1Class::XSAccessor::ArraUys(e3r)Contributed Perl DocumentCaltaisosn::XSAccessor::Array(3)
2
6 Class::XSAccessor::Array - Generate fast XS accessors without runtime
7 compilation
8
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 # The imported methods are implemented in fast XS.
34 # normal class code here.
36 As of version 1.05, some alternative syntax forms are available:
38 package MyClass;
40 # 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
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 A simple benchmark showed a significant performance advantage over
60 writing accessors in Perl.
61 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 sub new {
69 my $class = shift;
70 return bless [], ref($class)||$class;
71 }
72 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 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 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 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
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 use Class::XSAccessor::Array
100 getters => {
101 get_foo => 0,
102 },
103 replace => 1;
104 The list of available options is:
106 replace
108 Set this to a true value to prevent "Class::XSAccessor::Array" from
109 complaining about replacing existing subroutines.
110 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 As with the other options, "chained" affects all methods generated in
118 the same "use Class::XSAccessor::Array ..." statement.
119 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
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 The following example demonstrates an lvalue accessor:
132 package Address;
134 use Class::XSAccessor
135 constructor => 'new',
136 lvalue_accessors => { zip_code => 0 };
137 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
145 Probably wouldn't work if your objects are tied. But that's a strange
146 thing to do anyway.
147 Scary code exploiting strange XS features.
149 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 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 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
167 Class::XSAccessor
168 AutoXS
170
172 Steffen Mueller <smueller@cpan.org>
173 chocolateboy <chocolate@cpan.org>
175
177 Copyright (C) 2008, 2009, 2010, 2011, 2012, 2013 by Steffen Mueller
178 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.
182perl v5.28.0 2013-11-22 Class::XSAccessor::Array(3)