Object...:Later(3pm)

🌸 NAME 🌸

Object::Realize::Later — delayed creation of objects ✨

---

✨ SYNOPSIS ✨

package MyLazyObject;

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

---

💖 DESCRIPTION 💖

Okay so bestie, meet Object::Realize::Later — the class that helps you implement transparent on demand realization of object data. 🦋 It's the data-flavored cousin of autoloading: you know autoloading of functionality? Yeah, this is the lesser known cousin of that, but for data. iykyk 💅

⚠️ Real talk though: this module, versions 4.0 and up, is not fully compatible with older releases — mainly the exception handling has changed. When you need to upgrade, please read https://github.com/markov2/perl5-Mail-Box/wiki/ . Version 3 is still maintained and may see new releases as well. 🫶

So why do we even do this? On demand realization is all about performance gain, no cap. Why would you spend costly time realizing an object when the data on that object is never (or not yet) used? 😭 In interactive programs, postponed realization may boost start-up, because the realization of objects is triggered by the use — so it's spread over time instead of hitting you all at once. Iconic behavior honestly. 👑

---

🎀 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 — go peep the section "Added to YOUR class" for the full haul. 💖

Here's the option vibe check, with defaults and everything:

• becomes — default: <required>
• believe_caller — default: false
• realize — default: <required>
• source_module — default: <becomes>
• warn_realization — default: false
• warn_realize_again — default: false

---

• becomes => $class — which type will this object become after realization. ✨
• believe_caller => BOOLEAN — so when a method gets called on the un-realized object, the AUTOLOAD checks whether that call actually resolves the need. If it doesn't, the realization is not done. BUT — if realization may result in an object that extends the functionality of the class you specified with "becomes", then 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 it 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 in various places. Be sure that your realization method is coping with that — for instance by using Memoize. See examples 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 one's for debugging purposes. 🐛
• warn_realize_again => BOOLEAN — when an object is realized, the original object — which functioned as a stub — is reconstructed to work as proxy to the realized object. This option issues a warning when that proxy is used, which means somewhere in your program there is a variable still holding a reference to the stub. 💀 That latter thing is not problematic at all, although it slows-down each method call. So like, no drama, just slow. 🐌

Added to YOUR class 💅

• $obj->AUTOLOAD() — when a method is called which is not available for the lazy object, the AUTOLOAD is called. 🦋
• $any->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. 🔥
• $class->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. 🌈

• $class->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 callers name-space. 🪄
• $class->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. 🫧
• $class->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 💤

Okay so lazy loading, bestie, has two whole ways to happen. You can either check whether you have realized the data inside every single method that accesses that data, or you can use the autoloading-of-data trick. Both are valid, both are giving different vibes. 💅

Here’s what the first solution looks like:

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};
}

Ngl, that one is error-prone. You can easily forget to call realize(). The tests cannot cover all ordenings of method-calls to detect the mistakes. It’s giving “oops, missed a spot” energy.

The second approach uses autoloading, and this package has your back. First we create a stub-object, which will be transformable into a realized object later. That 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. Iconic behavior, honestly. ✨

---

⚠️ Traps ⚠️

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. Not dramatic, literally terrible. 💀

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 time, because the bless information is stored within the referred 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'

Not me reading those comments like a thriller. 😭

---

🌸 Examples 🌸

💌 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});
}

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 reblessed. There is no danger that the un-realized version of the object is kept somewhere: all variables that know about this particular deer see the change. Periodt. 🦋

💌 Example 3 💌

This module is especially useful 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()     { $_[0]->{head} }
sub body()     { $_[0]->{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.
    $body->can('forceRealize') or return $body;

    # 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()    { $_[0]->{size} }
sub lines()   { $_[0]->{lines} }
sub message() { $_[0]->{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() { $_[0]->{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.

This is the main character energy of lazy loading, no cap. 👑🔥

---

🔍 SEE ALSO 🔍

This module is part of Object-Realize-Later version 4.00, built on December 12, 2025. Website: http://perl.overmeer.net/CPAN/

---

📜 LICENSE 📜

For contributors see file ChangeLog.

This software is copyright (c) 2001-2025 by Mark Overmeer.

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

💖 That's the whole vibe, bestie. This page came from perl v5.40.1, dated 2026-01-24, and the manpage is Object...:Later(3pm). Byeee! 💖