NAME

Moose::Cookbook::Recipe3 - A lazy BinaryTree example

SYNOPSIS

  package BinaryTree;
  use Moose;
  
  has 'node' => (is => 'rw', isa => 'Any');
  
  has 'parent' => (
      is        => 'rw',
      isa       => 'BinaryTree',        
      predicate => 'has_parent',
      weak_ref  => 1,
  );
  
  has 'left' => (
      is        => 'rw',        
      isa       => 'BinaryTree',                
      predicate => 'has_left',  
      lazy      => 1,
      default   => sub { BinaryTree->new(parent => $_[0]) },       
  );
  
  has 'right' => (
      is        => 'rw',        
      isa       => 'BinaryTree',                
      predicate => 'has_right',   
      lazy      => 1,       
      default   => sub { BinaryTree->new(parent => $_[0]) },       
  );
  
  before 'right', 'left' => sub {
      my ($self, $tree) = @_;
      $tree->parent($self) if defined $tree;   
  };

DESCRIPTION

In this recipe we take a closer look at attributes, and see how some of their more advanced features can be used to create fairly complex behaviors.

The class in this recipe is a classic binary tree, each node in the tree is represented by an instance of the BinaryTree class. Each instance has a node slot to hold an abitrary value, a right slot to hold the right node, a left slot to hold the left node, and finally a parent slot to hold a reference back up the tree.

Now, let's start with the code, our first attribute is the node slot, defined as such:

  has 'node' => (is => 'rw', isa => 'Any');

If you recall from the previous recipies, this slot will have a read/write accessor generated for it, and has a type constraint on it. The new item here is the type constraint of Any. In the type constraint heirarchy in Moose::Utils::TypeConstraints, the Any constraint is the "root" of the hierarchy. It means exactly what it says, it allows anything to pass. Now, you could just as easily have left out the isa, left the node slot unconstrained and gotten the same behavior. But here, we are really including the type constraint for the benefit of other programmers, not the computer. It makes clear my intent that the node can be of any type, and that the class is a polymorphic container. Next, lets move onto the parent slot.

  has 'parent' => (
      is        => 'rw',
      isa       => 'BinaryTree',        
      predicate => 'has_parent',
      weak_ref  => 1,
  );

As you already know from reading the previous recipes, this code tells you that parent gets a read/write accessor and is constrained to only accept instances of BinaryTree. You will of course remember from the second recipe that the BinaryTree type constraint is automatically created for us by Moose.

The next attribute option is new though, the predicate option. This option creates a method, which can be used to check to see if a given slot (in this case parent) has a defined value in it. In this case it will create a method called has_parent. Quite simple, and also quite handy too.

This brings us to our last attribute, and also a new one. Since the parent is a circular reference (the tree in parent should already have a reference in either it's left or right nodes), we want to make sure that it is also a weakened reference to avoid memory leaks. The weak_ref attribute option will do just that, weak_ref simply takes a boolean value (1 or 0) and it will then add the extra capability to the accessor function to weaken the reference of any value stored in the parent slot (1).

Now, onto the left and right attributes. They are essentially the same things, only with different names, so I will just describe one here.

  has 'left' => (
      is        => 'rw',        
      isa       => 'BinaryTree',                
      predicate => 'has_left',  
      lazy      => 1,
      default   => sub { BinaryTree->new(parent => $_[0]) },       
  );

You already know what the is, isa and predicate options do, but now we have two more new options. These two options are actually linked together, in fact, you cannot use the lazy option unless you have set the default option. The class creation will fail with an exception (2).

Before I go into detail about how lazy works, let me first explain how default works, and in particular why it is wrapped in a CODE ref.

In the second recipe the BankAccount's balance slot had a default value of 0. Since Perl will copy strings and numbers by value, this was all we had to say. But for any other item (ARRAY ref, HASH ref, object instance, etc) you would need to wrap this into a CODE reference, so this:

  has 'foo' => (is => 'rw', default => []);

is actually illegal in Moose. Instead, what you really want is to do this:

  has 'foo' => (is => 'rw', default => sub { [] });

This assures that each instance of this class will get it's own ARRAY ref in the foo slot.

One other feature of the sub ref version of the default option is that when the subroutine is executed (to get back the expected default value), we also pass in the instance where the slot will be stored. This added feature can come in quite handy at times, as is illustrated above, with this code:

  default => sub { BinaryTree->new(parent => $_[0]) },

The default value being generated is a new BinaryTree instance for the left (or right) slot. Here we set up the parental relationship by passing the current instance to the constructor.

Now, before we go on to the lazy option, I want you to think for a moment. When an instance of this class is created, and the slots are being initialized, the "normal" behavior would be for the left and right slots to be populated with a new instance of BinaryTree. In creating that instance of the left or right slots, we would need to create new instances to populate the left and right slots of those instances. This would continue in an infinitely recursive spiral of death until you had exhausted all available memory on your machine.

This is, of course, not good :)

Which brings us to the lazy attribute option. The lazy option does just what it says. It lazily initializes the slot within the instance. This means that it waits till the absolute last possible moment to populate the slot. This means that if you, the user, write to the slot, everything happens as normal and what you pass in is stored. However, if you read the slot, then at that exact moment (and no sooner), the slot will be populated with the value of the default option.

This option is what allows the BinaryTree class to instantiate objects without fear of the infinitely recursive spiral of death mentioned earlier.

So, we have described a quite complex set of behaviors here, and not one method had to be written. But wait, we can't get away that easily. The autogenerated right and left accessors are not completely correct. They will not install the parental relationships that we need. We could write our own accessors, but that would require us to implement all those features we got automatically (the type constraint, the lazy initialization, etc). So instead we use the method modifiers again.

  before 'right', 'left' => sub {
      my ($self, $tree) = @_;
      $tree->parent($self) if defined $tree;   
  };

This is a before modifier, just like we saw in the second recipe, but with two slight differences. First, we are applying this to more than one method at a time. Since both the left and right methods need the same feature, it makes sense. The second difference is that we are not wrapping an inherited method anymore, but instead a method of our own local class. Wrapping local methods is no different, the only requirement is that the wrappee be created before the wrapper (after all, you cannot wrap something which doesn't exist right?).

Now, as with all the other recipes, you can go about using BinaryTree like any other Perl 5 class. A more detailed example of usage can be found in t/003_recipe.t.

CONCLUSION

This recipe introduced you to some of the more advanced behavioral possibilities of Moose's attribute mechanism. I hope that it has opened your mind to the powerful possibilities of Moose. In the next recipe we explore how we can create custom subtypes and take advantage of the plethora of useful modules out on CPAN with Moose.

FOOTNOTES

(1)

Weak references are tricky things, and should be used sparingly and appropriately (such as in the case of circular refs). If you are not careful, you will have slot values disappear "mysteriously" because perls reference counting garbage collector has gone and removed the item you are weak-referencing.

In short, don't use them unless you know what you are doing :)

(2)

You can use the default option without the lazy option if you like, as we showed in the second recipe.

AUTHOR

Stevan Little <stevan@iinteractive.com>

COPYRIGHT AND LICENSE

Copyright 2006 by Infinity Interactive, Inc.

http://www.iinteractive.com

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

cpanm Moose

perl -MCPAN -e shell
install Moose