MP(3C)MP(3C) NAME mp, mp_block, mp_blocktime, mp_create, mp_destroy, mp_my_threadnum, mp_numthreads, mp_set_numthreads, mp_setup, mp_unblock, mp_setlock, mp_suggested_numthreads, mp_unsetlock, mp_barrier, mp_in_doacross_loop, mp_set_slave_stacksize - C multiprocessing utility functions SYNOPSIS void mp_block() void mp_unblock() void mp_blocktime(iters) int iters void mp_setup() void mp_create(num) int num void mp_destroy() int mp_numthreads() void mp_set_numthreads(num) int num int mp_my_threadnum() int mp_is_master() void mp_setlock() void mp_unsetlock() void mp_barrier() int mp_in_doacross_loop() void mp_set_slave_stacksize(size) int size unsigned int mp_suggested_numthreads(num) unsigned int num DESCRIPTION The following routines control the parallelism used in C programs. Although not needed by most users, they help to tune specific applications. mp_block Puts all slave threads to sleep via blockproc(2). This frees the processors for use by other jobs. This is useful if it is known that the slaves will not be needed for some time, and the machine is being shared by several users. Calls to mp_block may not be nested; a warning is issued if an attempt to do so is made. mp_unblock Wakes up the slave threads that were previously blocked via mp_block. It is an error to unblock threads that are not currently blocked; a warning is issued if an attempt is made to do so. It is not necessary to explicitly call mp_unblock. When a parallel region is entered, a check is made, and if the slaves are currently blocked, a call is made to mp_unblock automatically. mp_blocktime Controls the amount of time a slave thread waits for work before giving up. When enough time has elapsed, the slave thread blocks itself. This automatic blocking is independent of the user level blocking provided by the mp_block/mp_unblock calls. Slave threads that have blocked themselves will be automatically unblocked upon entering a parallel region. The argument to mp_blocktime is the number of times to spin in the wait loop. By default, it is set to 10,000,000. This takes about .25 seconds on a 200MHz processor. As a special case, an argument of 0 disables the automatic blocking, and the slaves will spin wait without limit. The environment variable MP_BLOCKTIME may be set to an integer value. It acts like an implicit call to mp_blocktime during program startup. mp_destroy Deletes the slave threads. They are stopped by forcing them to call exit(2). An alternative is to specify mp_block. mp_create Creates and initializes threads. It creates enough threads so that the total number is equal to the argument. Because the calling thread counts as one, mp_create will create one less than its argument in new slave threads. mp_setup Also creates and initializes threads. It takes no arguments. It simply calls mp_create using the current default number of threads. Usually, the default number is equal to the number of CPUs currently on the machine. If the user has not already called either of the thread creation routines, then mp_setup is invoked automatically when the first parallel region is entered. If the MP_SETUP environment variable is set, then mp_setup is called during initialization, before any user code is executed. mp_numthreads Returns the number of threads that would participate in an immediately following parallel region. If the threads have already been created, then it returns the current number of threads. If the threads have not been created, then it returns the current default number of threads. The count includes the master thread. Knowing this count can be useful in optimizing certain kinds of parallel loops by hand, but this function has the side-effect of freezing the number of threads to the returned value. As a result, this routine should be used sparingly. To determine the number of threads without this side-effect, see the following description of mp_suggested_numthreads. mp_set_numthreads Sets the current default number of threads to the specified value. Note that this call does not directly create the threads, it only specifies the number that a subsequent mp_setup call should use. If the MP_SET_NUMTHREADS environment variable is set, it acts like an implicit call to mp_set_numthreads during program startup. For convenience when operating among several machines with different numbers of CPUs, MP_SET_NUMTHREADS can be set to an expression involving integer literals, the binary operators + and -, the binary functions min and max, and the special ALL symbolic value, which stands for "the total number of available CPUs on the current machine." Thus, the following example would set the number of threads to seven: setenv MP_SET_NUMTHREADS 7 The following example sets the number of threads on a 4 CPU machine to be one less than the number of CPUs on the current machine (but always at least one): setenv MP_SET_NUMTHREADS "max(1,all-1)" If your configuration includes some machines with large numbers of CPUs, it is helpful to set an upper bound. The following example will request (no more than) 4 CPUs: setenv MP_SET_NUMTHREADS "min(all,4)" For compatibility with earlier releases, NUM_THREADS is supported as a synonym for MP_SET_NUMTHREADS. mp_my_threadnum Returns an integer between 0 and n-1 where n is the value returned by mp_numthreads. The master process is always thread 0. This is occasionally useful for optimizing certain kinds of loops by hand. mp_is_master Returns 1 if called by the master process, otherwise 0 is returned.. mp_setlock Provides convenient (though limited) access to the locking routines. The convenience is that no set up is required; it may be called directly without any preliminaries. The limitation is that there is only one lock. It is analogous to the ussetlock(3P) routine, but it takes no arguments and does not return a value. This is useful for serializing access to shared variables (e.g. counters) in a parallel region. Note that it will frequently be necessary to declare those variables as volatile to ensure that the optimizer does not assign them to a register. mp_unsetlock The companion routine for mp_setlock. It also takes no arguments and does not return a value. mp_barrier Provides a simple interface to a single barrier(3P). It may be used inside a parallel loop to force a barrier synchronization to occur among the parallel threads. The routine takes no arguments, returns no value, and does not require any initialization. mp_in_doacross_loop Answers the question "Am I currently executing inside a parallel loop?" This is useful in certain rare situations where you have an external routine that can be called both from inside a parallel loop and also from outside a parallel loop, and the routine must do different things depending on whether or not it is being called in parallel. mp_set_slave_stacksize Sets the stacksize (in bytes) to be used by the slave processes when they are created (via sprocsp(2)). The default size is 16MB. Note that slave processes only allocate their local data onto their stack; shared data (even if allocated on the master's stack) is not counted. mp_suggested_numthreads Uses the supplied value as a hint about how many threads to use in subsequent parallel regions, and returns the previous value of the number of threads to be employed in parallel regions. It does not affect any currently executing parallel regions. The implementation may ignore this hint depending on factors such as overall system load. This routine may also be called with the value 0, in which case it simply returns the number of threads to be employed in parallel regions without the side-effect present in mp_numthreads. #pragma Directives The MIPSpro C and C++ compilers allow you to apply the capabilities of a Silicon Graphics multiprocessor computer to the execution of a single job. By coding a few simple directives, the compiler splits the job into concurrently executing pieces, thereby decreasing the wall- clock run time of the job. Directives enable, disable, or modify a feature of the compiler. Essentially, directives are command line options specified within the input file instead of on the command line. Unlike command line options, directives have no default setting. To invoke a directive, you must either toggle it on or set a desired value for its level. The following directives can be used in C (and C++) programs when compiled with the -mp option. * #pragma parallel * #pragma pfor * #pragma critical * #pragma independent * #pragma synchronize * #pragma enter gate * #pragma exit gate * #pragma page_place SEE ALSO cc(1), f77(1) C Language Reference Manual MIPSpro Fortran 77 Programmer's Guide