Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Class::XSAccessor(3)  User Contributed Perl Documentation Class::XSAccessor(3)

NAME
       Class::XSAccessor - Generate fast XS accessors without runtime
       compilation

SYNOPSIS
	 package MyClass;
	 use Class::XSAccessor
	   replace     => 1,   # Replace existing methods (if any)
	   constructor => 'new',
	   getters     => {
	     get_foo =>	'foo', # 'foo' is the hash key to access
	     get_bar =>	'bar',
	   },
	   setters => {
	     set_foo =>	'foo',
	     set_bar =>	'bar',
	   },
	   accessors =>	{
	     foo => 'foo',
	     bar => 'bar',
	   },
	   # "predicates" is an	alias for "defined_predicates"
	   defined_predicates => {
	     defined_foo => 'foo',
	     defined_bar => 'bar',
	   },
	   exists_predicates =>	{
	     has_foo =>	'foo',
	     has_bar =>	'bar',
	   },
	   lvalue_accessors => { # see below
	     baz => 'baz', # ...
	   },
	   true	 => [ 'is_token', 'is_whitespace' ],
	   false => [ 'significant' ];

	 # The imported	methods	are implemented	in fast	XS.

	 # normal class	code here.

       As of version 1.05, some	alternative syntax forms are available:

	 package MyClass;

	 # Options can be passed as a HASH reference, if preferred,
	 # which can also help Perl::Tidy to format the	statement correctly.
	 use Class::XSAccessor {
	    # If the name => key values	are always identical,
	    # the following shorthand can be used.
	    accessors => [ 'foo', 'bar'	],
	 };

DESCRIPTION
       Class::XSAccessor implements fast read, write and read/write accessors
       in XS.  Additionally, it	can provide predicates such as "has_foo()" for
       testing whether the attribute "foo" exists in the object	(which is
       different from "is defined within the object").	It only	works with
       objects that are	implemented as ordinary	hashes.
       Class::XSAccessor::Array	implements the same interface for objects that
       use arrays for their internal representation.

       Since version 0.10, the module can also generate	simple constructors
       (implemented in XS). Simply supply the "constructor =>
       'constructor_name'" option or the "constructors => ['new', 'create',
       'spawn']" option.  These	constructors do	the equivalent of the
       following Perl code:

	 sub new {
	   my $class = shift;
	   return bless	{ @_ },	ref($class)||$class;
	 }

       That means they can be called on	objects	and classes but	will not clone
       objects entirely. Parameters to "new()" are added to the	object.

       The XS accessor methods are between 3 and 4 times faster	than typical
       pure-Perl accessors in some simple benchmarking.	 The lower factor
       applies to the potentially slightly obscure "sub	set_foo_pp
       {$_[0]->{foo} = $_[1]}",	so if you usually write	clear code, a factor
       of 3.5 speed-up is a good estimate.  If in doubt, do your own
       benchmarking!

       The method names	may be fully qualified.	The example in the synopsis
       could have been written as "MyClass::get_foo" instead of	"get_foo".
       This way, methods can be	installed in classes other than	the current
       class. See also:	the "class" option below.

       By default, the setters return the new value that was set, and the
       accessors (mutators) do the same. This behaviour	can be changed with
       the "chained" option - see below. The predicates	return a boolean.

       Since version 1.01, "Class::XSAccessor" can generate extremely simple
       methods which just return true or false (and always do so). If that
       seems like a really superfluous thing to	you, then consider a large
       class hierarchy with interfaces such as PPI. These methods are provided
       by the "true" and "false" options - see the synopsis.

       "defined_predicates" check whether a given object attribute is defined.
       "predicates" is an alias	for "defined_predicates" for compatibility
       with older versions of "Class::XSAccessor". "exists_predicates" checks
       whether the given attribute exists in the object	using "exists".

OPTIONS
       In addition to specifying the types and names of	accessors, additional
       options can be supplied which modify behaviour. The options are
       specified as key/value pairs in the same	manner as the accessor
       declaration. For	example:

	 use Class::XSAccessor
	   getters => {
	     get_foo =>	'foo',
	   },
	   replace => 1;

       The list	of available options is:

   replace
       Set this	to a true value	to prevent "Class::XSAccessor" from
       complaining about replacing existing subroutines.

   chained
       Set this	to a true value	to change the return value of setters and
       mutators	(when called with an argument).	 If "chained" is enabled, the
       setters and accessors/mutators will return the object. Mutators called
       without an argument still return	the value of the associated attribute.

       As with the other options, "chained" affects all	methods	generated in
       the same	"use Class::XSAccessor ..." statement.

   class
       By default, the accessors are generated in the calling class. The the
       "class" option allows the target	class to be specified.

LVALUES
       Support for lvalue accessors via	the keyword "lvalue_accessors" was
       added in	version	1.08. At this point, THEY ARE CONSIDERED HIGHLY
       EXPERIMENTAL. Furthermore, their	performance hasn't been	benchmarked
       yet.

       The following example demonstrates an lvalue accessor:

	 package Address;
	 use Class::XSAccessor
	   constructor => 'new',
	   lvalue_accessors => { zip_code => 'zip' };

	 package main;
	 my $address = Address->new(zip	=> 2);
	 print $address->zip_code, "\n"; # prints 2
	 $address->zip_code = 76135; # <--- This is it!
	 print $address->zip_code, "\n"; # prints 76135

CAVEATS
       Probably	won't work for objects based on	tied hashes. But that's	a
       strange thing to	do anyway.

       Scary code exploiting strange XS	features.

       If you think writing an accessor	in XS should be	a laughably simple
       exercise, then please contemplate how you could instantiate a new XS
       accessor	for a new hash key that's only known at	run-time. Note that
       compiling C code	at run-time a la Inline::C is a	no go.

       Threading. With version 1.00, a memory leak has been fixed. Previously,
       a small amount of memory	would leak if "Class::XSAccessor"-based
       classes were loaded in a	subthread without having been loaded in	the
       "main" thread. If the subthread then terminated,	a hash key and an int
       per associated method used to be	lost. Note that	this mattered only if
       classes were only loaded	in a sort of throw-away	thread.

       In the new implementation, as of	1.00, the memory will still not	be
       released, in the	same situation,	but it will be recycled	when the same
       class, or a similar class, is loaded again in any thread.

SEE ALSO
       o   Class::XSAccessor::Array

       o   AutoXS

AUTHOR
       Steffen Mueller <smueller@cpan.org>

       chocolateboy <chocolate@cpan.org>

COPYRIGHT AND LICENSE
       Copyright (C) 2008, 2009, 2010, 2011, 2012, 2013	by Steffen Mueller

       This library is free software; you can redistribute it and/or modify it
       under the same terms as Perl itself, either Perl	version	5.8 or,	at
       your option, any	later version of Perl 5	you may	have available.

perl v5.24.1			  2013-11-22		  Class::XSAccessor(3)

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | LVALUES | CAVEATS | SEE ALSO | AUTHOR | COPYRIGHT AND LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Class::XSAccessor&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help