Daniel Pfeiffer > makepp > Mpp::Event

Download:
makepp-2.0.98.2.tgz

Dependencies

Annotate this POD

CPAN RT

New  3
Open  1
View/Report Bugs
Source   Latest Release: makepp-2.0.98.5

NAME ^

Mpp::Event -- event loop for makepp

USAGE ^

  use Mpp::Event;

  $handle = new Mpp::Event::Process STDOUT => ">> /tmp/junk", STDIN => undef,
    "shell command to execute";
  $handle = new Mpp::Event::Process sub { ... };

  $handle = when_done $handle1, $handle2, ..., sub {
  # Code that gets executed when the previous handles have finished.
  };

  $status = $handle->status;

  $status = wait_for $handle1, $handle2, ...;

  read_wait FILEHANDLE, sub { ... };
                                # Called when there is data to be read on
                                # the given file handle.

DESCRIPTION ^

Mpp::Event provides a way of multi-threading Perl code without actually using any of the thread extensions. It relies on Perl closures instead. So it's a little harder to write event-driven code than it would be if your code were threaded, but not much.

It also supports waiting for input availability on an arbitrary set of channels using the IO::Select module. Currently, it does not support waiting to write or waiting for exceptions.

Mpp::Event::event_loop

  &Mpp::Event::event_loop;

This is the main event loop. It waits for one event, processes it, and returns. You probably don't want to call this function directly; most likely, you want Mpp::Event::wait_until.

read_wait

  read_wait FILE_HANDLE, sub { ... };

Queue a subroutine to be activated whenever there is data on the given file handle (or IO::Handle object, or anything that can be supplied as an argument to IO::Select::new.

This is a one-shot queue. You must call read_wait again if you want the subroutine to be called again.

when_done

  $handle = when_done $handle1, $handle2, ..., sub { ... };
  $handle = when_done $handle1, $handle2, ..., sub { ... }, [subroutine args];
  $handle = when_done $handle1, $handle2, ..., sub { ... }, ERROR => sub { ... };
  $handle = when_done $handle1, $handle2, ..., sub { ... }, ERROR => $scalar;
  $handle = when_done $handle1, $handle2, ..., sub { ... }, [subroutine args], ERROR => sub { ... };
  $handle = when_done $handle1, $handle2, ..., sub { ... }, [subroutine args], ERROR => $scalar;

Calls the specified subroutine when the processes have finished or the other subroutines have been called. Scalar arguments are interpreted as handles, a reference to a subroutine is treated as a subroutine to call, and a reference to a list is a set of arguments to pass to the subroutine.

Ordinarily you would pass arguments into the subroutine via Perl's closure mechanism, but there do appear to be some bugs in this (in Perl 5.8.0) and so it is possible to pass arguments via an explicit argument list.

The subroutine should return any of the following values:

0

0 indicates success, as with Unix processes.

a non-zero value

A non-zero value indicates failure, and causes the error handler of any subroutine waiting to be called.

a list of handles

Doesn't activate anyone waiting for this subroutine until each handle in the list of handles has finished.

'ERROR', then a subroutine reference

The subroutine is called if an error status was returned by any of the handles. On entry to the subroutine, $_[0] is the error status code. The subroutine should return a status code just like the usual when_done subroutines.

'ERROR', then a scalar

Assign the scalar as the status, instead of the propagated one.

You can also specify an error handler, which is called if activity on any of the given handles returns an error. (It is not called if the subroutines themselves return an error; the error handler of whoever is waiting on them is called.) The error handler should return the same type of status code as the main routine. The error handler is called with the same arguments as the subroutines.

Instead of specifying the handles, you may also specify status codes. (This means that instead of keeping the handle object around, you can just store the status code when the handle has finished.)

wait_for

  $status = wait_for $handle1, $handle2, ...;

Waits for the processes or subroutines associated with the specified handles to finish, and returns the status.

AUTHOR ^

Gary Holt (holt@LNC.usc.edu)

syntax highlighting: