From: Stevan Little Date: Sun, 4 Mar 2007 16:03:50 +0000 (+0000) Subject: many doc updates X-Git-Tag: 0_19~21 X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=734d1752d36fa71901e772f16cd3e13e85220a2c;p=gitmo%2FMoose.git many doc updates --- diff --git a/Changes b/Changes index 91f5f5d..3670a78 100644 --- a/Changes +++ b/Changes @@ -10,8 +10,23 @@ Revision history for Perl extension Moose !! You must have Class::MOP 0.37_001 !! !! for this developer release to work !! - Lots of changes really, too numerous to mention now, - I need to have people test/fiddle with this first. + This release was primarily adding the immutable + feature to Moose. An immutable class is one which + you promise not to alter. When you set the class + as immutable it will perform various bits of + memoization and inline certain part of the code + (constructors, destructors and accessors). This + minimizes (and in some cases totally eliminates) + one of Moose's biggest performance hits. This + feature is not on by default, and is 100% optional. + It has several configurable bits as well, so you + can pick and choose to your specific needs. + + The changes involved in this were fairly wide and + highly specific, but 100% backwards compatible, so + I am not going to enumerate them here. If you are + truely interested in what was changed, please do + a diff :) 0.17 Tues. Nov. 14, 2006 * Moose::Meta::Method::Accessor diff --git a/benchmarks/caf_vs_moose.pl b/benchmarks/caf_vs_moose.pl index 55a3e0f..2634484 100644 --- a/benchmarks/caf_vs_moose.pl +++ b/benchmarks/caf_vs_moose.pl @@ -2,69 +2,65 @@ ### MODULES -package MooseHorse; -use Moose; -has foo => (is => 'rw'); -no Moose; - -package MooseHorseImmut; -use Moose; -has foo => (is => 'rw'); -__PACKAGE__->meta->make_immutable(); -no Moose; - -package MooseHorseImmutNoConst; -use Moose; -has foo => (is => 'rw'); -__PACKAGE__->meta->make_immutable(inline_constructor => 0); -no Moose; - - -package CAFHorse; -use warnings; -use strict; -use base 'Class::Accessor::Fast'; -__PACKAGE__->mk_accessors(qw(foo)); - - -package main; -use warnings; -use strict; +{ + package PlainMoose; + use Moose; + has foo => (is => 'rw'); +} +{ + package MooseImmutable; + use Moose; + has foo => (is => 'rw'); + __PACKAGE__->meta->make_immutable(); +} +{ + package MooseImmutable::NoConstructor; + use Moose; + has foo => (is => 'rw'); + __PACKAGE__->meta->make_immutable(inline_constructor => 0); +} +{ + package ClassAccessorFast; + use warnings; + use strict; + use base 'Class::Accessor::Fast'; + __PACKAGE__->mk_accessors(qw(foo)); +} use Benchmark qw(cmpthese); use Benchmark ':hireswallclock'; -my $moose = MooseHorse->new; -my $moose_immut = MooseHorseImmut->new; -my $moose_immut_no_const = MooseHorseImmutNoConst->new; -my $caf = CAFHorse->new; +my $moose = PlainMoose->new; +my $moose_immut = MooseImmutable->new; +my $moose_immut_no_const = MooseImmutable::NoConstructor->new; +my $caf = ClassAccessorFast->new; -my $acc_rounds = 1_000_000; -my $ins_rounds = 1_000_000; +my $acc_rounds = 100_000; +my $ins_rounds = 100_000; print "\nSETTING\n"; cmpthese($acc_rounds, { - Moose => sub { $moose->foo(23) }, - MooseImmut => sub { $moose_immut->foo(23) }, - MooseImmutNoConst => sub { $moose_immut_no_const->foo(23) }, - CAF => sub { $caf->foo(23) }, + Moose => sub { $moose->foo(23) }, + MooseImmutable => sub { $moose_immut->foo(23) }, + MooseImmutableNoConstructor => sub { $moose_immut_no_const->foo(23) }, + ClassAccessorFast => sub { $caf->foo(23) }, }, 'noc'); print "\nGETTING\n"; cmpthese($acc_rounds, { - Moose => sub { $moose->foo }, - MooseImmut => sub { $moose_immut->foo }, - MooseImmutNoConst => sub { $moose_immut_no_const->foo }, - CAF => sub { $caf->foo }, + Moose => sub { $moose->foo }, + MooseImmutable => sub { $moose_immut->foo }, + MooseImmutableNoConstructor => sub { $moose_immut_no_const->foo }, + ClassAccessorFast => sub { $caf->foo }, }, 'noc'); my (@moose, @moose_immut, @moose_immut_no_const, @caf_stall); print "\nCREATION\n"; cmpthese($ins_rounds, { - Moose => sub { push @moose, MooseHorse->new(foo => 23) }, - MooseImmut => sub { push @moose_immut, MooseHorseImmut->new(foo => 23) }, - MooseImmutNoConst => sub { push @moose_immut_no_const, MooseHorseImmutNoConst->new(foo => 23) }, - CAF => sub { push @caf_stall, CAFHorse->new({foo => 23}) }, + Moose => sub { push @moose, PlainMoose->new(foo => 23) }, + MooseImmutable => sub { push @moose_immut, MooseImmutable->new(foo => 23) }, + MooseImmutableNoConstructor => sub { push @moose_immut_no_const, MooseImmutable::NoConstructor->new(foo => 23) }, + ClassAccessorFast => sub { push @caf_stall, ClassAccessorFast->new({foo => 23}) }, }, 'noc'); my ( $moose_idx, $moose_immut_idx, $moose_immut_no_const_idx, $caf_idx ) = ( 0, 0, 0, 0 ); @@ -74,15 +70,15 @@ cmpthese($ins_rounds, { $moose[$moose_idx] = undef; $moose_idx++; }, - MooseImmut => sub { + MooseImmutable => sub { $moose_immut[$moose_immut_idx] = undef; $moose_immut_idx++; }, - MooseImmutNoConst => sub { + MooseImmutableNoConstructor => sub { $moose_immut_no_const[$moose_immut_no_const_idx] = undef; $moose_immut_no_const_idx++; }, - CAF => sub { + ClassAccessorFast => sub { $caf_stall[$caf_idx] = undef; $caf_idx++; }, diff --git a/lib/Moose.pm b/lib/Moose.pm index 95586ce..1eef1ea 100644 --- a/lib/Moose.pm +++ b/lib/Moose.pm @@ -289,18 +289,7 @@ Moose - A complete modern object system for Perl 5 after 'clear' => sub { my $self = shift; $self->z(0); - }; - -=head1 CAVEAT - -Moose is a rapidly maturing module, and is already being used by -a number of people. It's test suite is growing larger by the day, -and the docs should soon follow. - -This said, Moose is not yet finished, and should still be considered -to be evolving. Much of the outer API is stable, but the internals -are still subject to change (although not without serious thought -given to it). + }; =head1 DESCRIPTION @@ -319,13 +308,18 @@ for Perl 5. This means that Moose not only makes building normal Perl 5 objects better, but it also provides the power of metaclass programming. -=head2 Can I use this in production? Or is this just an experiment? +=head2 Is this for real? Or is this just an experiment? Moose is I on the prototypes and experiments I did for the Perl 6 meta-model; however Moose is B an experiment/prototype, it is -for B. I will be deploying Moose into production environments later -this year, and I have every intentions of using it as my de facto class -builder from now on. +for B. + +=head2 Can I, should I use this in production? + +I have two medium-to-large-ish web applications which use Moose heavily +and have been in production (without issue) for several months now. At +$work, we are re-writing our core offering in it. And several people on +#moose have been using it (in production) for several months now as well. =head2 Is Moose just Perl 6 in Perl 5? diff --git a/lib/Moose/Cookbook.pod b/lib/Moose/Cookbook.pod index bbf5afd..b85baa5 100644 --- a/lib/Moose/Cookbook.pod +++ b/lib/Moose/Cookbook.pod @@ -12,6 +12,9 @@ test suite. Each recipe presents some code, which demonstrates some of the features of Moose, and then proceeds to explain the details of the code. +We also provide a L and a L +for common questions and problems people have with Moose. + =head1 RECIPES =over 4 diff --git a/lib/Moose/Cookbook/FAQ.pod b/lib/Moose/Cookbook/FAQ.pod index 9201593..69f64a0 100644 --- a/lib/Moose/Cookbook/FAQ.pod +++ b/lib/Moose/Cookbook/FAQ.pod @@ -11,25 +11,16 @@ Moose::Cookbook::FAQ - Frequenty asked questions about Moose =head3 Is Moose "production ready"? -Yes and No. Currently I have one web application in production -using Moose, and at $work we are re-writing our core offering to -use Moose. Several other people on #moose either have sites in -production which use Moose, or are in the process of deploying -sites which use Moose. - -The biggest barrier to widespread use of Moose in production -right now is speed of development and speed of execution. - -Since development is still happening, regular upgrades are a -fact of life. This can be hairy in production, so if this makes -you quake with fear, you might want to wait a few months. - -Then comes speed of execution. In some ways, Moose is actually -pretty fast and makes great effort to stay out of your way when -you don't want it there. However, certain parts of Moose are -slow, such as compile time setup, introspection and object -construction (only because it uses introspection). See -L below for a deeper discussion on the subject. +Yes. I have two medium-to-large-ish web applications in +production using Moose, they have been running without +issue now for almost a year. + +At $work we are re-writing our core offering to use Moose, +so it's continued development is assured. + +Several other people on #moose either have apps in production +which use Moose, or are in the process of deploying sites +which use Moose. =head3 Is Moose's API stable? @@ -39,7 +30,7 @@ compatible>. The introspection API is I stable, I still reserve the right to tweak that if needed, but I will do my absolute best to maintain backwards comptability here as well. -=head3 Is Moose slow? +=head3 I heard Moose is slow, is this true? Again, this one is tricky, so Yes I No. @@ -56,30 +47,26 @@ we will optimize for speed later. It has been our experience that taking this approach allows for greater optimization capacity. -And lastly, I want to reassure the speed junkies out there that -we B working on it. - -We have the immutable classes in Class::MOP, but which are not -yet integrated with Moose. These allow you to "close" a class -and then for many of it's more expensive methods to me memoized. -Our tests indicated a performance comparable (and in some -instances exceeding) that of hand-coded Perl. +Currently we have the option of making your classes immutable +as a means of boosting speed. This will mean a larger compile +time cost, but the runtime speed increase (especially in object +construction) is pretty signifigant. -We are also discussing and experimenting with L, -and the idea of compiling highly optimized C<.pmc> files. And we -have also mapped out some core methods as canidates for conversion -to XS. +This is not all either, we are also discussing and experimenting +with L, and the idea of compiling highly +optimized C<.pmc> files. And we have also mapped out some core +methods as canidates for conversion to XS. =head3 When will Moose be 1.0 ready? -I expect (barring unforseen circumstances) that Moose will be -at 1.0 by the end of this year (2006). Which means that it will be -completely stable and provide a number of optimization options to -suit the need for speed. +I had originally said it would be end of 2006, but various bits +of $work kept me too busy. At this point, I think we are getting +pretty close and I will likely declare 1.0 within the next few +releases. -Will I have addressed all your concerns by then? Will all the -features you want be included? I don't know unless you tell me, -so come over to #moose and we can talk. +When will that be? Hard to say really, but honestly, it is ready +to use now, the difference between now and 1.0 will be pretty +minimal. =head2 Constructors @@ -292,6 +279,11 @@ Use the C option when building the subtype. Like so: This will be called when a value fails to pass the C constraint check. +=head3 Can I turn type constraint checking off? + +Not yet, but soon. This option will likely be coming in the next +release. + =head1 AUTHOR Stevan Little Estevan@iinteractive.comE diff --git a/lib/Moose/Cookbook/WTF.pod b/lib/Moose/Cookbook/WTF.pod index 0a6e85d..07f3a8e 100644 --- a/lib/Moose/Cookbook/WTF.pod +++ b/lib/Moose/Cookbook/WTF.pod @@ -23,12 +23,33 @@ but nothing is ready yet. =head3 Why are my objects taking so long to construct? Moose uses a lot of introspection when constructing an -instance, and introspection can be slow. However, this -is a temporary problem, and is already solved in -Class::MOP by making classes immutable. However immutable -support in Moose is not ready yet, but will be soon. +instance, and introspection can be slow. This problem +can be solved by making your class immutable. This can +be done with the following code: -=head2 Constructors + MyClass->meta->make_immutable(); + +Moose will then memoize a number of meta-level methods +and inline a constructor for you. For more information +on this see the L section below and in the +L. + +=head2 Constructors & Immutability + +=head3 I made my class immutable, but C it is still slow! + +Do you have a custom C method in your class? Moose +will not overwrite your custom C method, you would +probably do better to try and convert this to use the +C method or possibly set C values in +the attribute declaration. + +=head3 I made my class immutable, and now my (before | after | around) C is not being called? + +Making a I, I or I wrap around the +C method, will actually create a C method within +your class. This will prevent Moose from creating one itself +when you make the class immutable. =head2 Accessors