M_FORK(3P)							    M_FORK(3P)

NAME    [Toc]    [Back]

     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    [Toc]    [Back]

     #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    [Toc]    [Back]

     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 busywait
 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    [Toc]    [Back]

     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 ALSO    [Toc]    [Back]

     sproc(2), blockproc(2), prctl(2), barrier(3P), usinit(3P),	ussetlock(3P).

DIAGNOSTICS    [Toc]    [Back]

     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.


									PPPPaaaaggggeeee 3333