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

 package MyLazyObject;

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

The CWObject::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 functionality.

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 realization may boost start-up: the realization of objects is triggered by the use, so spread over time.

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

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

$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 version 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.

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 CWimport are the values after the class name with CWuse. So this routine implements the actual option parsing. It generates code dynamically, which is then evaluated in the callers name-space.

Object::Realize::Later->realizationOf(OBJECT [,REALIZED]) Returns the REALIZED version of OBJECT, optionally after setting it first. When the method returns CWundef, 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 CW$object-forceRealize()> takes place. It checks whether the realization has been done already (is which case the realized object is returned)

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 realized 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.

CWObject::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.

Be aware of dangerous traps in the current implementation. These problems 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 dangerous. 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'

Example 1 In the first example, we delay-load a message. On the moment the message is defined, we only take the location. When the data of the message 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});
 }

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

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

 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() {...}

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

 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(4);
 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.

The html version of this module can be found in the website about MailBox, <http://perl.overmeer.net/mailbox/html/>.

Module version 0.15. Written by Mark Overmeer (mark@overmeer.net). See the ChangeLog for other contributors. Copyright (c) 2003 by the author(s). All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.