unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (Debian-5.0)
Page:
Section:
Apropos / Subsearch:
optional field

Object::Realize::LaterUser)Contributed Perl DocumenObject::Realize::Later(3pm)



NAME
       Object::Realize::Later - Delayed creation of objects

SYNOPSIS
        package MyLazyObject;

        use Object::Realize::Later
           becomes => 'MyRealObject',
           realize => 'load';

DESCRIPTION
       The "Object::Realize::Later" class helps with implementing transparent
       on demand realization of object data.  This is related to the tricks on
       autoloading of data, the lesser known cousin of autoloading of func-
       tionality.

       On demand realization is all about performance gain.  Why should you
       spent costly time on realizing an object, when the data on the object
       is never (or not yet) used?  In interactive programs, postponed real-
       ization may boost start-up: the realization of objects is triggered by
       the use, so spread over time.

METHODS
       Construction

       use(Object::Realize::Later OPTIONS)

           When you invoke ("use") the "Object::Realize::Later" package, it
           will add a set of methods to your package (see section "Added to
           YOUR class").

            Option            --Default
            becomes             <required>
            believe_caller      <false>
            realize             <required>
            source_module       <becomes>
            warn_realization    <false>
            warn_realize_again  <false>

           . becomes => CLASS

               Which type will this object become after realization.

           . believe_caller => BOOLEAN

               When a method is called on the un-realized object, the AUTOLOAD
               checks whether this resolves the need.  If not, the realization
               is not done.  However, when realization may result in an object
               that extends the functionality of the class specified with
               "becomes", this check must be disabled.  In that case, specify
               true for this option.

           . realize => METHOD|CODE

               How will transform.  If you specify a CODE reference, then this
               will be called with the lazy-object as first argument, and the
               requested method as second.

               After realization, you may still have your hands on the lazy
               object on various places.  Be sure that your realization method
               is coping with that, for instance by using Memoize.  See exam-
               ples below.

           . source_module => CLASS

               if the class (a package) is included in a file (module) with a
               different name, then use this argument to specify the file
               name. The name is expected to be the same as in the "require"
               call which would load it.

           . warn_realization => BOOLEAN

               Print a warning message when the realization starts.  This is
               for debugging purposes.

           . warn_realize_again => BOOLEAN

               When an object is realized, the original object -which func-
               tioned as a stub- is reconstructed to work as proxy to the
               realized object.  This option will issue a warning when that
               proxy is used, which means that somewhere in your program there
               is a variable still holding a reference to the stub.  This lat-
               ter is not problematic at all, although it slows-down each
               method call.

       Added to YOUR class

       $obj->AUTOLOAD

           When a method is called which is not available for the lazy object,
           the AUTOLOAD is called.

       $obj->can(METHOD)

       Object::Realize::Later->can(METHOD)

           Is the specified METHOD available for the lazy or the realized ver-
           sion of this object?  It will return the reference to the code.

           Example:

              MyLazyObject->can('lazyWork')      # true
              MyLazyObject->can('realWork')      # true

              my $lazy = MyLazyObject->new;
              $lazy->can('lazyWork');            # true
              $lazy->can('realWork');            # true

       $obj->forceRealize

           You can force the load by calling this method on your object.  It
           returns the realized object.

       Object::Realize::Later->isa(CLASS)

           Is this object a (sub-)class of the specified CLASS or can it
           become a (sub-)class of CLASS.

           Example:

            MyLazyObject->isa('MyRealObject')      # true
            MyLazyObject->isa('SuperClassOfLazy'); # true
            MyLazyObject->isa('SuperClassOfReal'); # true

            my $lazy = MyLazyObject->new;
            $lazy->isa('MyRealObject');            # true
            $lazy->isa('SuperClassOfLazy');        # true
            $lazy->isa('SuperClassOfReal');        # true

       $obj->willRealize

           Returns which class will be the realized to follow-up this class.

       Object::Realize::Later internals

       The next methods are not exported to the class where the `use' took
       place.  These methods implement the actual realization.

       Object::Realize::Later->import(OPTIONS)

           The OPTIONS used for "import" are the values after the class name
           with "use".  So this routine implements the actual option parsing.
           It generates code dynamically, which is then evaluated in the call-
           ers name-space.

       Object::Realize::Later->realizationOf(OBJECT [,REALIZED])

           Returns the REALIZED version of OBJECT, optionally after setting it
           first.  When the method returns "undef", the realization has not
           yet taken place or the realized object has already been removed
           again.

       Object::Realize::Later->realize(OPTIONS)

           This method is called when a "$object-"forceRealize()> takes place.
           It checks whether the realization has been done already (is which
           case the realized object is returned)

DETAILS
       About lazy loading

       There are two ways to implement lazy behaviour: you may choose to check
       whether you have realized the data in each method which accesses the
       data, or use the autoloading of data trick.

       An implementation of the first solution is:

        sub realize {
            my $self = shift;
            return $self unless $self->{_is_realized};

            # read the data from file, or whatever
            $self->{data} = ....;

            $self->{_is_realized} = 1;
            $self;
        }

        sub getData() {
            my $self = shift;
            return $self->realize->{data};
        }

       The above implementation is error-prone, where you can easily forget to
       call realize().  The tests cannot cover all ordenings of method-calls
       to detect the mistakes.

       The second approach uses autoloading, and is supported by this package.
       First we create a stub-object, which will be transformable into a real-
       ized object later.  This transformation is triggered by AUTOLOAD.

       This stub-object may contain some methods from the realized object, to
       reduce the need for realization.  The stub will also contain some
       information which is required for the creation of the real object.

       "Object::Realize::Later" solves the inheritance problems (especially
       the isa() and can() methods) and supplies the AUTOLOAD method.  Class
       methods which are not defined in the stub object are forwarded as class
       methods without realization.

       Traps

       Be aware of dangerous traps in the current implementation.  These prob-
       lems appear by having multiple references to the same delayed object.
       Depending on how the realization is implemented, terrible things can
       happen.

       The two versions of realization:

       * by reblessing
           This is the safe version.  The realized object is the same object
           as the delayed one, but reblessed in a different package.  When
           multiple references to the delayed object exists, they will all be
           updated at the same, because the bless information is stored within
           the refered variable.

       * by new instance
           This is the nicest way of realization, but also quite more danger-
           ous.  Consider this:

            package Delayed;
            use Object::Realize::Later
                 becomes => 'Realized',
                 realize => 'load';

            sub new($)      {my($class,$v)=@_; bless {label=>$v}, $class}
            sub setLabel($) {my $self = shift; $self->{label} = shift}
            sub load()      {$_[0] = Realized->new($_[0]->{label}) }

            package Realized;  # file Realized.pm or use use(source_module)
            sub new($)      {my($class,$v)=@_; bless {label=>$v}, $class}
            sub setLabel($) {my $self = shift; $self->{label} = shift}
            sub getLabel()  {my $self = shift; $self->{label}}

            package main;
            my $original = Delayed->new('original');
            my $copy     = $original;
            print $original->getLabel;     # prints 'original'
            print ref $original;           # prints 'Realized'
            print ref $copy;               # prints 'Delayed'
            $original->setLabel('changed');
            print $original->getLabel;     # prints 'changed'
            print $copy->getLabel;         # prints 'original'

       Examples

       Example 1

       In the first example, we delay-load a message.  On the moment the mes-
       sage is defined, we only take the location.  When the data of the mes-
       sage is taken (header or body), the data is autoloaded.

        package Mail::Message::Delayed;

        use Object::Realize::Later
          ( becomes => 'Mail::Message::Real'
          , realize => 'loadMessage'
          );

        sub new($) {
            my ($class, $file) = @_;
            bless { filename => $file }, $class;
        }

        sub loadMessage() {
            my $self = shift;
            Mail::Message::Real->new($self->{filename});
        }

       In the main program:

        package main;
        use Mail::Message::Delayed;

        my $msg    = Mail::Message::Delayed->new('/home/user/mh/1');
        $msg->body->print;     # this will trigger autoload.

       Example 2

       Your realization may also be done by reblessing.  In that case to
       change the type of your object into a different type which stores the
       same information.  Is that right?  Are you sure?  For simple cases,
       this may be possible:

        package Alive;
        use Object::Realize::Later
             becomes => 'Dead',
             realize => 'kill';

        sub new()         {my $class = shift; bless {@_}, $class}
        sub jump()        {print "Jump!\n"}
        sub showAntlers() {print "Fight!\n"}
        sub kill()        {bless(shift, 'Dead')}

        package Dead;
        sub takeAntlers() {...}

       In the main program:

        my $deer   = Alive->new(Animal => 'deer');
        my $trophy = $deer->takeAntlers();

       In this situation, the object (reference) is not changed but is reb-
       lessed.  There is no danger that the un-realized version of the object
       is kept somewhere: all variable which know about this partical deer see
       the change.

       Example 3

       This module is especially usefull for larger projects, which there is a
       need for speed or memory reduction. In this case, you may have an extra
       overview on which objects have been realized (transformed), and which
       not.  This example is taken from the MailBox modules:

       The Mail::Box module tries to boost the access-time to a folder.  If
       you only need the messages of the last day, why shall all be read?  So,
       MailBox only creates an invertory of messages at first.  It takes the
       headers of all messages, but leaves the body (content) of the message
       in the file.

       In MailBox' case, the Mail::Message-object has the choice between a
       number of Mail::Message::Body's, one of which has only be prepared to
       read the body when needed.  A code snippet:

        package Mail::Message;
        sub new($$)
        {   my ($class, $head, $body) = @_;
            my $self = bless {head => $head, body => $body}, $class;
            $body->message($self);          # tell body about the message
        }
        sub head()     { shift->{head} }
        sub body()     { shift->{body} }

        sub loadBody()
        {   my $self = shift;
            my $body = $self->body;

            # Catch re-invocations of the loading.  If anywhere was still
            # a reference to the old (unrealized) body of this message, we
            # return the new-one directly.
            return $body unless $body->can('forceRealize');

            # Load the body (change it to anything which really is of
            # the promised type, or a sub-class of it.
            my ($lines, $size) = .......;    # get the data
            $self->{body} = Mail::Message::Body::Lines
                                 ->new($lines, $size, $self);

            # Return the realized object.
            return $self->{body};
        }

        package Mail::Message::Body::Lines;
        use base 'Mail::Message::Body';

        sub new($$$)
        {   my ($class, $lines, $size, $message) = @_;
            bless { lines => $lines, size => $size
                  , message => $message }, $class;
        }
        sub size()    { shift->{size} }
        sub lines()   { shift->{lines} }
        sub message() { shift->{message);

        package Mail::Message::Body::Delayed;
        use Object::Realize::Later
            becomes => 'Mail::Message::Body',
            realize => sub {shift->message->loadBody};

        sub new($)
        {   my ($class, $size) = @_;
            bless {size => $size}, $class;
        }
        sub size() { shift->{size} }
        sub message(;$)
        {   my $self = shift;
            @_ ? ($self->{message} = shift) : $self->{messages};
        }

        package main;
        use Mail::Message;
        use Mail::Message::Body::Delayed;

        my $body    = Mail::Message::Body::Delayed->new(42);
        my $message = Mail::Message->new($head, $body);

        print $message->size;         # will not trigger realization!
        print $message->can('lines'); # true, but no realization yet.
        print $message->lines;        # realizes automatically.

SEE ALSO
       This module is part of Object-Realize-Later distribution version 0.18,
       built on June 08, 2007. Website: http://perl.overmeer.net/orl/

LICENSE
       Copyrights 2001-2004,2007 by Mark Overmeer <perlATovermeer.net>. For
       other contributors see Changes.

       This program is free software; you can redistribute it and/or modify it
       under the same terms as Perl itself.  See
       http://www.perl.com/perl/misc/Artistic.html



perl v5.8.8                       2007-06-08       Object::Realize::Later(3pm)