1IO::Async::Routine(3) User Contributed Perl DocumentationIO::Async::Routine(3)
2
3
4

NAME

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

SYNOPSIS

10        use IO::Async::Routine;
11        use IO::Async::Channel;
12
13        use IO::Async::Loop;
14        my $loop = IO::Async::Loop->new;
15
16        my $nums_ch = IO::Async::Channel->new;
17        my $ret_ch  = IO::Async::Channel->new;
18
19        my $routine = IO::Async::Routine->new(
20           channels_in  => [ $nums_ch ],
21           channels_out => [ $ret_ch ],
22
23           code => sub {
24              my @nums = @{ $nums_ch->recv };
25              my $ret = 0; $ret += $_ for @nums;
26
27              # Can only send references
28              $ret_ch->send( \$ret );
29           },
30
31           on_finish => sub {
32              say "The routine aborted early - $_[-1]";
33              $loop->stop;
34           },
35        );
36
37        $loop->add( $routine );
38
39        $nums_ch->send( [ 10, 20, 30 ] );
40        $ret_ch->recv(
41           on_recv => sub {
42              my ( $ch, $totalref ) = @_;
43              say "The total of 10, 20, 30 is: $$totalref";
44              $loop->stop;
45           }
46        );
47
48        $loop->run;
49

DESCRIPTION

51       This IO::Async::Notifier contains a body of code and executes it in a
52       sub-process or thread, allowing it to act independently of the main
53       program.  Once set up, all communication with the code happens by
54       values passed into or out of the Routine via IO::Async::Channel
55       objects.
56
57       A choice of detachment model is available, with options being a
58       "fork()"ed child process, or a thread. In both cases the code contained
59       within the Routine is free to make blocking calls without stalling the
60       rest of the program. This makes it useful for using existing code which
61       has no option not to block within an IO::Async-based program.
62
63       Code running inside a "fork()"-based Routine runs within its own
64       process; it is isolated from the rest of the program in terms of
65       memory, CPU time, and other resources. Code running in a thread-based
66       Routine however, shares memory and other resources such as open
67       filehandles with the main thread.
68
69       To create asynchronous wrappers of functions that return a value based
70       only on their arguments, and do not generally maintain state within the
71       process it may be more convenient to use an IO::Async::Function
72       instead, which uses an "IO::Async::Routine" to contain the body of the
73       function and manages the Channels itself.
74

EVENTS

76   on_finish $exitcode
77       For "fork()"-based Routines, this is invoked after the process has
78       exited and is passed the raw exitcode status.
79
80   on_finish $type, @result
81       For thread-based Routines, this is invoked after the thread has
82       returned from its code block and is passed the "on_joined" result.
83
84       As the behaviour of these events differs per model, it may be more
85       convenient to use "on_return" and "on_die" instead.
86
87   on_return $result
88       Invoked if the code block returns normally. Note that "fork()"-based
89       Routines can only transport an integer result between 0 and 255, as
90       this is the actual "exit()" value.
91
92   on_die $exception
93       Invoked if the code block fails with an exception.
94

PARAMETERS

96       The following named parameters may be passed to "new" or "configure":
97
98   model => "fork" | "thread"
99       Optional. Defines how the routine will detach itself from the main
100       process.  "fork" uses a child process detached using an
101       IO::Async::Process.  "thread" uses a thread, and is only available on
102       threaded Perls.
103
104       If the model is not specified, the environment variable
105       "IO_ASYNC_ROUTINE_MODEL" is used to pick a default. If that isn't
106       defined, "fork" is preferred if it is available, otherwise "thread".
107
108   channels_in => ARRAY of IO::Async::Channel
109       ARRAY reference of IO::Async::Channel objects to set up for passing
110       values in to the Routine.
111
112   channels_out => ARRAY of IO::Async::Channel
113       ARRAY reference of IO::Async::Channel objects to set up for passing
114       values out of the Routine.
115
116   code => CODE
117       CODE reference to the body of the Routine, to execute once the channels
118       are set up.
119
120   setup => ARRAY
121       Optional. For "fork()"-based Routines, gives a reference to an array to
122       pass to the underlying "Loop" "fork_child" method. Ignored for thread-
123       based Routines.
124

METHODS

126   id
127          $id = $routine->id
128
129       Returns an ID string that uniquely identifies the Routine out of all
130       the currently-running ones. (The ID of already-exited Routines may be
131       reused, however.)
132
133   model
134          $model = $routine->model
135
136       Returns the detachment model in use by the Routine.
137
138   kill
139          $routine->kill( $signal )
140
141       Sends the specified signal to the routine code. This is either
142       implemented by "CORE::kill()" or "threads::kill" as required. Note that
143       in the thread case this has the usual limits of signal delivery to
144       threads; namely, that it works at the Perl interpreter level, and
145       cannot actually interrupt blocking system calls.
146
147   result_future
148          $f = $routine->result_future
149
150       Since version 0.75.
151
152       Returns a new "IO::Async::Future" which will complete with the eventual
153       return value or exception when the routine finishes.
154
155       If the routine finishes with a successful result then this will be the
156       "done" result of the future. If the routine fails with an exception
157       then this will be the "fail" result.
158

AUTHOR

160       Paul Evans <leonerd@leonerd.org.uk>
161
162
163
164perl v5.32.1                      2021-01-27             IO::Async::Routine(3)
Impressum