M_FORK(3P)M_FORK(3P)NAME
m_fork, m_kill_procs, m_set_procs, m_get_numprocs, m_get_myid, m_next,
m_lock, m_unlock, m_park_procs, m_rele_procs, m_sync - parallel
programming primitives
C SYNOPSIS
#include <ulocks.h>
#include <task.h>
int m_fork (void (*func)(), ...);
int m_kill_procs (void);
int m_set_procs (int numprocs);
int m_get_numprocs (void);
int m_get_myid (void);
unsigned m_next (void);
void m_lock (void);
void m_unlock (void);
int m_park_procs (void);
int m_rele_procs (void);
void m_sync (void);
DESCRIPTION
The m_fork routine creates n-1 processes that execute the given func in
parallel with the calling process. The processes are created using the
sproc(2) system call, and share all attributes (virtual address space,
file descriptors, uid, etc.). Once the processes are all created, they
each start executing the subprogram func taking up to six arguments as
passed to m_fork. The arguments passed must not be larger than pointers
in size, i.e. floating point numbers must be passed by reference.
The processes execute the subprogram and wait until they all return, at
which point the m_fork call returns. The other threads are left busy-
wait spinning until the master again calls m_fork. The overhead of
creating the additional process was done in the first call to m_fork and
is not repeated. m_fork sets a flag (see prctl(2)) so that if any of the
threads terminate, they will all receive a SIGTERM signal. Certain
operations such as profiling require that the various threads exit
normally (via the exit(2)) call. This can best be done by using
m_kill_procs to terminate the slave threads, then have the master itself
exit.
Page 1
M_FORK(3P)M_FORK(3P)
The number of subtasks n can be set and queried using m_set_procs and
m_get_numprocs, where the default is the number of processors in the
system (and hence the maximum number of processes that can truly be run
in parallel). Note that although up to 256 tasks may be requested, the
busy-wait rendezvous mechanism will usually result in a large performance
loss with any more threads than processors.
If sproc(2) is used with the PR_SADDR flag (share virtual address space),
m_set_procs should not be called more than once in the same program with
different values. To set the number of tasks more than once (with
different values) in the same program, either use sproc(2) without the
PR_SADDR (shared virtual address space) option or use fork instead of
sproc(2).
When the processes are created, each is assigned a unique thread
identifier (its tid). This identifier can be obtained through
m_get_myid. Thread id's range from 0 to n-1.
A global counter and a global lock are provided to simplify
synchronization between the processes. On each m_fork call, the counter
is reset to zero. The counter value is gotten and post incremented
through the m_next routine. The first time m_next is called, it returns
a zero. The global lock is set and unset through m_lock and m_unlock.
The m_park_procs and m_rele_procs are provided to suspend and resume the
child processes created by m_fork. This is useful if you have a phase of
the program where the parent will do setup or reinitialization code and
you do not want to have the children spinning and wasting resources.
m_park_procs should not be called when processes are already suspended.
m_sync is provided to synchronize all threads at some point in the code.
When m_sync is called by each thread, it waits at that point for all
other threads to call m_sync. The global counter is reset, and all
threads resume after the m_sync call.
m_kill_procs terminates the processes created from the previous m_fork.
Most errors from m_fork come from either sproc(2) or usinit(3P). See
those manual pages for more information on errors.
NOTES
These primitives are based on the Sequent Computer Systems parallel
programming primitives, but may not conform to all Sequent semantics.
Diagnostic output analyzing the failures in m_lock(3P) and the routines
that m_fork calls can be gotten using the _utrace mechanism discussed in
the usinit(3P) manual page.
m_fork will not work properly if the parent of the current process has
also called it. To avoid this problem, the parent should call
m_kill_procs prior to forking.
Page 2
M_FORK(3P)M_FORK(3P)SEE ALSOsproc(2), blockproc(2), prctl(2), barrier(3P), usinit(3P), ussetlock(3P).
DIAGNOSTICS
m_fork, m_set_procs, m_park_procs, m_rele_procs, and m_kill_procs return
a 0 when successful, and a -1 with errno set upon failure.
m_get_numprocs, m_get_myid, and m_next all return integers. m_lock,
m_unlock, and m_sync return no value.
Page 3
