M_FORK(3P) — UNIX Programmer’s Manual

NAME

m_fork − execute a subprogram in parallel

SYNOPSIS

C syntax:

#include <parallel/microtask.h>
m_fork(func[,arg,...]);
void (∗func)();
sometype args;

Pascal syntax

function m_pfork: integer;
cexternal;
procedure func(arg,...);
(code)
m_pfork(func[,arg,...]);
args : sometype;

FORTRAN syntax

external func
integer∗4 m_fork
i=m_fork(func[,arg,...])
subroutine func(arg,...)

DESCRIPTION

The m_fork routine assigns a subprogram to child processes, which then cooperate in executing the subprogram in parallel. The number of child processes used by the m_fork call can be set with a previous call to m_set_procs. If m_set_procs has not been called, the number of child processes defaults to (number of CPUs on-line) /2. If the program has no child processes from previous m_fork calls, the call creates the child processes. If there are already child processes from a previous call, m_fork re-uses the existing processes.

When an m_fork call creates child processes, each child process is given a private integer variable called m_myid, which identifies it within the set of child processes being created. The parent process’s identification number is always zero. The first child process’s identification is 1, the second’s is 2, and so on. You can call the routine m_getmyid to find out the identification number of a child process (see m_getmyid(3P)).

For C programs, the header file /parallel/microtask.h contains an external declaration of the variable m_myid and the variable m_numprocs, which indicates the total number of processes executing the subprogram (including all the child processes and the parent process).

Once child processes are available, m_fork starts them executing the subprogram func with the given arguments. (For Pascal programs, func must be an inner scope procedure.) The child processes execute the subprogram until they all return from it. At this point, the program returns from the m_fork call and the child processes spin, waiting for more work. The program can either kill the child processes with a call to the routine m_kill, suspend them with a call to m_park_procs, or let the child processes spin until they are re-used by another m_fork call. If the child processes are to be re-used, the m_park_procs offers the most efficient use of the Sequent system, because it saves the CPU usage of having the processes spin and it saves the overhead of having to recreate processes on the next m_fork call.

You must ensure that arguments passed to the subprogram func are either “call-by-value” arguments or addresses of data in shared memory. They must not be addresses in the parent’s private data segment.

ERRORS

The m_fork call fails and no child processes are created if one of the following error conditions occurs:

[EINVAL] This call to m_fork is nested within a previous call.

[EAGAIN] The m_fork call would exceed nproc, the system’s limit on the total number of executing processes.

[EAGAIN] The m_fork call would exceed maxuprc, the system’s limit on executing processes for a single user.

NOTES

Each call to m_fork resets the global counter (see m_next(3P)).

Museum