NAME

       "IO::Async::Routine" - execute code in an independent sub-process or thread

SYNOPSIS

        use IO::Async::Routine;
        use IO::Async::Channel;

        use IO::Async::Loop;
        my $loop = IO::Async::Loop->new;

        my $nums_ch = IO::Async::Channel->new;
        my $ret_ch  = IO::Async::Channel->new;

        my $routine = IO::Async::Routine->new(
           channels_in  => [ $nums_ch ],
           channels_out => [ $ret_ch ],

           code => sub {
              my @nums = @{ $nums_ch->recv };
              my $ret = 0; $ret += $_ for @nums;

              # Can only send references
              $ret_ch->send( \$ret );
           },

           on_finish => sub {
              say "The routine aborted early - $_[-1]";
              $loop->stop;
           },
        );

        $loop->add( $routine );

        $nums_ch->send( [ 10, 20, 30 ] );
        $ret_ch->recv(
           on_recv => sub {
              my ( $ch, $totalref ) = @_;
              say "The total of 10, 20, 30 is: $$totalref";
              $loop->stop;
           }
        );

        $loop->run;

DESCRIPTION

       This IO::Async::Notifier contains a body of code and executes it in a sub-process or
       thread, allowing it to act independently of the main program.  Once set up, all
       communication with the code happens by values passed into or out of the Routine via
       IO::Async::Channel objects.

       A choice of detachment model is available, with options being a "fork()"ed child process,
       or a thread. In both cases the code contained within the Routine is free to make blocking
       calls without stalling the rest of the program. This makes it useful for using existing
       code which has no option not to block within an "IO::Async"-based program.

       Code running inside a "fork()"-based Routine runs within its own process; it is isolated
       from the rest of the program in terms of memory, CPU time, and other resources. Code
       running in a thread-based Routine however, shares memory and other resources such as open
       filehandles with the main thread.

       To create asynchronous wrappers of functions that return a value based only on their
       arguments, and do not generally maintain state within the process it may be more
       convenient to use an IO::Async::Function instead, which uses an "IO::Async::Routine" to
       contain the body of the function and manages the Channels itself.

EVENTS

   on_finish $exitcode
       For "fork()"-based Routines, this is invoked after the process has exited and is passed
       the raw exitcode status.

   on_finish $type, @result
       For thread-based Routines, this is invoked after the thread has returned from its code
       block and is passed the "on_joined" result.

       As the behaviour of these events differs per model, it may be more convenient to use
       "on_return" and "on_die" instead.

   on_return $result
       Invoked if the code block returns normally. Note that "fork()"-based Routines can only
       transport an integer result between 0 and 255, as this is the actual "exit()" value.

   on_die $exception
       Invoked if the code block fails with an exception.

PARAMETERS

       The following named parameters may be passed to "new" or "configure":

       model => "fork" | "thread"
               Optional. Defines how the routine will detach itself from the main process.
               "fork" uses a child process detached using an IO::Async::Process.  "thread" uses a
               thread, and is only available on threaded Perls.

               If the model is not specified, the environment variable "IO_ASYNC_ROUTINE_MODEL"
               is used to pick a default. If that isn't defined, "fork" is preferred if it is
               available, otherwise "thread".

       channels_in => ARRAY of IO::Async::Channel
               ARRAY reference of "IO::Async::Channel" objects to set up for passing values in to
               the Routine.

       channels_out => ARRAY of IO::Async::Channel
               ARRAY reference of "IO::Async::Channel" objects to set up for passing values out
               of the Routine.

       code => CODE
               CODE reference to the body of the Routine, to execute once the channels are set
               up.

       setup => ARRAY
               Optional. For "fork()"-based Routines, gives a reference to an array to pass to
               the underlying "Loop" "fork_child" method. Ignored for thread-based Routines.

METHODS

   $id = $routine->id
       Returns an ID string that uniquely identifies the Routine out of all the currently-running
       ones. (The ID of already-exited Routines may be reused, however.)

AUTHOR

       Paul Evans <leonerd@leonerd.org.uk>