NAME

MakeEvent -- event loop for makepp

USAGE

  use MakeEvent;

  $handle = new MakeEvent::Process STDOUT => ">> /tmp/junk", STDIN => undef,
    "shell command to execute";
  $handle = new MakeEvent::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

MakeEvent 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.

MakeEvent::event_loop

  &MakeEvent::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 MakeEvent::wait_until.

read_wait

  read_wait FILE_HANDLE, sub { ... };

Queue a subroutie 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 { ... }, sub { ... };
  $handle = when_done $handle1, $handle2, ..., sub { ... }, ERROR => sub { ... };
  $handle = when_done [$handle1, $handle2], sub { ... };
  $handle = when_done $handle, [sub { ... }, sub { ... }];

Calls the specified subroutine when the processes have finished or the other subroutines have been called. The argument list is flattened, so you can specify array references and when_done will insert the contents of the array at that point in the argument list.

You can specify more than one subroutine to call. In this case, the subroutines are called in sequence. The subroutines may 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.

Each subroutine should return these values. If you specify more than one subroutine, and the first returns a list of handles, the second is not called until all of those handles are done.

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.

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)