doc: move mpi api to advanced api section

doc/chapters/advanced-api.texi

@@ -2,11 +2,12 @@
 
 @c This file is part of the StarPU Handbook.
 @c Copyright (C) 2009--2011  Universit@'e de Bordeaux 1
-@c Copyright (C) 2010, 2011, 2012  Centre National de la Recherche Scientifique
+@c Copyright (C) 2010, 2011, 2012, 2013  Centre National de la Recherche Scientifique
 @c Copyright (C) 2011, 2012 Institut National de Recherche en Informatique et Automatique
 @c See the file starpu.texi for copying conditions.
 
 @menu
+* MPI Interface::
 * Defining a new data interface::
 * Multiformat Data Interface::
 * Task Bundles::
@@ -18,6 +19,161 @@
 * Expert mode::
 @end menu
 
+@node MPI Interface
+@section MPI Interface
+
+@menu
+* Initialisation::
+* Communication::
+* Communication cache::
+@end menu
+
+@node Initialisation
+@subsection Initialisation
+
+@deftypefun int starpu_mpi_init (int *@var{argc}, char ***@var{argv}, int initialize_mpi)
+Initializes the starpumpi library. @code{initialize_mpi} indicates if
+MPI should be initialized or not by StarPU. If the value is not @code{0},
+MPI will be initialized by calling @code{MPI_Init_Thread(argc, argv,
+MPI_THREAD_SERIALIZED, ...)}.
+@end deftypefun
+
+@deftypefun int starpu_mpi_initialize (void)
+This function has been made deprecated. One should use instead the
+function @code{starpu_mpi_init()} defined above.
+This function does not call @code{MPI_Init}, it should be called beforehand.
+@end deftypefun
+
+@deftypefun int starpu_mpi_initialize_extended (int *@var{rank}, int *@var{world_size})
+This function has been made deprecated. One should use instead the
+function @code{starpu_mpi_init()} defined above.
+MPI will be initialized by starpumpi by calling @code{MPI_Init_Thread(argc, argv,
+MPI_THREAD_SERIALIZED, ...)}.
+@end deftypefun
+
+@deftypefun int starpu_mpi_shutdown (void)
+Cleans the starpumpi library. This must be called between calling
+@code{starpu_mpi} functions and @code{starpu_shutdown()}.
+@code{MPI_Finalize()} will be called if StarPU-MPI has been initialized
+by @code{starpu_mpi_init()}.
+@end deftypefun
+
+@deftypefun void starpu_mpi_comm_amounts_retrieve (size_t *@var{comm_amounts})
+Retrieve the current amount of communications from the current node in
+the array @code{comm_amounts} which must have a size greater or equal
+to the world size. Communications statistics must be enabled
+(@pxref{STARPU_COMM_STATS}).
+@end deftypefun
+
+@node Communication
+@subsection Communication
+
+The standard point to point communications of MPI have been
+implemented. The semantic is similar to the MPI one, but adapted to
+the DSM provided by StarPU. A MPI request will only be submitted when
+the data is available in the main memory of the node submitting the
+request.
+
+@deftypefun int starpu_mpi_send (starpu_data_handle_t @var{data_handle}, int @var{dest}, int @var{mpi_tag}, MPI_Comm @var{comm})
+Performs a standard-mode, blocking send of @var{data_handle} to the
+node @var{dest} using the message tag @code{mpi_tag} within the
+communicator @var{comm}.
+@end deftypefun
+
+@deftypefun int starpu_mpi_recv (starpu_data_handle_t @var{data_handle}, int @var{source}, int @var{mpi_tag}, MPI_Comm @var{comm}, MPI_Status *@var{status})
+Performs a standard-mode, blocking receive in @var{data_handle} from the
+node @var{source} using the message tag @code{mpi_tag} within the
+communicator @var{comm}.
+@end deftypefun
+
+@deftypefun int starpu_mpi_isend (starpu_data_handle_t @var{data_handle}, starpu_mpi_req *@var{req}, int @var{dest}, int @var{mpi_tag}, MPI_Comm @var{comm})
+Posts a standard-mode, non blocking send of @var{data_handle} to the
+node @var{dest} using the message tag @code{mpi_tag} within the
+communicator @var{comm}. After the call, the pointer to the request
+@var{req} can be used to test the completion of the communication.
+@end deftypefun
+
+@deftypefun int starpu_mpi_irecv (starpu_data_handle_t @var{data_handle}, starpu_mpi_req *@var{req}, int @var{source}, int @var{mpi_tag}, MPI_Comm @var{comm})
+Posts a nonblocking receive in @var{data_handle} from the
+node @var{source} using the message tag @code{mpi_tag} within the
+communicator @var{comm}. After the call, the pointer to the request
+@var{req} can be used to test the completion of the communication.
+@end deftypefun
+
+@deftypefun int starpu_mpi_isend_detached (starpu_data_handle_t @var{data_handle}, int @var{dest}, int @var{mpi_tag}, MPI_Comm @var{comm}, void (*@var{callback})(void *), void *@var{arg})
+Posts a standard-mode, non blocking send of @var{data_handle} to the
+node @var{dest} using the message tag @code{mpi_tag} within the
+communicator @var{comm}. On completion, the @var{callback} function is
+called with the argument @var{arg}.
+@end deftypefun
+
+@deftypefun int starpu_mpi_irecv_detached (starpu_data_handle_t @var{data_handle}, int @var{source}, int @var{mpi_tag}, MPI_Comm @var{comm}, void (*@var{callback})(void *), void *@var{arg})
+Posts a nonblocking receive in @var{data_handle} from the
+node @var{source} using the message tag @code{mpi_tag} within the
+communicator @var{comm}. On completion, the @var{callback} function is
+called with the argument @var{arg}.
+@end deftypefun
+
+@deftypefun int starpu_mpi_wait (starpu_mpi_req *@var{req}, MPI_Status *@var{status})
+Returns when the operation identified by request @var{req} is complete.
+@end deftypefun
+
+@deftypefun int starpu_mpi_test (starpu_mpi_req *@var{req}, int *@var{flag}, MPI_Status *@var{status})
+If the operation identified by @var{req} is complete, set @var{flag}
+to 1. The @var{status} object is set to contain information on the
+completed operation.
+@end deftypefun
+
+@deftypefun int starpu_mpi_barrier (MPI_Comm @var{comm})
+Blocks the caller until all group members of the communicator
+@var{comm} have called it.
+@end deftypefun
+
+@deftypefun int starpu_mpi_isend_detached_unlock_tag (starpu_data_handle_t @var{data_handle}, int @var{dest}, int @var{mpi_tag}, MPI_Comm @var{comm}, starpu_tag_t @var{tag})
+Posts a standard-mode, non blocking send of @var{data_handle} to the
+node @var{dest} using the message tag @code{mpi_tag} within the
+communicator @var{comm}. On completion, @var{tag} is unlocked.
+@end deftypefun
+
+@deftypefun int starpu_mpi_irecv_detached_unlock_tag (starpu_data_handle_t @var{data_handle}, int @var{source}, int @var{mpi_tag}, MPI_Comm @var{comm}, starpu_tag_t @var{tag})
+Posts a nonblocking receive in @var{data_handle} from the
+node @var{source} using the message tag @code{mpi_tag} within the
+communicator @var{comm}. On completion, @var{tag} is unlocked.
+@end deftypefun
+
+@deftypefun int starpu_mpi_isend_array_detached_unlock_tag (unsigned @var{array_size}, starpu_data_handle_t *@var{data_handle}, int *@var{dest}, int *@var{mpi_tag}, MPI_Comm *@var{comm}, starpu_tag_t @var{tag})
+Posts @var{array_size} standard-mode, non blocking send. Each post
+sends the n-th data of the array @var{data_handle} to the n-th node of
+the array @var{dest}
+using the n-th message tag of the array @code{mpi_tag} within the n-th
+communicator of the array
+@var{comm}. On completion of the all the requests, @var{tag} is unlocked.
+@end deftypefun
+
+@deftypefun int starpu_mpi_irecv_array_detached_unlock_tag (unsigned @var{array_size}, starpu_data_handle_t *@var{data_handle}, int *@var{source}, int *@var{mpi_tag}, MPI_Comm *@var{comm}, starpu_tag_t @var{tag})
+Posts @var{array_size} nonblocking receive. Each post receives in the
+n-th data of the array @var{data_handle} from the n-th
+node of the array @var{source} using the n-th message tag of the array
+@code{mpi_tag} within the n-th communicator of the array @var{comm}.
+On completion of the all the requests, @var{tag} is unlocked.
+@end deftypefun
+
+@node Communication cache
+@subsection Communication cache
+
+@deftypefun void starpu_mpi_cache_flush (MPI_Comm @var{comm}, starpu_data_handle_t @var{data_handle})
+Clear the send and receive communication cache for the data
+@var{data_handle}. The function has to be called synchronously by all
+the MPI nodes.
+The function does nothing if the cache mechanism is disabled (@pxref{STARPU_MPI_CACHE}).
+@end deftypefun
+
+@deftypefun void starpu_mpi_cache_flush_all_data (MPI_Comm @var{comm})
+Clear the send and receive communication cache for all data. The
+function has to be called synchronously by all the MPI nodes.
+The function does nothing if the cache mechanism is disabled (@pxref{STARPU_MPI_CACHE}).
+@end deftypefun
+
 @node Defining a new data interface
 @section Defining a new data interface
 

doc/chapters/mpi-support.texi

@@ -2,7 +2,7 @@
 
 @c This file is part of the StarPU Handbook.
 @c Copyright (C) 2009--2011  Universit@'e de Bordeaux 1
-@c Copyright (C) 2010, 2011, 2012  Centre National de la Recherche Scientifique
+@c Copyright (C) 2010, 2011, 2012, 2013  Centre National de la Recherche Scientifique
 @c Copyright (C) 2011 Institut National de Recherche en Informatique et Automatique
 @c See the file starpu.texi for copying conditions.
 
@@ -20,25 +20,14 @@ distributed application, by automatically issuing all required data transfers
 according to the task graph and an application-provided distribution.
 
 @menu
-* The API::
 * Simple Example::
 * Exchanging User Defined Data Interface::
 * MPI Insert Task Utility::
 * MPI Collective Operations::
 @end menu
 
-@node The API
-@section The API
-
-@menu
-* Compilation::
-* Initialisation::
-* Communication::
-* Communication cache::
-@end menu
-
-@node Compilation
-@subsection Compilation
+@node Simple Example
+@section Simple Example
 
 The flags required to compile or link against the MPI layer are then
 accessible with the following commands:
@@ -50,156 +39,6 @@ accessible with the following commands:
 
 Also pass the @code{--static} option if the application is to be linked statically.
 
-@node Initialisation
-@subsection Initialisation
-
-@deftypefun int starpu_mpi_init (int *@var{argc}, char ***@var{argv}, int initialize_mpi)
-Initializes the starpumpi library. @code{initialize_mpi} indicates if
-MPI should be initialized or not by StarPU. If the value is not @code{0},
-MPI will be initialized by calling @code{MPI_Init_Thread(argc, argv,
-MPI_THREAD_SERIALIZED, ...)}.
-@end deftypefun
-
-@deftypefun int starpu_mpi_initialize (void)
-This function has been made deprecated. One should use instead the
-function @code{starpu_mpi_init()} defined above.
-This function does not call @code{MPI_Init}, it should be called beforehand.
-@end deftypefun
-
-@deftypefun int starpu_mpi_initialize_extended (int *@var{rank}, int *@var{world_size})
-This function has been made deprecated. One should use instead the
-function @code{starpu_mpi_init()} defined above.
-MPI will be initialized by starpumpi by calling @code{MPI_Init_Thread(argc, argv,
-MPI_THREAD_SERIALIZED, ...)}.
-@end deftypefun
-
-@deftypefun int starpu_mpi_shutdown (void)
-Cleans the starpumpi library. This must be called between calling
-@code{starpu_mpi} functions and @code{starpu_shutdown()}.
-@code{MPI_Finalize()} will be called if StarPU-MPI has been initialized
-by @code{starpu_mpi_init()}.
-@end deftypefun
-
-@deftypefun void starpu_mpi_comm_amounts_retrieve (size_t *@var{comm_amounts})
-Retrieve the current amount of communications from the current node in
-the array @code{comm_amounts} which must have a size greater or equal
-to the world size. Communications statistics must be enabled
-(@pxref{STARPU_COMM_STATS}).
-@end deftypefun
-
-@node Communication
-@subsection Communication
-
-The standard point to point communications of MPI have been
-implemented. The semantic is similar to the MPI one, but adapted to
-the DSM provided by StarPU. A MPI request will only be submitted when
-the data is available in the main memory of the node submitting the
-request.
-
-@deftypefun int starpu_mpi_send (starpu_data_handle_t @var{data_handle}, int @var{dest}, int @var{mpi_tag}, MPI_Comm @var{comm})
-Performs a standard-mode, blocking send of @var{data_handle} to the
-node @var{dest} using the message tag @code{mpi_tag} within the
-communicator @var{comm}.
-@end deftypefun
-
-@deftypefun int starpu_mpi_recv (starpu_data_handle_t @var{data_handle}, int @var{source}, int @var{mpi_tag}, MPI_Comm @var{comm}, MPI_Status *@var{status})
-Performs a standard-mode, blocking receive in @var{data_handle} from the
-node @var{source} using the message tag @code{mpi_tag} within the
-communicator @var{comm}.
-@end deftypefun
-
-@deftypefun int starpu_mpi_isend (starpu_data_handle_t @var{data_handle}, starpu_mpi_req *@var{req}, int @var{dest}, int @var{mpi_tag}, MPI_Comm @var{comm})
-Posts a standard-mode, non blocking send of @var{data_handle} to the
-node @var{dest} using the message tag @code{mpi_tag} within the
-communicator @var{comm}. After the call, the pointer to the request
-@var{req} can be used to test the completion of the communication.
-@end deftypefun
-
-@deftypefun int starpu_mpi_irecv (starpu_data_handle_t @var{data_handle}, starpu_mpi_req *@var{req}, int @var{source}, int @var{mpi_tag}, MPI_Comm @var{comm})
-Posts a nonblocking receive in @var{data_handle} from the
-node @var{source} using the message tag @code{mpi_tag} within the
-communicator @var{comm}. After the call, the pointer to the request
-@var{req} can be used to test the completion of the communication.
-@end deftypefun
-
-@deftypefun int starpu_mpi_isend_detached (starpu_data_handle_t @var{data_handle}, int @var{dest}, int @var{mpi_tag}, MPI_Comm @var{comm}, void (*@var{callback})(void *), void *@var{arg})
-Posts a standard-mode, non blocking send of @var{data_handle} to the
-node @var{dest} using the message tag @code{mpi_tag} within the
-communicator @var{comm}. On completion, the @var{callback} function is
-called with the argument @var{arg}.
-@end deftypefun
-
-@deftypefun int starpu_mpi_irecv_detached (starpu_data_handle_t @var{data_handle}, int @var{source}, int @var{mpi_tag}, MPI_Comm @var{comm}, void (*@var{callback})(void *), void *@var{arg})
-Posts a nonblocking receive in @var{data_handle} from the
-node @var{source} using the message tag @code{mpi_tag} within the
-communicator @var{comm}. On completion, the @var{callback} function is
-called with the argument @var{arg}.
-@end deftypefun
-
-@deftypefun int starpu_mpi_wait (starpu_mpi_req *@var{req}, MPI_Status *@var{status})
-Returns when the operation identified by request @var{req} is complete.
-@end deftypefun
-
-@deftypefun int starpu_mpi_test (starpu_mpi_req *@var{req}, int *@var{flag}, MPI_Status *@var{status})
-If the operation identified by @var{req} is complete, set @var{flag}
-to 1. The @var{status} object is set to contain information on the
-completed operation.
-@end deftypefun
-
-@deftypefun int starpu_mpi_barrier (MPI_Comm @var{comm})
-Blocks the caller until all group members of the communicator
-@var{comm} have called it.
-@end deftypefun
-
-@deftypefun int starpu_mpi_isend_detached_unlock_tag (starpu_data_handle_t @var{data_handle}, int @var{dest}, int @var{mpi_tag}, MPI_Comm @var{comm}, starpu_tag_t @var{tag})
-Posts a standard-mode, non blocking send of @var{data_handle} to the
-node @var{dest} using the message tag @code{mpi_tag} within the
-communicator @var{comm}. On completion, @var{tag} is unlocked.
-@end deftypefun
-
-@deftypefun int starpu_mpi_irecv_detached_unlock_tag (starpu_data_handle_t @var{data_handle}, int @var{source}, int @var{mpi_tag}, MPI_Comm @var{comm}, starpu_tag_t @var{tag})
-Posts a nonblocking receive in @var{data_handle} from the
-node @var{source} using the message tag @code{mpi_tag} within the
-communicator @var{comm}. On completion, @var{tag} is unlocked.
-@end deftypefun
-
-@deftypefun int starpu_mpi_isend_array_detached_unlock_tag (unsigned @var{array_size}, starpu_data_handle_t *@var{data_handle}, int *@var{dest}, int *@var{mpi_tag}, MPI_Comm *@var{comm}, starpu_tag_t @var{tag})
-Posts @var{array_size} standard-mode, non blocking send. Each post
-sends the n-th data of the array @var{data_handle} to the n-th node of
-the array @var{dest}
-using the n-th message tag of the array @code{mpi_tag} within the n-th
-communicator of the array
-@var{comm}. On completion of the all the requests, @var{tag} is unlocked.
-@end deftypefun
-
-@deftypefun int starpu_mpi_irecv_array_detached_unlock_tag (unsigned @var{array_size}, starpu_data_handle_t *@var{data_handle}, int *@var{source}, int *@var{mpi_tag}, MPI_Comm *@var{comm}, starpu_tag_t @var{tag})
-Posts @var{array_size} nonblocking receive. Each post receives in the
-n-th data of the array @var{data_handle} from the n-th
-node of the array @var{source} using the n-th message tag of the array
-@code{mpi_tag} within the n-th communicator of the array @var{comm}.
-On completion of the all the requests, @var{tag} is unlocked.
-@end deftypefun
-
-@node Communication cache
-@subsection Communication cache
-
-@deftypefun void starpu_mpi_cache_flush (MPI_Comm @var{comm}, starpu_data_handle_t @var{data_handle})
-Clear the send and receive communication cache for the data
-@var{data_handle}. The function has to be called synchronously by all
-the MPI nodes.
-The function does nothing if the cache mechanism is disabled (@pxref{STARPU_MPI_CACHE}).
-@end deftypefun
-
-@deftypefun void starpu_mpi_cache_flush_all_data (MPI_Comm @var{comm})
-Clear the send and receive communication cache for all data. The
-function has to be called synchronously by all the MPI nodes.
-The function does nothing if the cache mechanism is disabled (@pxref{STARPU_MPI_CACHE}).
-@end deftypefun
-
-@page
-@node Simple Example
-@section Simple Example
-
 @cartouche
 @smallexample
 void increment_token(void)