NAME

     bsp_begin - spawn a number of BSP processes.

C SYNOPSIS

     #include "bsp.h"

     void bsp_begin(int maxprocs);

FORTRAN SYNOPSIS

     SUBROUTINE bspbegin(maxprocs)
     INTEGER , intent(IN):: maxprocs

DESCRIPTION

     At most maxprocs processes are created in a  bsplib(3)  pro-
     gram  by  the  operations  bsp_begin  and  bsp_end(3).  They
     bracket a piece of code to be run in an  SPMD  manner  on  a
     number  of  processors.  There can only be one instance of a
     bsp_begin/bsp_end pair within a program, although there  are
     two different ways to start a bsplib(3) program:

     1)   If bsp_begin and bsp_end(3)  are  the  first  and  last
          statements in a program, then the entire bsplib(3) com-
          putation is SPMD.


     2)   An alternative  mode  (see  bsp_init(3))  is  available
          where  a single process starts execution and determines
          the number of parallel processes required for the  cal-
          culation.  It  can  then  spawn  the required number of
          processes using bsp_begin.  Execution  of  the  spawned
          processes  then  continue  in  an  SPMD  manner,  until
          bsp_end(3) is encountered by all the processes. At that
          point,  all but process zero is terminated, and process
          zero is left to continue the execution of the  rest  of
          the program sequentially.

EXAMPLE

     1)   Consider a C program that starts as many  processes  as
          possible, each printing the string ``Hello World''.
          #include "bsp.h"

          void main() {
            bsp_begin(bsp_nprocs());
              printf("Hello World from process %d of %d",
                     bsp_pid(),bsp_nprocs());
            bsp_end();
          }
          The example illustrates  the  minimum  requirements  of
          bsplib(3)  with  respect  to  I/O.  When  a  number  of
          processes print a message on either standard output  or
          standard  error,  the  messages  are multiplexed to the
          users terminal  in  a  non-deterministic  manner.   All
          other  types  of I/O (e.g., user input and file access)
          are only guaranteed to work correctly if  performed  by
          process  zero . Therefore this example prints p strings
          in an arbitrary order.


     2)   Consider a  Fortran  77  program  that  prints  ``Hello
          World'' in parallel.

                PROGRAM Main
                INCLUDE 'fbsp.h'

                CALL bspbegin(bspnprocs())
                WRITE (*,*) 'Hello World from ',bsppid(),' of ',bspnprocs()
                CALL bspend()

SEE ALSO

     bsplib(3), bsp_begin(3), bsp_end(3)

     ``BSPlib: The BSP Programming Library'' Jonathan M. D. Hill,
     Bill  McColl,  Dan  C.  Stefanescu,  Mark W. Goudreau, Kevin
     Lang, Satish B. Rao, , Torsten Suel, Thanasis Tsantilas, and
     Rob  Bisseling.  Parallel  Computing,  to  appear  1998. See
     http://www.bsp-worldwide.org for more details.

NOTES

     i    There can only  be  a  single  bsp_begin  bsp_end  pair
          within  a  bsplib(3) program.  This excludes the possi-
          bility  of  starting,  stopping,  and  then  restarting
          parallel  tasks within a program, or any form of nested
          parallelism.


     ii   The process with bsp_pid()==0 is a continuation of  the
          thread of control that initiated bsp_begin(3). This has
          the effect that all the values of the local and  global
          variables prior to bsp_begin are available to that pro-
          cess.


     iii  After bsp_begin, the environment from process  zero  is
          not  inherited  by  any  of  the other processes, i.e.,
          those with bsp_pid() greater than zero. If any of  them
          require  part  of  zero's  state, then the data must be
          transferred from process zero.

     iv   bsp_begin has to be the first  statement  of  the  pro-
          cedure which contains the statement. Similarly, bsp_end
          has to be the last statement in the same procedure.


     v    bsp_begin(bsp_nprocs()) can  be  used  to  request  the
          number of processes as there are processors on a paral-
          lel machine.

BUGS

     Problems  and  bug  reports  should  be  mailed  to  bsplib-
     bugs@comlab.ox.ac.uk

AUTHORS

     The Oxford BSP Toolset implementation of BSPlib was  written
     by Jonathan.Hill@comlab.ox.ac.uk
     http://www.comlab.ox.ac.uk/oucl/people/jonathan.hill.html