Remove nothingmuch's nasty tabs ;)

[gitmo/Moose.git] / lib / Moose / Cookbook / Recipe7.pod

diff --git a/lib/Moose/Cookbook/Recipe7.pod b/lib/Moose/Cookbook/Recipe7.pod
index c54d39a..44b5c62 100644 (file)
--- a/lib/Moose/Cookbook/Recipe7.pod
+++ b/lib/Moose/Cookbook/Recipe7.pod
@@ -3,84 +3,59 @@
 
 =head1 NAME
 
-Moose::Cookbook::Recipe7 - The augment/inner example
+Moose::Cookbook::Recipe7 - Making Moose fast with immutable
 
 =head1 SYNOPSIS
-    
-  package Document::Page;
-  use Moose;
-  
-  has 'body' => (is => 'rw', isa => 'Str', default => sub {''});
-  
-  sub create {
-      my $self = shift;
-      $self->open_page;
-      inner();
-      $self->close_page;
-  }
-  
-  sub append_body { 
-      my ($self, $appendage) = @_;
-      $self->body($self->body . $appendage);
-  }
-  
-  sub open_page  { (shift)->append_body('<page>') }
-  sub close_page { (shift)->append_body('</page>') }  
-  
-  package Document::PageWithHeadersAndFooters;
-  use Moose;
-  
-  extends 'Document::Page';
-  
-  augment 'create' => sub {
-      my $self = shift;
-      $self->create_header;
-      inner();
-      $self->create_footer;
-  };
-  
-  sub create_header { (shift)->append_body('<header/>') }
-  sub create_footer { (shift)->append_body('<footer/>') }  
-  
-  package TPSReport;
+
+  package Point;
   use Moose;
-  
-  extends 'Document::PageWithHeadersAndFooters';
-  
-  augment 'create' => sub {
-      my $self = shift;
-      $self->create_tps_report;
-  };
-  
-  sub create_tps_report {
-     (shift)->append_body('<report type="tps"/>') 
-  }
-  
-  print TPSReport->new->create # <page><header/><report type="tps"/><footer/></page>
+
+  has 'x' => (isa => 'Int', is => 'ro');
+  has 'y' => (isa => 'Int', is => 'rw');
+
+  __PACKAGE__->meta->make_immutable;
 
 =head1 DESCRIPTION
 
-Coming Soon.
+The Moose metaclass API provides a method C<make_immutable()>. At a
+high level, this calling this method does two things to your
+class. One, it makes it faster. In particular, object construction and
+accessors are effectively "inlined" in your class, and no longer go
+through the meta-object system.
 
-=head1 CONCLUSION
+Second, you can no longer make changes via the metaclass API such as
+adding attributes. In practice, this won't be a problem, as you don't
+usually need to do this at runtime after first loading the class.
+
+=head2 Immutabilization and C<new()>
+
+If you override C<new()> in your class, then the immutabilization code
+will not be able to provide an optimized constructor for your
+class. Instead, consider providing a C<BUILD()> method. You can
+probably do the same thing in a C<BUILD()> method.
 
-=head1 FOOTNOTES
+Alternately, if you really need to provide a different C<new()>, you
+can also provide your own immutabilization method.
 
-=over 4
+Discussing this is beyond the scope of this recipe, however.
+
+=head1 CONCLUSION
 
-=back
+We strongly recommend you make your classes immutable. It makes your
+code much faster, basically for free. This will be especially
+noticeable when creating many objects or calling accessors frequently.
 
 =head1 AUTHOR
 
-Stevan Little E<lt>stevan@iinteractive.comE<gt>
+Dave Rolsky E<lt>autarch@urth.orgE<gt>
 
 =head1 COPYRIGHT AND LICENSE
 
-Copyright 2007 by Infinity Interactive, Inc.
+Copyright 2006-2008 by Infinity Interactive, Inc.
 
 L<http://www.iinteractive.com>
 
 This library is free software; you can redistribute it and/or modify
 it under the same terms as Perl itself.
 
-=cut       
+=cut