xref: /third_party/boost/libs/mpi/src/python/documentation.cpp

// (C) Copyright 2005 The Trustees of Indiana University.
// (C) Copyright 2006 Douglas Gregor <doug.gregor -at- gmail.com>

// Use, modification and distribution is subject to the Boost Software
// License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at
// http://www.boost.org/LICENSE_1_0.txt)

//  Authors: Douglas Gregor

/** @file documentation.cpp
 *
 *  This file contains all of the documentation strings for the
 *  Boost.MPI Python bindings.
 */
namespace boost { namespace mpi { namespace python {

const char* module_docstring =
  "The boost.mpi module contains Python wrappers for Boost.MPI.\n"
  "Boost.MPI is a C++ interface to the Message Passing Interface 1.1,\n"
  "a high-performance message passing library for parallel programming.\n"
  "\n"
  "This module supports the most commonly used subset of MPI 1.1. All\n"
  "communication operations can transmit any Python object that can be\n"
  "pickled and unpickled, along with C++-serialized data types and\n"
  "separation of the structure of a data type from its content.\n"
  "Collectives that have a user-supplied functions,\n"
  "such as reduce() or scan(), accept arbitrary Python functions, and\n"
  "all collectives can operate on any serializable or picklable data type.\n"
  "\n"
  "IMPORTANT MODULE DATA\n"
  "  any_source       This constant may be used for the source parameter of\n"
  "                   receive and probe operations to indicate that a\n"
  "                   message may be received from any source.\n"
  "\n"
  "  any_tag          This constant may be used for the tag parameter of\n"
  "                   receive or probe operations to indicate that a send\n"
  "                   with any tag will be matched.\n"
  "\n"
  "  collectives_tag  Returns the reserved tag value used by the Boost.MPI\n"
  "                   implementation for collective operations. Although\n"
  "                   users are not permitted to use this tag to send or\n"
  "                   receive messages with this tag, it may be useful when\n"
  "                   monitoring communication patterns.\n"
  "\n"
  "  host_rank        If there is a host process, this is the rank of that\n"
  "                   that process. Otherwise, this value will be None. MPI\n"
  "                   does not define the meaning of a \"host\" process: \n"
  "                   consult the documentation for your MPI implementation.\n"
  "\n"
  "  io_rank          The rank of a process that can perform input/output\n"
  "                   via the standard facilities. If every process can\n"
  "                   perform I/O using the standard facilities, this value\n"
  "                   will be the same as any_source. If no process can\n"
  "                   perform I/O, this value will be None.\n"
  "\n"
  "  max_tag          The maximum value that may be used for the tag\n"
  "                   parameter of send/receive operations. This value will\n"
  "                   be somewhat smaller than the value of MPI_TAG_UB,\n"
  "                   because the Boost.MPI implementation reserves some\n"
  "                   tags for collective operations.\n"
  "\n"
  "  processor_name   The name of this processor. The actual form of the\n"
  "                   of the name is unspecified, but may be documented by\n"
  "                   the underlying MPI implementation.\n"
  "\n"
  "  rank             The rank of this process in the \"world\" communicator.\n"
  "\n"
  "  size             The number of processes in the \"world\" communicator.\n"
  "                   that process. Otherwise, this value will be None. MPI\n"
  "                   does not define the meaning of a \"host\" process: \n"
  "\n"
  "  world            The \"world\" communicator from which all other\n"
  "                   communicators will be derived. This is the equivalent\n"
  "                   of MPI_COMM_WORLD.\n"
  "\n"
  "TRANSMITTING USER-DEFINED DATA\n"
  "  Boost.MPI can transmit user-defined data in several different ways.\n"
  "  Most importantly, it can transmit arbitrary Python objects by pickling\n"
  "  them at the sender and unpickling them at the receiver, allowing\n"
  "  arbitrarily complex Python data structures to interoperate with MPI.\n"
  "\n"
  "  Boost.MPI also supports efficient serialization and transmission of\n"
  "  C++ objects (that have been exposed to Python) through its C++\n"
  "  interface. Any C++ type that provides (de-)serialization routines that\n"
  "  meet the requirements of the Boost.Serialization library is eligible\n"
  "  for this optimization, but the type must be registered in advance. To\n"
  "  register a C++ type, invoke the C++ function:\n"
  "    boost::mpi::python::register_serialized\n"
  "\n"
  "  Finally, Boost.MPI supports separation of the structure of an object\n"
  "  from the data it stores, allowing the two pieces to be transmitted\n"
  "  separately. This \"skeleton/content\" mechanism, described in more\n"
  "  detail in a later section, is a communication optimization suitable\n"
  "  for problems with fixed data structures whose internal data changes\n"
  "  frequently.\n"
  "\n"
  "COLLECTIVES\n"
  "  Boost.MPI supports all of the MPI collectives (scatter, reduce, scan,\n"
  "  broadcast, etc.) for any type of data that can be transmitted with the\n"
  "  point-to-point communication operations. For the MPI collectives that\n"
  "  require a user-specified operation (e.g., reduce and scan), the\n"
  "  operation can be an arbitrary Python function. For instance, one could\n"
  "  concatenate strings with all_reduce:\n\n"
  "    mpi.all_reduce(my_string, lambda x,y: x + y)\n\n"
  "  The following module-level functions implement MPI collectives:\n"
  "    all_gather    Gather the values from all processes.\n"
  "    all_reduce    Combine the results from all processes.\n"
  "    all_to_all    Every process sends data to every other process.\n"
  "    broadcast     Broadcast data from one process to all other processes.\n"
  "    gather        Gather the values from all processes to the root.\n"
  "    reduce        Combine the results from all processes to the root.\n"
  "    scan          Prefix reduction of the values from all processes.\n"
  "    scatter       Scatter the values stored at the root to all processes.\n"
  "\n"
  "SKELETON/CONTENT MECHANISM\n"
  "  Boost.MPI provides a skeleton/content mechanism that allows the\n"
  "  transfer of large data structures to be split into two separate stages,\n"
  "  with the `skeleton' (or, `shape') of the data structure sent first and\n"
  "  the content (or, `data') of the data structure sent later, potentially\n"
  "  several times, so long as the structure has not changed since the\n"
  "  skeleton was transferred. The skeleton/content mechanism can improve\n"
  "  performance when the data structure is large and its shape is fixed,\n"
  "  because while the skeleton requires serialization (it has an unknown\n"
  "  size), the content transfer is fixed-size and can be done without\n"
  "  extra copies.\n"
  "\n"
  "  To use the skeleton/content mechanism from Python, you must first\n"
  "  register the type of your data structure with the skeleton/content\n"
  "  mechanism *from C++*. The registration function is\n"
  "    boost::mpi::python::register_skeleton_and_content\n"
  "  and resides in the <boost/mpi/python.hpp> header.\n"
  "\n"
  "  Once you have registered your C++ data structures, you can extract\n"
  "  the skeleton for an instance of that data structure with skeleton().\n"
  "  The resulting SkeletonProxy can be transmitted via the normal send\n"
  "  routine, e.g.,\n\n"
  "    mpi.world.send(1, 0, skeleton(my_data_structure))\n\n"
  "  SkeletonProxy objects can be received on the other end via recv(),\n"
  "  which stores a newly-created instance of your data structure with the\n"
  "  same `shape' as the sender in its `object' attribute:\n\n"
  "    shape = mpi.world.recv(0, 0)\n"
  "    my_data_structure = shape.object\n\n"
  "  Once the skeleton has been transmitted, the content (accessed via \n"
  "  get_content) can be transmitted in much the same way. Note, however,\n"
  "  that the receiver also specifies get_content(my_data_structure) in its\n"
  "  call to receive:\n\n"
  "    if mpi.rank == 0:\n"
  "      mpi.world.send(1, 0, get_content(my_data_structure))\n"
  "    else:\n"
  "      mpi.world.recv(0, 0, get_content(my_data_structure))\n\n"
  "  Of course, this transmission of content can occur repeatedly, if the\n"
  "  values in the data structure--but not its shape--changes.\n"
  "\n"
  "  The skeleton/content mechanism is a structured way to exploit the\n"
  "  interaction between custom-built MPI datatypes and MPI_BOTTOM, to\n"
  "  eliminate extra buffer copies.\n"
  "\n"
  "C++/PYTHON MPI COMPATIBILITY\n"
  "  Boost.MPI is a C++ library whose facilities have been exposed to Python\n"
  "  via the Boost.Python library. Since the Boost.MPI Python bindings are\n"
  "  build directly on top of the C++ library, and nearly every feature of\n"
  "  C++ library is available in Python, hybrid C++/Python programs using\n"
  "  Boost.MPI can interact, e.g., sending a value from Python but receiving\n"
  "  that value in C++ (or vice versa). However, doing so requires some\n"
  "  care. Because Python objects are dynamically typed, Boost.MPI transfers\n"
  "  type information along with the serialized form of the object, so that\n"
  "  the object can be received even when its type is not known. This\n"
  "  mechanism differs from its C++ counterpart, where the static types of\n"
  "  transmitted values are always known.\n"
  "\n"
  "  The only way to communicate between the C++ and Python views on \n"
  "  Boost.MPI is to traffic entirely in Python objects. For Python, this is\n"
  "  the normal state of affairs, so nothing will change. For C++, this\n"
  "  means sending and receiving values of type boost::python::object, from\n"
  "  the Boost.Python library. For instance, say we want to transmit an\n"
  "  integer value from Python:\n\n"
  "    comm.send(1, 0, 17)\n\n"
  "  In C++, we would receive that value into a Python object and then\n"
  "  `extract' an integer value:\n\n"
  "    boost::python::object value;\n"
  "    comm.recv(0, 0, value);\n"
  "    int int_value = boost::python::extract<int>(value);\n\n"
  "  In the future, Boost.MPI will be extended to allow improved\n"
  "  interoperability with the C++ Boost.MPI and the C MPI bindings.\n"
  ;

/***********************************************************
 * environment documentation                               *
 ***********************************************************/
const char* environment_init_docstring =
  "Initialize the MPI environment. Users should not need to call\n"
  "this function directly, because the MPI environment will be\n"
  "automatically initialized when the Boost.MPI module is loaded.\n";

const char* environment_finalize_docstring =
  "Finalize (shut down) the MPI environment. Users only need to\n"
  "invoke this function if MPI should be shut down before program\n"
  "termination. Boost.MPI will automatically finalize the MPI\n"
  "environment when the program exits.\n";

const char* environment_abort_docstring =
  "Aborts all MPI processes and returns to the environment. The\n"
  "precise behavior will be defined by the underlying MPI\n"
  "implementation. This is equivalent to a call to MPI_Abort with\n"
  "MPI_COMM_WORLD.\n"
  "errcode is the error code to return from aborted processes.\n";

const char* environment_initialized_docstring =
 "Determine if the MPI environment has already been initialized.\n";

const char* environment_finalized_docstring =
  "Determine if the MPI environment has already been finalized.\n";

/***********************************************************
 * nonblocking documentation                               *
 ***********************************************************/
const char* request_list_init_docstring=
  "Without arguments, constructs an empty RequestList.\n"
  "With one argument `iterable', copies request objects from this\n"
  "iterable to the new RequestList.\n";

const char* nonblocking_wait_any_docstring =
  "Waits until any of the given requests has been completed. It provides\n"
  "functionality equivalent to MPI_Waitany.\n"
  "\n"
  "requests must be a RequestList instance.\n"
  "\n"
  "Returns a triple (value, status, index) consisting of received value\n"
  "(or None), the Status object for the completed request, and its index\n"
  "in the RequestList.\n";

const char* nonblocking_test_any_docstring =
  "Tests if any of the given requests have been completed, but does not wait\n"
  "for completion. It provides functionality equivalent to MPI_Testany.\n"
  "\n"
  "requests must be a RequestList instance.\n"
  "\n"
  "Returns a triple (value, status, index) like wait_any or None if no request\n"
  "is complete.\n";

const char* nonblocking_wait_all_docstring =
  "Waits until all of the given requests have been completed. It provides\n"
  "functionality equivalent to MPI_Waitall.\n"
  "\n"
  "requests must be a RequestList instance.\n"
  "\n"
  "If the second parameter `callable' is provided, it is called with each\n"
  "completed request's received value (or None) and it s Status object as\n"
  "its arguments. The calls occur in the order given by the `requests' list.\n";

const char* nonblocking_test_all_docstring =
  "Tests if all of the given requests have been completed. It provides\n"
  "functionality equivalent to MPI_Testall.\n"
  "\n"
  "Returns True if all requests have been completed.\n"
  "\n"
  "requests must be a RequestList instance.\n"
  "\n"
  "If the second parameter `callable' is provided, it is called with each\n"
  "completed request's received value (or None) and it s Status object as\n"
  "its arguments. The calls occur in the order given by the `requests' list.\n";

const char* nonblocking_wait_some_docstring =
  "Waits until at least one of the given requests has completed. It\n"
  "then completes all of the requests it can, partitioning the input\n"
  "sequence into pending requests followed by completed requests.\n"
  "\n"
  "This routine provides functionality equivalent to MPI_Waitsome.\n"
  "\n"
  "Returns the index of the first completed request."
  "\n"
  "requests must be a RequestList instance.\n"
  "\n"
  "If the second parameter `callable' is provided, it is called with each\n"
  "completed request's received value (or None) and it s Status object as\n"
  "its arguments. The calls occur in the order given by the `requests' list.\n";

const char* nonblocking_test_some_docstring =
  "Tests to see if any of the given requests has completed. It completes\n"
  "all of the requests it can, partitioning the input sequence into pending\n"
  "requests followed by completed requests. This routine is similar to\n"
  "wait_some, but does not wait until any requests have completed.\n"
  "\n"
  "This routine provides functionality equivalent to MPI_Testsome.\n"
  "\n"
  "Returns the index of the first completed request."
  "\n"
  "requests must be a RequestList instance.\n"
  "\n"
  "If the second parameter `callable' is provided, it is called with each\n"
  "completed request's received value (or None) and it s Status object as\n"
  "its arguments. The calls occur in the order given by the `requests' list.\n";

/***********************************************************
 * exception documentation                                 *
 ***********************************************************/
const char* exception_docstring =
  "Instances of this class will be thrown when an MPI error\n"
  "occurs. MPI failures that trigger these exceptions may or may not\n"
  "be recoverable, depending on the underlying MPI implementation.\n"
  "Consult the documentation for your MPI implementation to determine\n"
  "the effect of MPI errors.\n";

const char* exception_what_docstring =
  "A description of the error that occured. At present, this refers\n"
  "only to the name of the MPI routine that failed.\n";

const char* exception_routine_docstring =
  "The name of the MPI routine that reported the error.\n";

const char* exception_result_code_docstring =
  "The result code returned from the MPI routine that reported the\n"
  "error.\n";

/***********************************************************
 * collectives documentation                               *
 ***********************************************************/
const char* all_gather_docstring =
  "all_gather is a collective algorithm that collects the values\n"
  "stored at each process into a tuple of values indexed by the\n"
  "process number they came from. all_gather is (semantically) a\n"
  "gather followed by a broadcast. The same tuple of values is\n"
  "returned to all processes.\n";

const char* all_reduce_docstring =
  "all_reduce is a collective algorithm that combines the values\n"
  "stored by each process into a single value. The values can be\n"
  "combined arbitrarily, specified via any function. The values\n"
  "a1, a2, .., ap provided by p processors will be combined by the\n"
  "binary function op into the result\n"
  "         op(a1, op(a2, ... op(ap-1,ap)))\n"
  "that will be returned to all processes. This function is the\n"
  "equivalent of calling all_gather() and then applying the built-in\n"
  "reduce() function to the returned sequence. op is assumed to be\n"
  "associative.\n";

const char* all_to_all_docstring =
  "all_to_all is a collective algorithm that transmits values from\n"
  "every process to every other process. On process i, the jth value\n"
  "of the values sequence is sent to process j and placed in the ith\n"
  "position of the tuple that will be returned from all_to_all.\n";

const char* broadcast_docstring =
  "broadcast is a collective algorithm that transfers a value from an\n"
  "arbitrary root process to every other process that is part of the\n"
  "given communicator (comm). The root parameter must be the same for\n"
  "every process. The value parameter need only be specified at the root\n"
  "root. broadcast() returns the same broadcasted value to every process.\n";

const char* gather_docstring =
  "gather is a collective algorithm that collects the values\n"
  "stored at each process into a tuple of values at the root\n"
  "process. This tuple is indexed by the process number that the\n"
  "value came from, and will be returned only by the root process.\n"
  "All other processes return None.\n";

const char* reduce_docstring =
  "reduce is a collective algorithm that combines the values\n"
  "stored by each process into a single value at the root. The\n"
  "values can be combined arbitrarily, specified via any function.\n"
  "The values a1, a2, .., ap provided by p processors will be\n"
  "combined by the binary function op into the result\n"
  "     op(a1, op(a2, ... op(ap-1,ap)))\n"
  "that will be returned on the root process. This function is the\n"
  "equivalent of calling gather() to the root and then applying the\n"
  "built-in reduce() function to the returned sequence. All non-root\n"
  "processes return None. op is assumed to be associative.\n";

const char* scan_docstring =
  "@c scan computes a prefix reduction of values from all processes.\n"
  "It is a collective algorithm that combines the values stored by\n"
  "each process with the values of all processes with a smaller rank.\n"
  "The values can be arbitrarily combined, specified via a binary\n"
  "function op. If each process i provides the value ai, then scan\n"
  "returns op(a1, op(a2, ... op(ai-1, ai))) to the ith process. op is\n"
  "assumed to be associative. This routine is the equivalent of an\n"
  "all_gather(), followed by a built-in reduce() on the first i+1\n"
  "values in the resulting sequence on processor i. op is assumed\n"
  "to be associative.\n";

const char* scatter_docstring =
  "scatter is a collective algorithm that scatters the values stored\n"
  "in the root process (as a container with comm.size elements) to\n"
  "all of the processes in the communicator. The values parameter \n"
  "(only significant at the root) is indexed by the process number to\n"
  "which the corresponding value will be sent. The value received by \n"
  "each process is returned from scatter.\n";

/***********************************************************
 * communicator documentation                              *
 ***********************************************************/
const char* communicator_docstring =
 "The Communicator class abstracts a set of communicating\n"
 "processes in MPI. All of the processes that belong to a certain\n"
 "communicator can determine the size of the communicator, their rank\n"
 "within the communicator, and communicate with any other processes\n"
 "in the communicator.\n";

const char* communicator_default_constructor_docstring =
  "Build a new Boost.MPI Communicator instance for MPI_COMM_WORLD.\n";

const char* communicator_rank_docstring =
  "Returns the rank of the process in the communicator, which will be a\n"
  "value in [0, size).\n";

const char* communicator_size_docstring =
  "Returns the number of processes in the communicator.\n";

const char* communicator_send_docstring =
  "This routine executes a potentially blocking send with the given\n"
  "tag to the process with rank dest. It can be received by the\n"
  "destination process with a matching recv call. The value will be\n"
  "transmitted in one of several ways:\n"
  "\n"
  "  - For C++ objects registered via register_serialized(), the value\n"
  "    will be serialized and transmitted.\n"
  "\n"
  "  - For SkeletonProxy objects, the skeleton of the object will be\n"
  "    serialized and transmitted.\n"
  "\n"
  "  - For Content objects, the content will be transmitted directly.\n"
  "    This content can be received by a matching recv/irecv call that\n"
  "    provides a suitable `buffer' argument.\n"
  "\n"
  "  - For all other Python objects, the value will be pickled and\n"
  "    transmitted.\n";

const char* communicator_recv_docstring =
  "This routine blocks until it receives a message from the process\n"
  "source with the given tag. If the source parameter is not specified,\n"
  "the message can be received from any process. Likewise, if the tag\n"
  "parameter is not specified, a message with any tag can be received.\n"
  "If return_status is True, returns a tuple containing the received\n"
  "object followed by a Status object describing the communication.\n"
  "Otherwise, recv() returns just the received object.\n"
  "\n"
  "When receiving the content of a data type that has been sent separately\n"
  "from its skeleton, user code must provide a value for the `buffer'\n"
  "argument. This value should be the Content object returned from\n"
  "get_content().\n";

const char* communicator_isend_docstring =
  "This routine executes a nonblocking send with the given\n"
  "tag to the process with rank dest. It can be received by the\n"
  "destination process with a matching recv call. The value will be\n"
  "transmitted in the same way as with send().\n"
  "This routine returns a Request object, which can be used to query\n"
  "when the transmission has completed, wait for its completion, or\n"
  "cancel the transmission.\n";

const char* communicator_irecv_docstring =
  "This routine initiates a non-blocking receive from the process\n"
  "source with the given tag. If the source parameter is not specified,\n"
  "the message can be received from any process. Likewise, if the tag\n"
  "parameter is not specified, a message with any tag can be received.\n"
  "This routine returns a Request object, which can be used to query\n"
  "when the transmission has completed, wait for its completion, or\n"
  "cancel the transmission. The received value be accessible\n"
  "through the `value' attribute of the Request object once transmission\n"
  "has completed.\n"
  "\n"
  "As with the recv() routine, when receiving the content of a data type\n"
  "that has been sent separately from its skeleton, user code must provide\n"
  "a value for the `buffer' argument. This value should be the Content\n"
  "object returned from get_content().\n";

 const char* communicator_probe_docstring =
  "This operation waits until a message matching (source, tag)\n"
  "is available to be received. It then returns information about\n"
  "that message. If source is omitted, a message from any process\n"
  "will match. If tag is omitted, a message with any tag will match.\n"
  "The actual source and tag can be retrieved from the returned Status\n"
  "object. To check if a message is available without blocking, use\n"
  "iprobe.\n";

const char* communicator_iprobe_docstring =
  "This operation determines if a message matching (source, tag) is\n"
  "available to be received. If so, it returns information about that\n"
  "message; otherwise, it returns None. If source is omitted, a message\n"
  "from any process will match. If tag is omitted, a message with any\n"
  "tag will match. The actual source and tag can be retrieved from the\n"
  "returned Status object. To wait for a message to become available, use\n"
  "probe.\n";

const char* communicator_barrier_docstring =
  "Wait for all processes within a communicator to reach the\n"
  "barrier.\n";

const char* communicator_split_docstring =
  "Split the communicator into multiple, disjoint communicators\n"
  "each of which is based on a particular color. This is a\n"
  "collective operation that returns a new communicator that is a\n"
  "subgroup of this. This routine is functionally equivalent to\n"
  "MPI_Comm_split.\n\n"
  "color is the color of this process. All processes with the\n"
  "same color value will be placed into the same group.\n\n"
  "If provided, key is a key value that will be used to determine\n"
  "the ordering of processes with the same color in the resulting\n"
  "communicator. If omitted, the key will default to the rank of\n"
  "the process in the current communicator.\n\n"
  "Returns a new Communicator instance containing all of the \n"
  "processes in this communicator that have the same color.\n";

const char* communicator_abort_docstring =
  "Makes a \"best attempt\" to abort all of the tasks in the group of\n"
  "this communicator. Depending on the underlying MPI\n"
  "implementation, this may either abort the entire program (and\n"
  "possibly return errcode to the environment) or only abort\n"
  "some processes, allowing the others to continue. Consult the\n"
  "documentation for your MPI implementation. This is equivalent to\n"
  "a call to MPI_Abort\n\n"
  "errcode is the error code to return from aborted processes.\n";

/***********************************************************
 * request documentation                                   *
 ***********************************************************/
const char* request_docstring =
  "The Request class contains information about a non-blocking send\n"
  "or receive and will be returned from isend or irecv, respectively.\n"
  "When a Request object represents a completed irecv, the `value' \n"
  "attribute will contain the received value.\n";

const char* request_with_value_docstring =
  "This class is an implementation detail. Any call that accepts a\n"
  "Request also accepts a RequestWithValue, and vice versa.\n";

const char* request_wait_docstring =
  "Wait until the communication associated with this request has\n"
  "completed. For a request that is associated with an isend(), returns\n"
  "a Status object describing the communication. For an irecv()\n"
  "operation, returns the received value by default. However, when\n"
  "return_status=True, a (value, status) pair is returned by a\n"
  "completed irecv request.\n";

const char* request_test_docstring =
  "Determine whether the communication associated with this request\n"
  "has completed successfully. If so, returns the Status object\n"
  "describing the communication (for an isend request) or a tuple\n"
  "containing the received value and a Status object (for an irecv\n"
  "request). Note that once test() returns a Status object, the\n"
  "request has completed and wait() should not be called.\n";

const char* request_cancel_docstring =
  "Cancel a pending communication, assuming it has not already been\n"
  "completed.\n";

const char* request_value_docstring =
  "If this request originated in an irecv(), this property makes the"
  "sent value accessible once the request completes.\n"
  "\n"
  "If no value is available, ValueError is raised.\n";

/***********************************************************
 * skeleton/content documentation                          *
 ***********************************************************/
const char* object_without_skeleton_docstring =
  "The ObjectWithoutSkeleton class is an exception class used only\n"
  "when the skeleton() or get_content() function is called with an\n"
  "object that is not supported by the skeleton/content mechanism.\n"
  "All C++ types for which skeletons and content can be transmitted\n"
  "must be registered with the C++ routine:\n"
  "  boost::mpi::python::register_skeleton_and_content\n";

const char* object_without_skeleton_object_docstring =
  "The object on which skeleton() or get_content() was invoked.\n";

const char* skeleton_proxy_docstring =
  "The SkeletonProxy class is used to represent the skeleton of an\n"
  "object. The SkeletonProxy can be used as the value parameter of\n"
  "send() or isend() operations, but instead of transmitting the\n"
  "entire object, only its skeleton (\"shape\") will be sent, without\n"
  "the actual data. Its content can then be transmitted, separately.\n"
  "\n"
  "User code cannot generate SkeletonProxy instances directly. To\n"
  "refer to the skeleton of an object, use skeleton(object). Skeletons\n"
  "can also be received with the recv() and irecv() methods.\n"
  "\n"
  "Note that the skeleton/content mechanism can only be used with C++\n"
  "types that have been explicitly registered.\n";

const char* skeleton_proxy_object_docstring =
  "The actual object whose skeleton is represented by this proxy object.\n";

const char* content_docstring =
  "The content is a proxy class that represents the content of an object,\n"
  "which can be separately sent or received from its skeleton.\n"
  "\n"
  "User code cannot generate content instances directly. Call the\n"
  "get_content() routine to retrieve the content proxy for a particular\n"
  "object. The content instance can be used with any of the send() or\n"
  "recv() variants. Note that get_content() can only be used with C++\n"
  "data types that have been explicitly registered with the Python\n"
  "skeleton/content mechanism.\n";

const char* skeleton_docstring =
  "The skeleton function retrieves the SkeletonProxy for its object\n"
  "parameter, allowing the transmission of the skeleton (or \"shape\")\n"
  "of the object separately from its data. The skeleton/content mechanism\n"
  "is useful when a large data structure remains structurally the same\n"
  "throughout a computation, but its content (i.e., the values in the\n"
  "structure) changes several times. Tranmission of the content part does\n"
  "not require any serialization or unnecessary buffer copies, so it is\n"
  "very efficient for large data structures.\n"
  "\n"
  "Only C++ types that have been explicitly registered with the Boost.MPI\n"
  "Python library can be used with the skeleton/content mechanism. Use:\b"
  "  boost::mpi::python::register_skeleton_and_content\n";

const char* get_content_docstring =
  "The get_content function retrieves the content for its object parameter,\n"
  "allowing the transmission of the data in a data structure separately\n"
  "from its skeleton (or \"shape\"). The skeleton/content mechanism\n"
  "is useful when a large data structure remains structurally the same\n"
  "throughout a computation, but its content (i.e., the values in the\n"
  "structure) changes several times. Tranmission of the content part does\n"
  "not require any serialization or unnecessary buffer copies, so it is\n"
  "very efficient for large data structures.\n"
  "\n"
  "Only C++ types that have been explicitly registered with the Boost.MPI\n"
  "Python library can be used with the skeleton/content mechanism. Use:\b"
  "  boost::mpi::python::register_skeleton_and_content\n";

/***********************************************************
 * status documentation                                    *
 ***********************************************************/
const char* status_docstring =
  "The Status class stores information about a given message, including\n"
  "its source, tag, and whether the message transmission was cancelled\n"
  "or resulted in an error.\n";

const char* status_source_docstring =
  "The source of the incoming message.\n";

const char* status_tag_docstring =
  "The tag of the incoming message.\n";

const char* status_error_docstring =
  "The error code associated with this transmission.\n";

const char* status_cancelled_docstring =
  "Whether this transmission was cancelled.\n";

/***********************************************************
 * timer documentation                                     *
 ***********************************************************/
const char* timer_docstring =
  "The Timer class is a simple wrapper around the MPI timing facilities.\n";

const char* timer_default_constructor_docstring =
  "Initializes the timer. After this call, elapsed == 0.\n";

const char* timer_restart_docstring =
  "Restart the timer, after which elapsed == 0.\n";

const char* timer_elapsed_docstring =
  "The time elapsed since initialization or the last restart(),\n"
  "whichever is more recent.\n";

const char* timer_elapsed_min_docstring =
  "Returns the minimum non-zero value that elapsed may return\n"
  "This is the resolution of the timer.\n";

const char* timer_elapsed_max_docstring =
  "Return an estimate of the maximum possible value of elapsed. Note\n"
  "that this routine may return too high a value on some systems.\n";

const char* timer_time_is_global_docstring =
  "Determines whether the elapsed time values are global times or\n"
  "local processor times.\n";

} } } // end namespace boost::mpi::python