view release on metacpan or  search on metacpan

README.md  view on Meta::CPAN

Used for debugging purpose only, this will print out the
[PPI](https://metacpan.org/pod/PPI){.perl-module} structure of the code
filtered and parsed.

\_parse
-------

After the code has been collected, this method will quickly parse it and
make changes to enable [\"async\"](#async){.perl-module}

\_reject\_resolve
-----------------

This is a common code called by either
[\"resolve\"](#resolve){.perl-module} or
[\"reject\"](#reject){.perl-module}

\_set\_exit\_values
-------------------

This is called upon the exit of the asynchronous process to set some
general value about how the process exited.

See [\"exit\_bit\"](#exit_bit){.perl-module},
[\"exit\_signal\"](#exit_signal){.perl-module} and
[\"exit\_status\"](#exit_status){.perl-module}

\_set\_shared\_space
--------------------

This is called in [\"exec\"](#exec){.perl-module} to share data
including result between main parent process and asynchronous process.

SHARED VARIABLES
================

It is important to be able to share variables between processes in a
seamless way.

When the asynchronous process is executed, the main process first fork
and from this point on all data is being duplicated in an impermeable
way so that if a variable is modified, it would have no effect on its
alter ego in the other process; thus the need for shareable variables.

You can enable shared variables in two ways:

1\. declaring the variable as shared

:       my $name : shared;
            # Initiate a value
            my $location : shared = 'Tokyo';
            # you can also use 'pshared'
            my $favorite_programming_language : pshared = 'perl';
            # You can share array, hash and scalar
            my %preferences : shared;
            my @names : shared;

2\. calling [\"share\"](#share){.perl-module}

:       my( $name, %prefs, @middle_names );
            share( $name, %prefs, @middle_names );

Once shared, you can use those variables normally and their values will
be shared between the parent process and the asynchronous process.

For example:

        my( $name, @first_names, %preferences );
        share( $name, @first_names, %preferences );
        $name = 'Momo Taro';

        Promise::Me->new(sub
        {
            $preferences{name} = $name = 'Mr. ' . $name;
            print( "Hello $name\n" );
            $preferences{location} = 'Okayama';
            $preferences{lang} = 'ja_JP';
            $preferences{locale} = '桃太郎';
            my $rv = $tbl->insert( \%$preferences )->exec || die( My::Exception->new( $tbl->error ) );
            $rv;
        })->then(sub
        {
            my $mail = My::Mailer->new(
                to => $preferences{email},
                name => $preferences{name},
                body => $welcome_ja_file,
            );
            $mail->send || die( $mail->error );
        })->catch(sub
        {
            my $exception = shift( @_ );
            $logger->write( $exception );
        })->finally(sub
        {
            $dbh->disconnect;
        });

If you want to mix this feature and the usage of threads\' `shared`
feature, use the keyword `pshared` instead of `shared`, such as:

        my $name : pshared;

Otherwise the two keywords would conflict.

SHARED MEMORY
=============

This module uses shared memory using
[Module::Generic::SharedMemXS](https://metacpan.org/pod/Module::Generic::SharedMemXS){.perl-module},
or shared cache file using
[Module::Generic::File::Cache](https://metacpan.org/pod/Module::Generic::File::Cache){.perl-module}
if shared memory is not supported, or if the value of the global package
variable `$SHARE_MEDIUM` is set to `file` instead of `memory`.
Alternatively you can also have
[Promise::Me](https://metacpan.org/pod/Promise::Me){.perl-module} use
cache mmap file by setting `$SHARE_MEDIUM` to `mmap`. This will have it
use
[Module::Generic::File::Mmap](https://metacpan.org/pod/Module::Generic::File::Mmap){.perl-module},
but note that you will need to install
[Cache::FastMmap](https://metacpan.org/pod/Cache::FastMmap){.perl-module}

README.md  view on Meta::CPAN

This will yield:

        Promise 2: result is now: 'John '
        Promise 1: result is now: 'John Peter '
        Result is: 'John Peter '

CLASS VARIABLE
==============

\$RESULT\_MEMORY\_SIZE
----------------------

This is the size in bytes of the shared memory block used for sharing
result between sub process and main process, such as when you call:

        my $res = $prom->result;

It defaults to 512Kb

\$SERIALISER
------------

A string representing the serialiser to use by default. A serialiser is
used to serialiser data to share them between processes. This defaults
to `storable`

Currently supported serialisers are:
[CBOR::XS](https://metacpan.org/pod/CBOR::XS){.perl-module},
[Sereal](https://metacpan.org/pod/Sereal){.perl-module} and
[Storable](https://metacpan.org/pod/Storable::Improved){.perl-module}

You can set accordingly the value for `$SERIALISER` to: `cbor`, `sereal`
or `storable`

You can override this global value when you instantiate a new
[Promise::Me](https://metacpan.org/pod/Promise::Me){.perl-module} object
with the `serialiser` option. See [\"new\"](#new){.perl-module}

Note that the serialiser used to serialise shared variable, is set only
via this class variable `$SERIALISER`

\$SHARE\_MEDIUM
---------------

The value of `$SHARE_MEDIUM` is automatically initialised to `memory` if
the system, on which this module runs, supports
[IPC::SysV](https://metacpan.org/pod/IPC::SysV){.perl-module}, or `mmap`
if you have
[Cache::FastMmap](https://metacpan.org/pod/Cache::FastMmap){.perl-module}
installed, or else to `file`

\$SHARED\_MEMORY\_SIZE
----------------------

This is the size in bytes of the shared memory block used for sharing
variables between the main process and the sub processes. This is used
when you share variables, such as:

        my $name : shared;
        my( $name, %prefs, @middle_names );
        share( $name, %prefs, @middle_names );

See [\"SHARED VARIABLES\"](#shared-variables){.perl-module}

SERIALISATION
=============

[Promise::Me](https://metacpan.org/pod/Promise::Me){.perl-module} uses
the following supported serialiser to serialise shared data across
processes:

-   [CBOR](https://metacpan.org/pod/CBOR::XS){.perl-module}
-   [Sereal](https://metacpan.org/pod/Sereal){.perl-module}
-   [Storable](https://metacpan.org/pod/Storable::Improved){.perl-module}

You can set which one to use globally by setting the class variable
`$SERIALISER` to `cbor`, `sereal` or to `storable`

You can also set which serialiser to use on a per promise object by
setting the option `serialiser`. See [\"new\"](#new){.perl-module}

AUTHOR
======

Jacques Deguest \<`jack@deguest.jp`{classes="ARRAY(0x558dc867c1d0)"}\>

SEE ALSO
========

[Promise::XS](https://metacpan.org/pod/Promise::XS){.perl-module},
[Promise::E6](https://metacpan.org/pod/Promise::E6){.perl-module},
[Promise::AsyncAwait](https://metacpan.org/pod/Promise::AsyncAwait){.perl-module},
[AnyEvent::XSPromises](https://metacpan.org/pod/AnyEvent::XSPromises){.perl-module},
[Async](https://metacpan.org/pod/Async){.perl-module},
[Promises](https://metacpan.org/pod/Promises){.perl-module},
[Mojo::Promise](https://metacpan.org/pod/Mojo::Promise){.perl-module}

[Mozilla documentation on
promises](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Using_promises){.perl-module}

COPYRIGHT & LICENSE
===================

Copyright(c) 2021-2022 DEGUEST Pte. Ltd. DEGUEST Pte. Ltd.

All rights reserved

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