6 Moose::Cookbook::Recipe3 - A lazy B<BinaryTree> example
15 has 'node' => (is => 'rw', isa => 'Any');
20 predicate => 'has_parent',
27 predicate => 'has_left',
29 default => sub { BinaryTree->new(parent => $_[0]) },
35 predicate => 'has_right',
37 default => sub { BinaryTree->new(parent => $_[0]) },
40 before 'right', 'left' => sub {
41 my ($self, $tree) = @_;
42 $tree->parent($self) if defined $tree;
47 In this recipe we take a closer look at attributes, and see how
48 some of their more advanced features can be used to create fairly
51 The class in this recipe is a classic binary tree, each node in the
52 tree is represented by an instance of the B<BinaryTree> class. Each
53 instance has a C<node> slot to hold an abitrary value, a C<right>
54 slot to hold the right node, a C<left> slot to hold the left node,
55 and finally a C<parent> slot to hold a reference back up the tree.
57 Now, lets start with the code, our first attribute is the C<node>
58 slot, defined as such:
60 has 'node' => (is => 'rw', isa => 'Any');
62 If you recall from the previous recipies, this slot will have a
63 read/write accessor generated for it, and has a type constraint on it.
64 The new item here is the type constraint of C<Any>. In the type
65 constraint heirarchy in L<Moose::Utils::TypeConstraints>, the C<Any>
66 constraint is the "root" of the hierarchy. It means exactly what it
67 says, it allows anything to pass. Now, you could just as easily of left
68 the C<isa> out, and left the C<node> slot unconstrainted and gotten the
69 same behavior. But here, we are really including the type costraint
70 for the benefit of other programmers, not the computer. It makes
71 clear my intent that the C<node> can be of any type, and that the
72 class is a polymorphic container. Next, lets move onto the C<parent>
78 predicate => 'has_parent',
82 As you already know from reading the previous recipes, this code
83 tells you that C<parent> gets a read/write accessor, is constrainted
84 to only accept instances of B<BinaryTree>. You will of course remember
85 from the second recipe that the C<BinaryTree> type constraint is
86 automatically created for us by Moose.
88 The next attribute option is new though, the C<predicate> option.
89 This option creates a method, which can be used to check to see if
90 a given slot (in this case C<parent>) has a defined value in it. In
91 this case it will create a method called C<has_parent>. Quite simple,
92 and also quite handy too.
94 This brings us to our last attribute, and also a new one. Since the
95 C<parent> is a circular reference (the tree in C<parent> should
96 already have a reference in either it's C<left> or C<right> nodes),
97 we want to make sure that it is also a weakened reference to avoid
98 memory leaks. The C<weak_ref> attribute option will do just that,
99 C<weak_ref> simply takes a boolean value (C<1> or C<0>) and it will
100 then add the extra capability to the accessor function to weaken
101 the reference of any value stored in the C<parent> slot (1).
103 Now, onto the C<left> and C<right> attributes. They are essentially
104 the same things, only with different names, so I will just describe
110 predicate => 'has_left',
112 default => sub { BinaryTree->new(parent => $_[0]) },
115 You already know what the C<is>, C<isa> and C<>predicate> options
116 do, but now we have two more new options. These two options are
117 actually linked together, in fact, you cannot use the C<lazy>
118 option unless you have set the C<default> option. The class
119 creation will fail with an exception (2).
121 Before I go into detail about how C<lazy> works, let me first
122 explain how C<default> works, and in particular why it is wrapped
125 In the second recipe the B<BankAccount>'s C<balance> slot had a
126 default value of C<0>. Since Perl will copy strings and numbers
127 by value, this was all we had to say. But for any other item
128 (ARRAY ref, HASH ref, object instance, etc) Perl will copy by
129 reference. This means that if I were to do this:
131 has 'foo' => (is => 'rw', default => []);
133 Every single instance of that class would get a pointer to the
134 same ARRAY ref in their C<foo> slot. This is almost certainly
135 B<not> the behavior you intended. So, the solution is to wrap
136 these defaults into an anon-sub, like so:
138 has 'foo' => (is => 'rw', default => sub { [] });
140 This assures that each instance of this class will get it's own
141 ARRAY ref in the C<foo> slot.
143 One other feature of the sub ref version of the C<default> option
144 is that when the subroutine is executed (to get back the expected
145 default value), we also pass in the instance where the slot will
146 be stored. This added feature can come in quite handy at times, as
147 is illustrated above, with this code:
149 default => sub { BinaryTree->new(parent => $_[0]) },
151 The default value being generated is a new C<BinaryTree> instance
152 for the C<left> (or C<right>) slot. Here we set up the parental
153 relationship by passing the current instance to the constructor.
155 Now, before we go on to the C<lazy> option, I want you to think
156 for a moment. When an instance of this class is created, and the
157 slots are being initialized, the "normal" behavior would be for
158 the C<left> and C<right> slots to be populated with a new instance
159 of B<BinaryTree>. In creating that instance of the C<left> or
160 C<right> slots, we would need to create new instances to populate
161 the C<left> and C<right> slots of I<those> instances. This would
162 continue in an I<infinitely recursive spiral of death> until you had
163 exhausted all available memory on your machine.
165 This is, of course, not good :)
167 Which brings us to the C<lazy> attribute option. The C<lazy> option
168 does just what it says. It lazily initializes the slot within the
169 instance. This means that it waits till the I<absolute> last possible
170 moment to populate the slot. This means that if you, the user, write
171 to the slot, everything happens as normal and what you pass in is stored.
172 However, if you I<read> the slot, then at that I<exact> moment (and no
173 sooner), the slot will be populated with the value of the C<default>
176 This option is what allows the B<BinaryTree> class to instantiate
177 objects without fear of the I<infinitely recursive spiral of death>
180 So, we have descibed a quite complex set of behaviors here, and not
181 one method has needed to be written. But wait, we can't get away that
182 easily. The autogenerated C<right> and C<left> accessors are not
183 completely correct. They will not install the parental relationships
184 that we need. We could write our own accessors, but that would require
185 us to implement all those features we got automatically (the type
186 constraint, the lazy initialization, etc). So instead we use the
187 method modifiers again.
189 before 'right', 'left' => sub {
190 my ($self, $tree) = @_;
191 $tree->parent($self) if defined $tree;
194 This is a C<before> modifier, just like we saw in the second recipe,
195 but with two slight differences. First, we are applying this to more
196 than one method at a time. Since both the C<left> and C<right> methods
197 need the same feature, it makes sense. The second difference is that
198 we are not wrapping an inherited method anymore, but instead a method
199 of our own local class. Wrapping local methods is no different, the
200 only requirement is that the wrappee be created before the wrapper
201 (after all, you cannot wrap something which doesn't exist right?).
203 Now, as with all the other recipes, you can go about using
204 B<BinaryTree> like any other Perl 5 class. A more detailed example of
205 usage can be found in F<t/003_recipe.t>.
209 This recipe introduced you to some of the more advanced behavioral
210 possibilities of Moose's attribute mechanism. I hope that it has
211 opened your mind to the powerful possibilities of Moose. In the next
212 recipe we explore how we can create custom subtypes and take
213 advantage of the plethora of useful modules out on CPAN with Moose.
221 Weak references are tricky things, and should be used sparingly
222 and appropriately (such as in the case of circular refs). If you
223 are not careful, you will have slot values disappear "mysteriously"
224 because perls reference counting garbage collector has gone and
225 removed the item you are weak-referencing.
227 In short, don't use them unless you know what you are doing :)
231 You I<can> use the C<default> option without the C<lazy> option if
232 you like, as we showed in the second recipe.
238 Stevan Little E<lt>stevan@iinteractive.comE<gt>
240 =head1 COPYRIGHT AND LICENSE
242 Copyright 2006 by Infinity Interactive, Inc.
244 L<http://www.iinteractive.com>
246 This library is free software; you can redistribute it and/or modify
247 it under the same terms as Perl itself.