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