CPAN::Groonga

=encoding utf8

=head1 NAME

Module::Generic::Null - Null Value Chaining Object Class

=head1 SYNOPSIS

    # In your code:
    sub customer
    {
        my $self = shift( @_ );
        return( $self->error( "No customer id was provided" ) ) if( !scalar( @_ ) );
        return( $self->customer_info_to_object( @_ ) );
    }

    # And this method is called without providing an id, thus triggering an error,
    # but is chained. Upon error triggered by method "error", a Module::Generic::Null
    # object is returned
    my $name = $object->customer->name;

=head1 VERSION

    v1.1.4

=head1 DESCRIPTION

Normally the call above would have triggered a perl error like C<Cannot call method name on an undefined value>, but since L<Module::Generic/"error"> returns a L<Module::Generic::Null> object, the method B<name> here is called without triggering an error, and returns the right value based on the expectation of the caller which will ultimately result in C<undef> in scalar context or an empty list in list context.

L<Module::Generic::Null> uses C<AUTOLOAD> to allow any method to work in chaining, but contains the original error within its object.

When the C<AUTOLOAD> is called, it checks the call context and returns the appropriate value (self object, code ref, hash ref, array ref, scalar ref, or simply undef or empty list)

If the caller wants an hash reference, it returns an empty hash reference.

If the caller wants an array reference, it returns an empty array reference.

If the caller wants a scalar reference, it returns a scalar reference pointing to undef.

If the caller wants a code reference, it returns an anonymous subroutine that returns C<undef> or an empty list.

If the caller is calling another method right after, this means this is an object context and L<Module::Generic::Null> will return the current object it was called with.

In any other context, C<undef> is returned or an empty list.

Without using L<Module::Generic::Null>, if you return simply undef, like:

    my $val = $object->return_false->[0];

    sub return_false{ return }

The above would trigger an error that the value returned by C<return_false> is not an array reference.
Instead of having the caller checking what kind of returned value was returned, the caller only need to check if it is defined or not, no matter the context in which it is called.

For example:

    my $this = My::Object->new;
    my $val  = $this->call1;
    defined( $val ) || die( $this->error );
    # return undef)

    # object context
    $val = $this->call1->call_again;
    defined( $val ) || die( $this->error );
    # $val is undefined

    # hash reference context
    $val = $this->call1->fake->{name};
    defined( $val ) || die( $this->error );
    # $val is undefined

    # array reference context
    $val = $this->call1->fake->[0];
    defined( $val ) || die( $this->error );
    # $val is undefined

    # code reference context
    $val = $this->call1->fake->();
    defined( $val ) || die( $this->error );
    # $val is undefined

    # scalar reference context
    $val = ${$this->call1->fake};
    defined( $val ) || die( $this->error );
    # $val is undefined

    # simple scalar
    $val = $this->call1->fake;
    defined( $val ) || die( $this->error );
    # $val is undefined

    package My::Object;
    use parent qw( Module::Generic );

    sub call1
    {
        return( shift->call2 );
    }

    sub call2 { return( shift->new_null ); }

    sub call_again
    {
        my $self = shift( @_ );
        print( "Got here in call_again\n" );
        return( $self );
    }

Undefined value is the typical response one gets when an error occurred, so you can check like this, assuming you know you normally would not get a false value :

    my $name = $object->customer->name || die( $object->error );

Apart from that, this does not do anything meaningful.

=head1 METHODS

There is only 1 method. This module makes it possible to call it with any method to fake original data flow.

=head2 new

This takes an optional error object (e.g., a L<Module::Generic::Exception>) and an optional hash or hash reference of options, and returns a new L<Module::Generic::Null> object.

Possible options:

=over 4

=item * C<wants>

Specifies the desired context for the null object to return. Can be any of (case-insensitive): C<ARRAY>, C<BOOLEAN>, C<CODE>, C<GLOB>, C<HASH>, C<LIST>, C<OBJECT>, C<REFSCALAR>, C<SCALAR>, C<VOID>. If not specified, the context is determined dynamically using L<Wanted>.

Example:

    my $null = Module::Generic::Null->new( wants => 'HASH' );
    my $hash = $null->fake; # Returns {}

=back

=head1 SERIALISATION

=for Pod::Coverage FREEZE

=for Pod::Coverage STORABLE_freeze

=for Pod::Coverage STORABLE_thaw

=for Pod::Coverage THAW

=for Pod::Coverage TO_JSON

Serialisation by L<CBOR|CBOR::XS>, L<Sereal> and L<Storable::Improved> (or the legacy L<Storable>) is supported by this package. To that effect, the following subroutines are implemented: C<FREEZE>, C<THAW>, C<STORABLE_freeze> and C<STORABLE_thaw>

=head1 THREAD & PROCESS SAFETY

L<Module::Generic::Null> is fully thread-safe and process-safe, designed to provide a null object for method chaining without breaking in multi-threaded or multi-process environments, such as Perl ithreads or mod_perl’s threaded Multi-Processing Modules (MPMs) like Worker or Event. All operations are per-object, ensuring no shared state conflicts.

Key considerations for thread and process safety:

=over 4

=item * B<Object State>

All methods, including L</new>, C<AUTOLOAD>, and serialisation subroutines (L</FREEZE>, L</THAW>), operate exclusively on the object’s internal hash, which is unique to each instance. This ensures thread-safe and process-safe behaviour without shared resources:

    use threads;
    my $null = Module::Generic::Null->new( wants => 'HASH' );
    my @threads = map
    {
        threads->create(sub
        {
            my $val = $null->fake; # Returns empty hashref, thread-safe
            return( ref( $val ) eq 'HASH' ? 1 : 0 );
        });
    } 1..5;
    $_->join for @threads;

=item * B<AUTOLOAD>

The C<AUTOLOAD> mechanism handles arbitrary method calls, returning context-appropriate values (e.g., empty hashref, arrayref, or the object itself) based on L<Wanted>’s stack inspection. This process is thread-safe, as it uses no shared state and creates per-object or immutable return values:

    my $null = Module::Generic::Null->new;
    my $val = $null->any_method->another; # Returns $null, thread-safe

=item * B<Overloading>

Overloaded operators (stringification, equality, boolean) are pure functions operating on the object’s state or local data, ensuring thread-safety:

    my $null = Module::Generic::Null->new;
    my $str = "$null"; # Empty string, thread-safe
    my $bool = $null ? 1 : 0; # False, thread-safe

=item * B<Serialisation>

Serialisation methods (L</FREEZE>, L</THAW>) copy the object’s hash, which is per-object and thread-safe, supporting L<CBOR::XS>, L<Sereal>, and L<Storable::Improved>:

    use threads;
    use Sereal;
    my $null = Module::Generic::Null->new;
    my $encoded = Sereal::encode_sereal( $null ); # Thread-safe

=item * B<mod_perl Considerations>

=over 4

=item - B<Prefork MPM>

Each process creates independent L<Module::Generic::Null> instances, ensuring process isolation with no shared state.

=item - B<Threaded MPMs (Worker/Event)>

All operations remain thread-safe due to per-object state and thread-safe dependencies (L<Scalar::Util>, L<Wanted>). No thread-unsafe Perl functions (e.g., L<perlfunc/localtime>) are used. Users should ensure mod_perl handlers clean up objects to prevent memory leaks, though L<Module::Generic::Null> itself requires no special handling.

Consult L<perlthrtut|http://perldoc.perl.org/perlthrtut.html> and L<mod_perl documentation|https://perl.apache.org/docs/2.0/user/coding/coding.html#Thread_environment_Issues> for details.

=back

=item * B<Process Safety>

Since all operations are per-object and use no system-level resources (e.g., files, sockets), L<Module::Generic::Null> is inherently process-safe. Separate processes create distinct instances with no interaction:

    use POSIX qw( fork );
    my $pid = fork();
    if( $pid == 0 )
    {
        my $null = Module::Generic::Null->new;
        my $val = $null->fake; # Safe, per-process state
        exit;
    }
    waitpid( $pid, 0 );

=back

For debugging in threaded or multi-process environments, use platform-specific commands (e.g., on Linux):

    ls -l /proc/$$/fd  # List open file descriptors

See your operating system’s documentation for equivalent commands.

=head2 CREDITS

Based on an original idea from L<Brian D. Foy|https://stackoverflow.com/users/2766176/brian-d-foy> discussed on L<StackOverflow|https://stackoverflow.com/a/7068271/4814971> and also on L<Perl Monks|https://www.perlmonks.org/?node_id=265214>

=head1 AUTHOR

Jacques Deguest E<lt>F<jack@deguest.jp>E<gt>

=head1 COPYRIGHT & LICENSE

Copyright (c) 2000-2024 DEGUEST Pte. Ltd.

You can use, copy, modify and redistribute this package and associated
files under the same terms as Perl itself.

=cut