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

FreeBSD Manual Pages

  
 
  

home | help
POE::Quickie(3)	      User Contributed Perl Documentation      POE::Quickie(3)

NAME
       POE::Quickie - A	lazy way to wrap blocking code and programs

SYNOPSIS
	use POE::Quickie;

	sub event_handler {
	    # the "I'll	wait until it's	finished" approach, which will block your
	    # session until the	command	has finished
	    my ($stdout, $stderr, $exit_status)	= quickie('foo.pl');
	    print $stdout;

	    # the "keep	me posted" approach, which will	give you each line of output
	    # as it is appears
	    quickie_run(
		Program	    => ['foo.pl', 'bar'],
		StdoutEvent => 'stdout',
		Context	    => 'remember this',
	    );

	    # the "get back to me when it's done" approach, which will notify you
	    # of the entire output when	the command has	finished
	    quickie_run(
		Program	    => ['foo.pl', 'bar'],
		Context	    => 'remember this',
		ResultEvent => 'result',
	    );
	}

	sub stdout {
	    my ($output, $context) = @_[ARG0, ARG1];
	    print "got output: '$output' in the	context	of '$context'\n";
	}

	sub result {
	    my ($pid, $stdout, $stderr,	$merged, $status, $context) = @_[ARG0..$#_];
	    print "got all this	output in the context of '$context':\n";
	    print "$_\n" for @$stdout;
	}

DESCRIPTION
       If you need nonblocking access to an external program, or want to
       execute some blocking code in a separate	process, but you don't want to
       write a wrapper module or some POE::Wheel::Run boilerplate code,	then
       POE::Quickie can	help. You just specify what you're interested in
       (stdout,	stderr,	and/or exit code), and POE::Quickie will handle	the
       rest in a sensible way.

       It has some convenience features, such as killing processes after a
       timeout,	and storing process-specific context information which will be
       delivered with every event.

       There is	also an	even lazier API	which suspends the execution of	your
       event handler and gives control back to POE while your task is running,
       the same	way LWP::UserAgent::POE	does. This is provided by the
       "quickie_*" functions which are exported	by default.

METHODS
   "new"
       Constructs a POE::Quickie object. You only need to do this if you want
       to specify any of the parameters	below, since a POE::Quickie object
       will be constructed automatically when it is needed. The	rest of	the
       methods can be called on	the object ("$object->run()") or as class
       methods ("POE::Quickie->run()").	You can	safely let the object go out
       of scope; POE::Quickie will continue to run your	processes until	they
       finish.

       Takes 3 optional	parameters: 'debug', 'default',	and 'trace'. These
       will be passed to the object's POE::Session constructor.	See its
       documentation for details.

   "run"
       This method spawns a new	child process. It returns its process id.

       You can either call it with a single argument (string, arrayref,	or
       coderef), which will used as the	'Program' argument, or you can supply
       the following key-value pairs:

       'Program' (required), will be passed to directly	to POE::Wheel::Run's
       constructor.

       'ProgramArgs' (optional), will be passed	directly to POE::Wheel::Run's
       constructor.

       'Input' (optional), a string containing the input to the	process. This
       string, if provided, will be sent immediately to	the child, and its
       stdin will then be shut down. Note: no processing will be done on the
       data before it is sent. For instance, if	you are	executing a program
       which expects line-based	input, be sure to end your input with a
       newline.

       'StdoutEvent' (optional), the event for delivering lines	from the
       process'	STDOUT.	If you don't supply this, they will be printed to the
       main process's STDOUT. To explicitly ignore them, set this to "undef".

       'StderrEvent' (optional), the event for delivering lines	from the
       process'	STDERR.	If you don't supply this, they will be printed to the
       main process' STDERR. To	explicitly ignore them,	set this to "undef".

       'ExitEvent' (optional), the event to be called when the process has
       exited.	If you don't supply this, a warning indicating the exit	code
       will be printed if it is	nonzero. To explicitly ignore it, set this to
       "undef".

       'ResultEvent' (optional), like 'ExitEvent', but it will also contain
       all the stdout/stderr generated by the child process.

       'Context' (optional), a variable	which will be sent back	to you with
       every event. If you pass	a reference, that same reference will be
       delivered back to you later (not	a copy), so you	can update it as you
       see fit.

       'Timeout' (optional), a timeout in seconds after	which the process will
       be forcibly killed if it	is still running. There	is no timeout by
       default.

       'AltFork' (optional), if	true, a	new instance of	the active Perl
       interpreter ($^X) will be launched with 'Program' (which	must be	a
       string) as the code argument (-e), and the current @INC passed as
       include arguments (-I). Default is false.

       All other arguments will	be passed to POE::Wheel::Run's "new" method.
       Useful if you want to specify the input/output filters and such.

   "killall"
       This kills all processes	which POE::Quickie is managing for your
       session.	Takes one optional argument, a signal name (e.g.  'SIGTERM').

   "processes"
       Returns a hash reference	of all the currently running processes.	The
       key is the process id, and the value is the context variable, if	any.

OUTPUT
       The following events might get sent to your session. The	names
       correspond to the options to "run".

   StdoutEvent
       "ARG0": the chunk of STDOUT generated by	the process
       "ARG1": the process id of the child process
       "ARG2": the context variable, if	any

   StderrEvent
       "ARG0": the chunk of STDERR generated by	the process
       "ARG1": the process id of the child process
       "ARG2": the context variable, if	any

   ExitEvent
       "ARG0": the exit	code ($?) of the child process
       "ARG1": the process id of the child process
       "ARG2": the context variable, if	any

   ResultEvent
       "ARG0": the process id of the child process
       "ARG1": an array	of every chunk of stdout generated by the child
       process
       "ARG2": an array	of every chunk of stderr generated by the child
       process
       "ARG3": an array	of the interleaved stdout and stderr chunks
       "ARG4": the exit	code ($?) of the child process
       "ARG5": the context variable, if	any

FUNCTIONS
   "quickie_run"
       Equivalent to "POE::Quickie->run()", provided as	a convenience.

   Blocking functions
       The following functions are modeled after the ones provided by
       Capture::Tiny. They will	not return until the executed process has
       exited. However,	"run_one_timeslice" in POE::Kernel will	be called in
       the meantime, so	the rest of your application will continue to run.

       They all	take the same arguments	as the "run" method, except for	the
       '*Event'	and 'Context' arguments.

       Note: Since these functions block, you must be careful not to call them
       in event	handlers which were executed with "$poe_kernel->call()"	by
       other sessions, so you don't hold them up. A simple way to avoid	that
       is to "yield()" or "post()" a new event to your session and do it from
       there.

       "quickie"

       Returns 3 values: the stdout, stderr, and exit code ($?)	of the child
       process.

       "quickie_tee"

       Returns 3 values: an array of all stdout	chunks,	an array of all	stderr
       chunks, and the exit code ($?) of the child process. In addition, it
       will echo the stdout/stderr to your process' stdout/stderr.

       "quickie_merged"

       Returns 2 values: an array of interleaved stdout	and stderr chunks, and
       the exit	code ($?) of the child process.	Beware that stdout and stderr
       in the merged result are	not guaranteed to be properly ordered due to
       buffering.

       "quickie_tee_merged"

       Returns 2 values: an array of interleaved stdout	and stderr chunks, and
       the exit	code ($?) of the child process.	In addition, it	will echo the
       merged stdout & stderr to your process' stdout. Beware that stdout and
       stderr in the merged result are not guaranteed to be properly ordered
       due to buffering.

AUTHOR
       Hinrik Arn SigurA<degree>sson, hinrik.sig@gmail.com

LICENSE	AND COPYRIGHT
       Copyright 2010-2011 Hinrik Arn SigurA<degree>sson

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

perl v5.32.0			  2020-08-24		       POE::Quickie(3)

NAME | SYNOPSIS | DESCRIPTION | METHODS | OUTPUT | FUNCTIONS | AUTHOR | LICENSE AND COPYRIGHT

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

home | help