documentation.cpp

来自「Boost provides free peer-reviewed portab」· C++ 代码 · 共 672 行 · 第 1/3 页

// (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"