XMPI_Buoy  -   LAM/MPI-specific function to drop a buoy in
       the XMPI trace stream.


SYNOPSIS

       #include <mpi.h>
       int
       XMPI_Buoy(const char* name)


INPUT PARAMETER

       name   - buoy name (string)


NOTES

       The LAM implementation of MPI is integrated with the  XMPI
       run/debug  viewer.  It can generate tracefiles and on-the-
       fly trace streams suitable for display in XMPI.

       A new functionality in XMPI is the ability to view "buoys"
       in the trace stream that can be helpful in marking partic­
       ular sections of code.  LAM/MPI  allows  the  dropping  of
       buoys with the XMPI_Buoy function.  Calling XMPI_Buoy with
       a string will drop a bouy of  that  name  (if  tracing  is
       enabled)  in the trace stream.  Dropping a buoy is a local
       action; the call will return  immediately.   The  buoy  is
       dropped  in  the  trace stream of the local rank, and will
       appear on the corresponding rank timeline in XMPI.

       The name can be a maximum of 32 characters long; if it  is
       longer, it will be truncated.

       If this function is invoked and tracing is not active, the
       buoy is ignored.

       There is no profiling version of this function.

       This is a LAM/MPI-specific function and is intended mainly
       for use with XMPI.  If this function is used, it should be
       used in conjunction with the LAM_MPI C preprocessor macro

       #if LAM_MPI
       XMPI_Buoy("my function begins");
       // ... message passing code
       XMPI_Buoy("my function ends");
       #endif


NOTES FOR FORTRAN

       All MPI routines in  Fortran  (except  for  MPI_WTIME  and
       MPI_WTICK ) have an additional argument ierr at the end of
       the argument list.  ierr is an integer and  has  the  same
       meaning  as the return value of the routine in C.  In For­
       tran, MPI routines are subroutines, and are  invoked  with


       All  MPI  objects  (e.g., MPI_Datatype , MPI_Comm ) are of
       type INTEGER in Fortran.


ERRORS

       If an error occurs in an MPI  function,  the  current  MPI
       error  handler  is  called to handle it.  By default, this
       error handler aborts the MPI job.  The error  handler  may
       be  changed with MPI_Errhandler_set ; the predefined error
       handler MPI_ERRORS_RETURN may be used to cause error  val­
       ues  to  be returned (in C and Fortran; this error handler
       is less useful in with the C++ MPI bindings.   The  prede­
       fined error handler MPI::ERRORS_THROW_EXCEPTIONS should be
       used in C++ if the error value  needs  to  be  recovered).
       Note  that  MPI does not guarantee that an MPI program can
       continue past an error.

       All MPI routines (except MPI_Wtime and MPI_Wtick )  return
       an  error  value;  C routines as the value of the function
       and Fortran routines in the last argument.  The C++  bind­
       ings  for  MPI  do not return error values; instead, error
       values are communicated by  throwing  exceptions  of  type
       MPI::Exception  (but not by default).  Exceptions are only
       thrown if the error value is not MPI::SUCCESS .

       Note that if the MPI::ERRORS_RETURN handler is set in C++,
       while  MPI functions will return upon an error, there will
       be no way to recover what the actual error value was.
       MPI_SUCCESS
              - No error; MPI routine completed successfully.
       MPI_ERR_ARG
              - Invalid argument.  Some argument is  invalid  and
              is  not identified by a specific error class.  This
              is typically a NULL pointer or other such error.
       MPI_ERR_INTERN
              - An internal error has  been  detected.   This  is
              fatal.  Please send a bug report to the LAM mailing
              list (see http://www.lam-mpi.org/contact.php ).


SEE ALSO

       XMPI_Coloron, XMPI_Coloroff


LOCATION

       xbuoy.c


Man(1) output converted with man2html