boost/mpi/python.hpp

   1 // Copyright (C) 2006 Douglas Gregor <doug.gregor -at- gmail.com>
   2
   3 // Use, modification and distribution is subject to the Boost Software
   4 // License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at
   5 // http://www.boost.org/LICENSE_1_0.txt)
   6
   7 //  Authors: Douglas Gregor
   8 #ifndef BOOST_MPI_PYTHON_HPP
   9 #define BOOST_MPI_PYTHON_HPP
  10
  11 #include <boost/python/object.hpp>
  12
  13 /** @file python.hpp
  14  *
  15  *  This header interacts with the Python bindings for Boost.MPI. The
  16  *  routines in this header can be used to register user-defined and
  17  *  library-defined data types with Boost.MPI for efficient
  18  *  (de-)serialization and separate transmission of skeletons and
  19  *  content.
  20  *
  21  */
  22
  23 namespace boost { namespace mpi { namespace python {
  24
  25 /**
  26  * @brief Register the type T for direct serialization within Boost.MPI
  27  *
  28  * The @c register_serialized function registers a C++ type for direct
  29  * serialization within Boost.MPI. Direct serialization elides the use
  30  * of the Python @c pickle package when serializing Python objects
  31  * that represent C++ values. Direct serialization can be beneficial
  32  * both to improve serialization performance (Python pickling can be
  33  * very inefficient) and to permit serialization for Python-wrapped
  34  * C++ objects that do not support pickling.
  35  *
  36  *  @param value A sample value of the type @c T. This may be used
  37  *  to compute the Python type associated with the C++ type @c T.
  38  *
  39  *  @param type The Python type associated with the C++ type @c
  40  *  T. If not provided, it will be computed from the same value @p
  41  *  value.
  42  */
  43 template<typename T>
  44 void
  45 register_serialized(const T& value = T(), PyTypeObject* type = 0);
  46
  47 /**
  48  * @brief Registers a type for use with the skeleton/content mechanism
  49  * in Python.
  50  *
  51  * The skeleton/content mechanism can only be used from Python with
  52  * C++ types that have previously been registered via a call to this
  53  * function. Both the sender and the transmitter must register the
  54  * type. It is permitted to call this function multiple times for the
  55  * same type @c T, but only one call per process per type is
  56  * required. The type @c T must be Serializable.
  57  *
  58  *  @param value A sample object of type T that will be used to
  59  *  determine the Python type associated with T, if @p type is not
  60  *  specified.
  61  *
  62  *  @param type The Python type associated with the C++ type @c
  63  *  T. If not provided, it will be computed from the same value @p
  64  *  value.
  65  */
  66 template<typename T>
  67 void
  68 register_skeleton_and_content(const T& value = T(), PyTypeObject* type = 0);
  69
  70 } } } // end namespace boost::mpi::python
  71
  72 #ifndef BOOST_MPI_PYTHON_FORWARD_ONLY
  73 #  include <boost/mpi/python/serialize.hpp>
  74 #  include <boost/mpi/python/skeleton_and_content.hpp>
  75 #else
  76 #  undef BOOST_MPI_PYTHON_FORWARD_ONLY
  77 #endif
  78
  79 #endif // BOOST_MPI_PYTHON_HPP