README.windows file for Forks::Super module
===========================================

Many standard functions of Perl are not
supported or not completely supported in
most of the ports to Windows, including
many features that would be useful to the
Forks::Super module.


1. Process groups and pseudo-process IDs

On Un*x systems, a process group is identified
with a negative value. In a Perl script, it can
be obtained with the getpgrp() function or set
with the setpgrp() function. A process group can
be used as an argument to  Forks::Super::waitpid  to wait
on any process that belongs to a process group.

In Windows, the getpgrp() and setpgrp() functions
are usually not supported, and the Perl  fork
call will usually return a negative value that
represents a psuedo-process id. On a Windows system,
calling  Forks::Super::waitpid  with a negative value on
a Windows system will be interpreted as waiting 
on a single child process with the specified 
pseudo-process ID.

See the  perlfork  POD for more information about
how  CORE::fork  is emulated on Windows.


2. Process priority

The getpriority() and setpriority() calls in Perl
are often not supported on Windows. If the
Win32::API  module is installed on your system,
then this module can emulate the getpriority() and
setpriority() functions. If  Win32::API  is
unavailable, then calling  Forks::Super::fork
with an  os_priority  option will have no effect.


3. Signal handling

The Forks::Super module provides features such as job
throttling (limiting the number of simultaneous
background proceses that can be running), job
dependencies (where one job will not start until
one or more other jobs have started and/or
finished), and job deferral (scheduling a job to
start at a future time). When a child process
finishes, this is often a trigger for other
child processes to begin. So it is important for
the Forks::Super module to be able to detect when a
child process has finished.

On POSIX systems, child processes send a SIGCHLD
signal to the parent process when they complete.
The Forks::Super module will install a SIGCHLD handler
that will manage cleanup of completed child
processes and attempt to dispatch the jobs that
are deferred. A SIGUSR1 handler may also be
installed. The SIGUSR1 handler may periodically
receive signals from a background process that 
will cause the Forks::Super module to attempt to 
dispatch deferred jobs from the queue. The design
goal was to keep these operations as transparent to
the user as possible. 

In Windows systems, it is more difficult to 
achieve this goal. There is no mechanism for
background processes to signal to the parent,
and so the parent process must poll the operating 
system to determine when child processes are
complete. This polling must occur in the main
execution thread. Such polling is built into
functions like  Forks::Super::wait  and  Forks::Super::waitpid,
but it is up to the caller whether these functions
are called in a timely manner. Windows users are
recommended to use the  Forks::Super::pause  function
as a *productive* drop-in replacement for the 
Perl  sleep  system call. The  Forks::Super::pause  function
will perform operating system polling and queue
management. The caller may also invoke  Forks::Super::pause
with an argument of  0  to perform these child
management functions but without any additional
delay.


4. Alarm

The Perl  alarm  system call is not fully supported 
on all systems, including all Windows ports of Perl
prior to 5.8.3.  The feature of passing a  timeout
or  expiration  option to a  Forks::Super::fork  
call depends on this feature, so the call
will fail when used with those options on systems that
cannot support  alarm().

On Windows systems that do implement  alarm() ,
it may not be fully functional. For example, the
SIGALRM signal might still not interrupt certain
system calls like  sysread().


5. Sockets are blocking

Sockets in Windows systems are always blocking.
If you invoke  fork { child_fh => [ "socket" ] }
to use sockets for parent-child interprocess
communication, you must take care not to read from
an empty socket handle or your script will hang.

In general, the 4-arg version of select does work
on Windows (but only on socket handles, not on pipes
or regular filehandles). You can use this command
to check whether there is input to be read on a
Windows socket handle.



The  perlfork  pod discusses many pitfalls of 
attempting to use  fork  under Windows systems.
All of these caveats also apply to any background
processes created with this module.