boost/mpi/python.hpp

0001 // Copyright (C) 2006 Douglas Gregor <doug.gregor -at- gmail.com>
0002
0003 // Use, modification and distribution is subject to the Boost Software
0004 // License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at
0005 // http://www.boost.org/LICENSE_1_0.txt)
0006
0007 //  Authors: Douglas Gregor
0008 #ifndef BOOST_MPI_PYTHON_HPP
0009 #define BOOST_MPI_PYTHON_HPP
0010
0011 #include <boost/python/object.hpp>
0012
0013 /** @file python.hpp
0014  *
0015  *  This header interacts with the Python bindings for Boost.MPI. The
0016  *  routines in this header can be used to register user-defined and
0017  *  library-defined data types with Boost.MPI for efficient
0018  *  (de-)serialization and separate transmission of skeletons and
0019  *  content.
0020  *
0021  */
0022
0023 namespace boost { namespace mpi { namespace python {
0024
0025 /**
0026  * @brief Register the type T for direct serialization within Boost.MPI
0027  *
0028  * The @c register_serialized function registers a C++ type for direct
0029  * serialization within Boost.MPI. Direct serialization elides the use
0030  * of the Python @c pickle package when serializing Python objects
0031  * that represent C++ values. Direct serialization can be beneficial
0032  * both to improve serialization performance (Python pickling can be
0033  * very inefficient) and to permit serialization for Python-wrapped
0034  * C++ objects that do not support pickling.
0035  *
0036  *  @param value A sample value of the type @c T. This may be used
0037  *  to compute the Python type associated with the C++ type @c T.
0038  *
0039  *  @param type The Python type associated with the C++ type @c
0040  *  T. If not provided, it will be computed from the same value @p
0041  *  value.
0042  */
0043 template<typename T>
0044 void
0045 register_serialized(const T& value = T(), PyTypeObject* type = 0);
0046
0047 /**
0048  * @brief Registers a type for use with the skeleton/content mechanism
0049  * in Python.
0050  *
0051  * The skeleton/content mechanism can only be used from Python with
0052  * C++ types that have previously been registered via a call to this
0053  * function. Both the sender and the transmitter must register the
0054  * type. It is permitted to call this function multiple times for the
0055  * same type @c T, but only one call per process per type is
0056  * required. The type @c T must be Serializable.
0057  *
0058  *  @param value A sample object of type T that will be used to
0059  *  determine the Python type associated with T, if @p type is not
0060  *  specified.
0061  *
0062  *  @param type The Python type associated with the C++ type @c
0063  *  T. If not provided, it will be computed from the same value @p
0064  *  value.
0065  */
0066 template<typename T>
0067 void
0068 register_skeleton_and_content(const T& value = T(), PyTypeObject* type = 0);
0069
0070 } } } // end namespace boost::mpi::python
0071
0072 #ifndef BOOST_MPI_PYTHON_FORWARD_ONLY
0073 #  include <boost/mpi/python/serialize.hpp>
0074 #  include <boost/mpi/python/skeleton_and_content.hpp>
0075 #else
0076 #  undef BOOST_MPI_PYTHON_FORWARD_ONLY
0077 #endif
0078
0079 #endif // BOOST_MPI_PYTHON_HPP