Class::XSAccessor::Array(3pm)

1Class::XSAccessor::ArraUys(e3r)Contributed Perl DocumentCaltaisosn::XSAccessor::Array(3)
2
3
4

NAME

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

SYNOPSIS

10         package MyClassUsingArraysAsInternalStorage;
11         use Class::XSAccessor::Array
12           constructor => 'new',
13           getters => {
14             get_foo => 0, # 0 is the array index to access
15             get_bar => 1,
16           },
17           setters => {
18             set_foo => 0,
19             set_bar => 1,
20           },
21           accessors => { # a mutator
22             buz => 2,
23           },
24           predicates => { # test for definedness
25             has_buz => 2,
26           },
27           lvalue_accessors => { # see below
28             baz => 3,
29           },
30           true => [ 'is_token', 'is_whitespace' ],
31           false => [ 'significant' ];
32
33         # The imported methods are implemented in fast XS.
34
35         # normal class code here.
36
37       As of version 1.05, some alternative syntax forms are available:
38
39         package MyClass;
40
41         # Options can be passed as a HASH reference if you prefer it,
42         # which can also help PerlTidy to flow the statement correctly.
43         use Class::XSAccessor {
44           getters => {
45             get_foo => 0,
46             get_bar => 1,
47           },
48         };
49

DESCRIPTION

51       The module implements fast XS accessors both for getting at and setting
52       an object attribute. Additionally, the module supports mutators and
53       simple predicates ("has_foo()" like tests for definedness of an
54       attributes).  The module works only with objects that are implemented
55       as arrays. Using it on hash-based objects is bound to make your life
56       miserable. Refer to Class::XSAccessor for an implementation that works
57       with hash-based objects.
58
59       A simple benchmark showed a significant performance advantage over
60       writing accessors in Perl.
61
62       Since version 0.10, the module can also generate simple constructors
63       (implemented in XS) for you. Simply supply the "constructor =>
64       'constructor_name'" option or the "constructors => ['new', 'create',
65       'spawn']" option.  These constructors do the equivalent of the
66       following Perl code:
67
68         sub new {
69           my $class = shift;
70           return bless [], ref($class)||$class;
71         }
72
73       That means they can be called on objects and classes but will not clone
74       objects entirely. Note that any parameters to new() will be discarded!
75       If there is a better idiom for array-based objects, let me know.
76
77       While generally more obscure than hash-based objects, objects using
78       blessed arrays as internal representation are a bit faster as its
79       somewhat faster to access arrays than hashes.  Accordingly, this module
80       is slightly faster (~10-15%) than Class::XSAccessor, which works on
81       hash-based objects.
82
83       The method names may be fully qualified. In the example of the
84       synopsis, you could have written "MyClass::get_foo" instead of
85       "get_foo". This way, you can install methods in classes other than the
86       current class. See also: The "class" option below.
87
88       Since version 1.01, you can generate extremely simple methods which
89       just return true or false (and always do so). If that seems like a
90       really superfluous thing to you, then think of a large class hierarchy
91       with interfaces such as PPI. This is implemented as the "true" and
92       "false" options, see synopsis.
93

OPTIONS

95       In addition to specifying the types and names of accessors, you can add
96       options which modify behaviour. The options are specified as key/value
97       pairs just as the accessor declaration. Example:
98
99         use Class::XSAccessor::Array
100           getters => {
101             get_foo => 0,
102           },
103           replace => 1;
104
105       The list of available options is:
106
107   replace
108       Set this to a true value to prevent "Class::XSAccessor::Array" from
109       complaining about replacing existing subroutines.
110
111   chained
112       Set this to a true value to change the return value of setters and
113       mutators (when called with an argument).  If "chained" is enabled, the
114       setters and accessors/mutators will return the object. Mutators called
115       without an argument still return the value of the associated attribute.
116
117       As with the other options, "chained" affects all methods generated in
118       the same "use Class::XSAccessor::Array ..." statement.
119
120   class
121       By default, the accessors are generated in the calling class. Using the
122       "class" option, you can explicitly specify where the methods are to be
123       generated.
124

LVALUES

126       Support for lvalue accessors via the keyword "lvalue_accessors" was
127       added in version 1.08. At this point, THEY ARE CONSIDERED HIGHLY
128       EXPERIMENTAL. Furthermore, their performance hasn't been benchmarked
129       yet.
130
131       The following example demonstrates an lvalue accessor:
132
133         package Address;
134         use Class::XSAccessor
135           constructor => 'new',
136           lvalue_accessors => { zip_code => 0 };
137
138         package main;
139         my $address = Address->new(2);
140         print $address->zip_code, "\n"; # prints 2
141         $address->zip_code = 76135; # <--- This is it!
142         print $address->zip_code, "\n"; # prints 76135
143

CAVEATS

145       Probably wouldn't work if your objects are tied. But that's a strange
146       thing to do anyway.
147
148       Scary code exploiting strange XS features.
149
150       If you think writing an accessor in XS should be a laughably simple
151       exercise, then please contemplate how you could instantiate a new XS
152       accessor for a new hash key or array index that's only known at run-
153       time. Note that compiling C code at run-time a la Inline::C is a no go.
154
155       Threading. With version 1.00, a memory leak has been fixed that would
156       leak a small amount of memory if you loaded "Class::XSAccessor"-based
157       classes in a subthread that hadn't been loaded in the "main" thread
158       before. If the subthread then terminated, a hash key and an int per
159       associated method used to be lost. Note that this mattered only if
160       classes were only loaded in a sort of throw-away thread.
161
162       In the new implementation as of 1.00, the memory will not be released
163       again either in the above situation. But it will be recycled when the
164       same class or a similar class is loaded again in any thread.
165

AUTHOR

172       Steffen Mueller <smueller@cpan.org>
173
174       chocolateboy <chocolate@cpan.org>
175

COPYRIGHT AND LICENSE

177       Copyright (C) 2008, 2009, 2010, 2011, 2012, 2013 by Steffen Mueller
178
179       This library is free software; you can redistribute it and/or modify it
180       under the same terms as Perl itself, either Perl version 5.8 or, at
181       your option, any later version of Perl 5 you may have available.
182
183
184
185perl v5.34.0                      2021-07-22       Class::XSAccessor::Array(3)