lib/Moose/Cookbook/Recipe3.pod

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