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 => {
27 has_foo => 'foo',
28 has_bar => 'bar',
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 preferred,
42 # which can also help Perl::Tidy to format the statement correctly.
43 use Class::XSAccessor {
44 # If the name => key values are always identical,
45 # the following shorthand can be used.
46 accessors => [ 'foo', 'bar' ],
47 };
48
50 Class::XSAccessor implements fast read, write and read/write accessors
51 in XS. Additionally, it can provide predicates such as "has_foo()" for
52 testing whether the attribute "foo" is defined in the object. It only
53 works with objects that are implemented as ordinary hashes.
54 Class::XSAccessor::Array implements the same interface for objects that
55 use arrays for their internal representation.
56 Since version 0.10, the module can also generate simple constructors
58 (implemented in XS). Simply supply the "constructor =>
59 'constructor_name'" option or the "constructors => ['new', 'create',
60 'spawn']" option. These constructors do the equivalent of the
61 following Perl code:
62 sub new {
64 my $class = shift;
65 return bless { @_ }, ref($class)||$class;
66 }
67 That means they can be called on objects and classes but will not clone
69 objects entirely. Parameters to "new()" are added to the object.
70 The XS accessor methods are between 2 and 3 times faster than typical
72 pure-Perl accessors in some simple benchmarking. The lower factor
73 applies to the potentially slightly obscure "sub set_foo_pp
74 {$_[0]->{foo} = $_[1]}", so if you usually write clear code, a factor
75 of 2.5 speed-up is a good estimate.
76 The method names may be fully qualified. The example in the synopsis
78 could have been written as "MyClass::get_foo" instead of "get_foo".
79 This way, methods can be installed in classes other than the current
80 class. See also: the "class" option below.
81 By default, the setters return the new value that was set, and the
83 accessors (mutators) do the same. This behaviour can be changed with
84 the "chained" option - see below. The predicates return a boolean.
85 Since version 1.01, "Class::XSAccessor" can generate extremely simple
87 methods which just return true or false (and always do so). If that
88 seems like a really superfluous thing to you, then consider a large
89 class hierarchy with interfaces such as PPI. These methods are provided
90 by the "true" and "false" options - see the synopsis.
91
93 In addition to specifying the types and names of accessors, additional
94 options can be supplied which modify behaviour. The options are
95 specified as key/value pairs in the same manner as the accessor
96 declaration. For example:
97 use Class::XSAccessor
99 getters => {
100 get_foo => 'foo',
101 },
102 replace => 1;
103 The list of available options is:
105 replace
107 Set this to a true value to prevent "Class::XSAccessor" from
108 complaining about replacing existing subroutines.
109 chained
111 Set this to a true value to change the return value of setters and
112 mutators (when called with an argument). If "chained" is enabled, the
113 setters and accessors/mutators will return the object. Mutators called
114 without an argument still return the value of the associated attribute.
115 As with the other options, "chained" affects all methods generated in
117 the same "use Class::XSAccessor ..." statement.
118 class
120 By default, the accessors are generated in the calling class. The the
121 "class" option allows the target class to be specified.
122
124 Probably won't work for objects based on tied hashes. But that's a
125 strange thing to do anyway.
126 Scary code exploiting strange XS features.
128 If you think writing an accessor in XS should be a laughably simple
130 exercise, then please contemplate how you could instantiate a new XS
131 accessor for a new hash key that's only known at run-time. Note that
132 compiling C code at run-time a la Inline::C is a no go.
133 Threading. With version 1.00, a memory leak has been fixed. Previously,
135 a small amount of memory would leak if "Class::XSAccessor"-based
136 classes were loaded in a subthread without having been loaded in the
137 "main" thread. If the subthread then terminated, a hash key and an int
138 per associated method used to be lost. Note that this mattered only if
139 classes were only loaded in a sort of throw-away thread.
140 In the new implementation, as of 1.00, the memory will still not be
142 released, in the same situation, but it will be recycled when the same
143 class, or a similar class, is loaded again in any thread.
144
146 · Class::XSAccessor::Array
147 · AutoXS
149
151 Steffen Mueller <smueller@cpan.org>
152 Chocolateboy <chocolate@cpan.org>
154
156 Copyright (C) 2008-2009 by Steffen Mueller
157 This library is free software; you can redistribute it and/or modify it
159 under the same terms as Perl itself, either Perl version 5.8 or, at
160 your option, any later version of Perl 5 you may have available.
161perl v5.12.1 2010-08-15 Class::XSAccessor(3)