M_SET_PROCS(3P)

NAME
m_set_procs - set number of child processes

SYNOPSIS
C syntax:

#include <parallel/microtask.h>
int m_set_procs(nprocs);
int nprocs;

Pascal syntax

function m_set_procs (numprocs : longint) : longint;
cexternal;

FORTRAN syntax

integer*4 function m_set_procs(nprocs)
integer*4 nprocs

DESCRIPTION
The m_set_procs routine declares the number of processes to execute subprograms in parallel on subsequent calls to m_fork. The argument nprocs declares the total number of processes that will run in parallel, including the parent process and the child processes. If nprocs is zero, the program creates no child processes, but all barriers and locks are initialized as if the program were going to create child processes.

The m_set_procs routine initializes a shared variable called m_numprocs, which controls the number of processes created by subsequent calls to m_fork. The C header file /usr/include/parallel/microtask.h contains an external declaration of m_numprocs, as well as the constant MAXPROCS which determines the maximum number of processes that the system will allow the program to create. The number of processes the program can create is not limited by the number of CPUs in the system, it is only limited by MAXPROCS.

The m_set_procs routine is optional: if the program does not call this routine before calling m_fork, the number of processes defaults to (number of CPUs on-line)/2. The program must not call m_set_procs while the child processes from an m_fork call are still alive (that is, before an m_kill_procs call to kill the child processes).

ERRORS
If an m_set_procs call is successful, the return value is zero. If the call fails, the return value is -1 and the variable errno holds the error code.

The m_set_procs call fails if one of the following error conditions occurs:

[EINVAL]
    The argument nprocs is greater than MAXPROCS or it is greater than or equal to the number of on-line CPUs.

[EINVAL]
    Children from an m_fork call are already running. In this case, call m_kill_procs to kill the existing child processes before calling m_set_procs.

NOTES
The number of processes that can be assigned is no longer restricted by the number of CPUs on-line minus 1. In order to retain that limit, a call to cpus_online() should be made, and that number minus one should then be sent to m_set_procs.

SEE ALSO
m_fork(3P), m_kill_procs(3P), Guide to Parallel Programming