1NAME
2 Class::XSAccessor - Generate fast XS accessors without runtime
3 compilation
4
5SYNOPSIS
6 package MyClass;
7 use Class::XSAccessor
8 replace => 1, # Replace existing methods (if any)
9 constructor => 'new',
10 getters => {
11 get_foo => 'foo', # 'foo' is the hash key to access
12 get_bar => 'bar',
13 },
14 setters => {
15 set_foo => 'foo',
16 set_bar => 'bar',
17 },
18 accessors => {
19 foo => 'foo',
20 bar => 'bar',
21 },
22 predicates => {
23 has_foo => 'foo',
24 has_bar => 'bar',
25 },
26 lvalue_accessors => { # see below
27 baz => 'baz', # ...
28 },
29 true => [ 'is_token', 'is_whitespace' ],
30 false => [ 'significant' ];
31
32 # The imported methods are implemented in fast XS.
33
34 # normal class code here.
35
36 As of version 1.05, some alternative syntax forms are available:
37
38 package MyClass;
39
40 # Options can be passed as a HASH reference, if preferred,
41 # which can also help Perl::Tidy to format the statement correctly.
42 use Class::XSAccessor {
43 # If the name => key values are always identical,
44 # the following shorthand can be used.
45 accessors => [ 'foo', 'bar' ],
46 };
47
48DESCRIPTION
49 Class::XSAccessor implements fast read, write and read/write accessors
50 in XS. Additionally, it can provide predicates such as "has_foo()" for
51 testing whether the attribute "foo" is defined in the object. It only
52 works with objects that are implemented as ordinary hashes.
53 Class::XSAccessor::Array implements the same interface for objects that
54 use arrays for their internal representation.
55
56 Since version 0.10, the module can also generate simple constructors
57 (implemented in XS). Simply supply the "constructor =>
58 'constructor_name'" option or the "constructors => ['new', 'create',
59 'spawn']" option. These constructors do the equivalent of the following
60 Perl code:
61
62 sub new {
63 my $class = shift;
64 return bless { @_ }, ref($class)||$class;
65 }
66
67 That means they can be called on objects and classes but will not clone
68 objects entirely. Parameters to "new()" are added to the object.
69
70 The XS accessor methods are between 3 and 4 times faster than typical
71 pure-Perl accessors in some simple benchmarking. The lower factor
72 applies to the potentially slightly obscure "sub set_foo_pp
73 {$_[0]->{foo} = $_[1]}", so if you usually write clear code, a factor of
74 3.5 speed-up is a good estimate. If in doubt, do your own benchmarking!
75
76 The method names may be fully qualified. The example in the synopsis
77 could have been written as "MyClass::get_foo" instead of "get_foo". This
78 way, methods can be installed in classes other than the current class.
79 See also: the "class" option below.
80
81 By default, the setters return the new value that was set, and the
82 accessors (mutators) do the same. This behaviour can be changed with the
83 "chained" option - see below. The predicates return a boolean.
84
85 Since version 1.01, "Class::XSAccessor" can generate extremely simple
86 methods which just return true or false (and always do so). If that
87 seems like a really superfluous thing to you, then consider a large
88 class hierarchy with interfaces such as PPI. These methods are provided
89 by the "true" and "false" options - see the synopsis.
90
91OPTIONS
92 In addition to specifying the types and names of accessors, additional
93 options can be supplied which modify behaviour. The options are
94 specified as key/value pairs in the same manner as the accessor
95 declaration. For example:
96
97 use Class::XSAccessor
98 getters => {
99 get_foo => 'foo',
100 },
101 replace => 1;
102
103 The list of available options is:
104
105 replace
106 Set this to a true value to prevent "Class::XSAccessor" from complaining
107 about replacing existing subroutines.
108
109 chained
110 Set this to a true value to change the return value of setters and
111 mutators (when called with an argument). If "chained" is enabled, the
112 setters and accessors/mutators will return the object. Mutators called
113 without an argument still return the value of the associated attribute.
114
115 As with the other options, "chained" affects all methods generated in
116 the same "use Class::XSAccessor ..." statement.
117
118 class
119 By default, the accessors are generated in the calling class. The the
120 "class" option allows the target class to be specified.
121
122LVALUES
123 Support for lvalue accessors via the keyword "lvalue_accessors" was
124 added in version 1.08. At this point, THEY ARE CONSIDERED HIGHLY
125 EXPERIMENTAL. Furthermore, their performance hasn't been benchmarked
126 yet.
127
128 The following example demonstrates an lvalue accessor:
129
130 package Address;
131 use Class::XSAccessor
132 constructor => 'new',
133 lvalue_accessors => { zip_code => 'zip' };
134
135 package main;
136 my $address = Address->new(zip => 2);
137 print $address->zip_code, "\n"; # prints 2
138 $address->zip_code = 76135; # <--- This is it!
139 print $address->zip_code, "\n"; # prints 76135
140
141CAVEATS
142 Probably won't work for objects based on *tied* hashes. But that's a
143 strange thing to do anyway.
144
145 Scary code exploiting strange XS features.
146
147 If you think writing an accessor in XS should be a laughably simple
148 exercise, then please contemplate how you could instantiate a new XS
149 accessor for a new hash key that's only known at run-time. Note that
150 compiling C code at run-time a la Inline::C is a no go.
151
152 Threading. With version 1.00, a memory leak has been fixed. Previously,
153 a small amount of memory would leak if "Class::XSAccessor"-based classes
154 were loaded in a subthread without having been loaded in the "main"
155 thread. If the subthread then terminated, a hash key and an int per
156 associated method used to be lost. Note that this mattered only if
157 classes were only loaded in a sort of throw-away thread.
158
159 In the new implementation, as of 1.00, the memory will still not be
160 released, in the same situation, but it will be recycled when the same
161 class, or a similar class, is loaded again in any thread.
162
163SEE ALSO
164 * Class::XSAccessor::Array
165
166 * AutoXS
167
168AUTHOR
169 Steffen Mueller <smueller@cpan.org>
170
171 chocolateboy <chocolate@cpan.org>
172
173COPYRIGHT AND LICENSE
174 Copyright (C) 2008, 2009, 2010, 2011, 2012 by Steffen Mueller
175
176 This library is free software; you can redistribute it and/or modify it
177 under the same terms as Perl itself, either Perl version 5.8 or, at your
178 option, any later version of Perl 5 you may have available.
179
180