Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
IO::Async::Routine(3) User Contributed Perl DocumentationIO::Async::Routine(3)

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.

       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.

       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.

   Models
       A choice	of detachment model is available. Each has various advantages
       and disadvantages. Not all of them may be available on a	particular
       system.

       The "fork" model

       The code	in this	model runs within its own process, created by calling
       "fork()"	from the main process. It is isolated from the rest of the
       program in terms	of memory, CPU time, and other resources. Because it
       is started using	"fork()", the initial process state is a clone of the
       main process.

       This model performs well	on UNIX-like operating systems which possess a
       true native "fork()" system call, but is	not available on "MSWin32" for
       example,	because	the operating system does not provide full fork-like
       semantics.

       The "thread" model

       The code	in this	model runs inside a separate thread within the main
       process.	 It therefore shares memory and	other resources	such as	open
       filehandles with	the main thread. As with the "fork" model, the initial
       thread state is cloned from the main controlling	thread.

       This model is only available on perls built to support threading.

       The "spawn" model

       The code	in this	model runs within its own freshly-created process
       running another copy of the perl	interpreter. Similar to	the "fork"
       model it	therefore has its own memory, CPU time,	and other resources.
       However,	since it is started freshly rather than	by cloning the main
       process,	it starts up in	a clean	state, without any shared resources
       from its	parent.

       Since this model	creates	a new fresh process rather than	sharing
       existing	state, it cannot use the "code"	argument to specify the
       routine body; it	must instead use only the "module" and "func"
       arguments.

       In the current implementation this model	requires exactly one input
       channel and exactly one output channel; both must be present, and there
       cannot be more than one of either.

       This model performs well	on both	UNIX and Windows-like operating
       systems,	because	it does	not need full fork semantics.

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" |	"spawn"
       Optional. Defines how the routine will detach itself from the main
       process.	 See the "Models" section above	for more detail.

       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.

       When using the "spawn" model, this is not permitted; you	must use
       "module"	and "func" instead.

   module => STRING
   func	=> STRING
       An alternative to the "code" argument, which names a module to load and
       a function to call within it. "module" should give a perl module	name
       (i.e.  "Some::Name", not	a filename like	Some/Name.pm), and "func"
       should give the basename	of a function within that module (i.e. without
       the module name prefixed). It will be invoked as	the main code body of
       the object, and passed in a list	of all the channels; first the input
       ones then the output ones.

	  module::func(	@channels_in, @channels_out )

   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
	  $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.)

   model
	  $model = $routine->model

       Returns the detachment model in use by the Routine.

   kill
	  $routine->kill( $signal )

       Sends the specified signal to the routine code. This is either
       implemented by "CORE::kill()" or	"threads::kill"	as required. Note that
       in the thread case this has the usual limits of signal delivery to
       threads;	namely,	that it	works at the Perl interpreter level, and
       cannot actually interrupt blocking system calls.

   result_future
	  $f = $routine->result_future

       Since version 0.75.

       Returns a new "IO::Async::Future" which will complete with the eventual
       return value or exception when the routine finishes.

       If the routine finishes with a successful result	then this will be the
       "done" result of	the future. If the routine fails with an exception
       then this will be the "fail" result.

AUTHOR
       Paul Evans <leonerd@leonerd.org.uk>

perl v5.32.1			  2021-11-04		 IO::Async::Routine(3)

NAME | SYNOPSIS | DESCRIPTION | EVENTS | PARAMETERS | METHODS | AUTHOR

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=IO::Async::Routine&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help