1Class::XSAccessor(3)  User Contributed Perl Documentation Class::XSAccessor(3)
2
3
4

NAME

6       Class::XSAccessor - Generate fast XS accessors without runtime
7       compilation
8

SYNOPSIS

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
41         # The imported methods are implemented in fast XS.
42
43         # normal class code here.
44
45       As of version 1.05, some alternative syntax forms are available:
46
47         package MyClass;
48
49         # 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

DESCRIPTION

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
66       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
72         sub new {
73           my $class = shift;
74           return bless { @_ }, ref($class)||$class;
75         }
76
77       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
80       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
87       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
92       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
96       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
102       "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

OPTIONS

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
113         use Class::XSAccessor
114           getters => {
115             get_foo => 'foo',
116           },
117           replace => 1;
118
119       The list of available options is:
120
121   replace
122       Set this to a true value to prevent "Class::XSAccessor" from
123       complaining about replacing existing subroutines.
124
125   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
131       As with the other options, "chained" affects all methods generated in
132       the same "use Class::XSAccessor ..." statement.
133
134   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

LVALUES

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
144       The following example demonstrates an lvalue accessor:
145
146         package Address;
147         use Class::XSAccessor
148           constructor => 'new',
149           lvalue_accessors => { zip_code => 'zip' };
150
151         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

CAVEATS

158       Probably won't work for objects based on tied hashes. But that's a
159       strange thing to do anyway.
160
161       Scary code exploiting strange XS features.
162
163       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
168       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
175       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

SEE ALSO

180       •   Class::XSAccessor::Array
181
182       •   AutoXS
183

AUTHOR

185       Steffen Mueller <smueller@cpan.org>
186
187       chocolateboy <chocolate@cpan.org>
188
190       Copyright (C) 2008, 2009, 2010, 2011, 2012, 2013 by Steffen Mueller
191
192       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.
195
196
197
198perl v5.38.0                      2023-07-20              Class::XSAccessor(3)
Impressum