mirror of
https://github.com/boostorg/mpi.git
synced 2026-01-22 05:22:18 +00:00
672 lines
34 KiB
C++
672 lines
34 KiB
C++
// (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
|