
Forks::Super version 0.28
=========================

Forks::Super provides drop-in replacements for the Perl
fork(), wait(), and waitpid() functions with
additional features for spawning background processes
and managing them, including:

   *  forking to shell command or subroutine

      can specify a shell command or a Perl subroutine
      (name or code reference) to invoke in the child
      process

   *  setting deadlines

      can specify a deadline (in relative or absolute
      time) for a background process to complete,
      with the background process being killed if it does
      not complete by the deadline.

   *  throttling

      Limiting the number of simultaneous processes.
      Callers can install their own functions to determine
      when the system is too busy to launch another
      job.

   *  dependencies

      Jobs can be specified to wait until other jobs
      have started and/or completed before they can begin.

   *  deferred jobs

      Jobs can be specified to start at some specific time in
      the future, or to be launched under some specific
      future conditions. Arbitrary priorities can be
      assigned to jobs so that more urgent jobs will be
      launched first

   *  access to standard child filehandles

      Parent process can have access to STDIN, STDOUT,
      and STDERR filehandles of child processes to
      facilitate interprocess communication

   *  timeouts on wait,waitpid calls

      extended  wait  and  waitpid  functions can take
      an optional timeout argument
      
   *  operating system features

      On some operating systems, the priority and CPU affinity
      of the child processes can be set.


INSTALLATION

The typical installation recipe

   perl Makefile.PL
   make
   make test
   make install

usually works. The unit tests assume they are
running on a moderately loaded system; intermittent
failures are more likely on a heavily loaded
system. If "make test" fails, it will often work
if you run it a second time.

It will take about 10 minutes to run the test suite
of the Forks::Super module with "make test". An
alternative is to run

   make fasttest

which will run the Forks::Super module tests in
parallel, using the Forks::Super module. Running
"make fasttest" will take about 1-2 minutes.


DEPENDENCIES

This module requires these other modules and libraries,
all included with the standard distribution:

    Carp
    Exporter
    POSIX
    IO::Handle

Forks::Super recommends and will make use of the following 
modules if they are installed, but will still be able
to perform all of its functions without using them:

    Time::HiRes

The bg_eval function, to evaluate Perl code in the background,
requires either YAML or JSON.

Certain operating system dependent features may not work
(usually failing silently) if these OS-specific modules
are not installed:

    Win32::Process [Windows and Cygwin]
    Win32          [Windows]
    Win32::API     [Windows]
    BSD::Process::Affinity [BSD]
    Inline, Inline::C


WINDOWS

Some features of this module do not work or work a
little differently with Windows systems. See the
README.windows file included in this distribution
for important information.


COPYRIGHT AND LICENCE

Copyright (c) 2009-2010, Marty O'Brien.

This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself, either Perl version 5.8.8 or,
at your option, any later version of Perl 5 you may have available.


