Current version is 1.08.
Distribution from this site.
CPAN site
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 => {
has_foo => 'foo',
has_bar => 'bar',
}
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 you prefer it,
# which can also help PerlTidy to flow the statement correctly.
use Class::XSAccessor {
# If the name => key values are always identical,
# you can use the following shorthand.
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" is defined in 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) for you. 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 2.6 and 3.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
two speed-up is a good estimate.
The method names may be fully qualified. In the example of the synopsis,
you could have written "MyClass::get_foo" instead of "get_foo". This
way, you can install methods 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. You can change this behaviour with the
"chained" option, see below. The predicates obviously return a boolean.
Since version 1.01, you 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. This is implemented as the "true" and "false"
options, see synopsis.
OPTIONS
In addition to specifying the types and names of accessors, you can add
options which modify behaviour. The options are specified as key/value
pairs just as the accessor declaration. 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. Using the
"class" option, you can explicitly specify where the methods are to be
generated.
CAVEATS
Probably wouldn't work if your objects are *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 that would
leak a small amount of memory if you loaded "Class::XSAccessor"-based
classes in a subthread that hadn't been loaded in the "main" thread
before. If the subthread then terminated, a hash key and an int per
associated method used ot 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 not be released
again either in the above situation. But it will be recycled when the
same class or a similar class is loaded again in any thread.
SEE ALSO
Class::XSAccessor::Array
AutoXS
AUTHOR
Steffen Mueller
chocolateboy
COPYRIGHT AND LICENSE
Copyright (C) 2008-2010 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.
Class::XSAccessor
Class::XSAccessor::Heavy
Class::XSAccessor::Array
Revision history for Perl extension Class-XSAccessor.
1.08 Fri Sep 17 20:30 2010
- Promote latest development release to a stable release.
1.07_04 Sun Sep 12 10:30 2010
- Since WIN32 doesn't have the PERL_CORE optimization,
it gets the PERL_NO_GET_CONTEXT optimization back.
- Add threading test that would previously crash on win32
and perls compiled with track-mempool.
- Use the system's malloc/etc for the shared memory, not perl's.
1.07_03 Thu Sep 9 20:30 2010
- Minor constructor optimization/cleanup.
- Various built-time warning fixes.
- PERL_CORE optimization now disabled on WIN32.
- Class::Accessor::Fast compatibility code added (not
for public consumption!)
- Clear requirement of Perl 5.8 everywhere.
- Fix minor (constant as in O(1)) memory leak.
1.07_02 Mon Aug 23 20:30 2010
- Various warning fixes and small cleanups over previous
dev. version.
1.07_01 Wed Aug 18 20:30 2010
- Experimental support for lvalue accessors:
$obj->foo = 12
1.07 Sun Aug 15 14:41 2010
- Include two new test files for the fix in 1.06.
- Define PERL_CORE, but *only* while including XSUB.h to get
a significant speed-up (see XSAccessor.xs for an explanation).
Idea from chocolateboy. Complaints from rightfully annoyed
perl5-porters (in particular but not limited to Nicholas)
go to Steffen.
1.06 Sat Aug 14 20:21 2010
- Add sanity checks to make sure we don't segfault on
invalid invocants (chocolateboy)
1.05 Sun Nov 15 12:54 2009
- Minor developer doc tweaks.
- Minor XS refactoring
1.04_05 Mon Nov 9 20:10 2009
- Fixes for perls < 5.10:
=> No entersub optimization
=> Do no use precalculated hashes
- Updated entersub optimization
- Remove brain-damaged double-hashing
- Minor portability fixlets
1.04_04 Thu Nov 5 18:00 2009
- Fixes for non-threaded perls
(no need for locks, perl_mutex not even defined).
1.04_03 Tue Nov 3 22:32 2009
** This release features some very radical changes. Test well. **
- Replace use of perl hashes in the global hash key name storage with
a full-blown, separate implementation of a hash table
(Steffen, chocolateboy)
- Similarly, throw out the SV's for simple C strings.
- Add a global lock for all modifications to global data structures:
- The above three items fix RT #50454 (serious threading issues).
- Add support for alternate use Class::XSAccessor { ... } syntax
(Adam K)
1.04_02 Mon Sep 7 11:35 2009
** This release features some very radical changes. Test well. **
- Significant optimization by replacing the relevant entersub ops
with stripped down versions (chocolateboy)
1.04_01 Mon Sep 7 11:35 2009
** This release features some very radical changes. Test well. **
- More aggressive OPTIMIZE flags if possible (chocolateboy)
- Added shorthand syntax for getters, setters, accessors, and predicates
where the attribute has the same name as the method (chocolateboy)
- Remove dependency on AutoXS::Header.
- Merge Class::XSAccessor::Array into this distribution.
- Refactored the XS to remove duplicate code.
- Refactored the perl code in XSAccessor.pm and Array.pm to remove
duplicate code (=> Heavy.pm).
- Upgrade Devel::PPPort/ppport.h (chocolateboy)
1.04 Thu Jun 11 16:40 2009
- Fix a bunch of warnings thanks to a heads up from
Marcela Maslanova.
1.03 Sun May 31 18:45 2009
- Upgrade to AutoXS::Header 1.01: Make it C89!
1.02 Sun May 17 11:18 2009
- Require new AutoXS header version in order to fix
prototyping issue.
1.01 Sat May 16 16:11 2009
- XS boolean constants for PPI
1.00 Sat May 16 13:48 2009
- Implement new caching algorithm: Only recreate
the int => hash key association for new hash keys.
0.14 Tue Dec 9 21:06 2008
- Fix Makefile issue on Windows using nmake (Petar Shangov)
0.13 Thu Dec 4 15:06 2008
- Add predicate tests
- Fix some compiler warnings (Tom Heady)
0.12 Tue Dec 2 14:07 2008
- Compilation fix for Solaris cc. (Probably going half-way only.)
0.11 Sat Nov 29 21:37 2008
- Forgot to add more tests in previous release.
0.10 Sat Nov 29 21:17 2008
- Add generation of constructors.
0.09 Sat Nov 29 17:28 2008
- Add the class option to set the target class.
0.08 Fri Nov 21 12:17 2008
- Reduce code duplication.
- Fix for compilation issues on Solaris with Sun's cc.
0.07 Thu Aug 29 14:14 2008
- Documented the "replace" option.
- Added the "chained" option to generate chainable setters
and mutators.
0.06 Thu Aug 28 13:39 2008
- Copy input scalars on setter/mutator calls (RT #38573)
0.05 Sat Jun 21 18:06 2008
- Add read/write accessors. (chocolateboy)
- By default, return the new value from setters. (chocolateboy)
- Add predicates, i.e. "has_foo".
0.04 Mon May 3 19:12 2008
- Win32 support.
0.03 Mon May 3 19:12 2008
- Refer to Class::XSAccessor::Array for array based objects.
0.02 Mon Apr 3 17:12 2008
- Mention in the docs that fully qualified method names are
supported.
0.01 Mon Apr 3 17:09 2008
- original version as uploaded to CPAN.
(c) 2002-2010 Steffen Müller; All rights reserved.