ceph/src/boost/libs/python/include/boost/python/converter/rvalue_from_python_data.hpp

   1 // Copyright David Abrahams 2002.
   2 // Distributed under the Boost Software License, Version 1.0. (See
   3 // accompanying file LICENSE_1_0.txt or copy at
   4 // http://www.boost.org/LICENSE_1_0.txt)
   5 #ifndef FROM_PYTHON_AUX_DATA_DWA2002128_HPP
   6 # define FROM_PYTHON_AUX_DATA_DWA2002128_HPP
   7
   8 # include <boost/python/converter/constructor_function.hpp>
   9 # include <boost/python/detail/referent_storage.hpp>
  10 # include <boost/python/detail/destroy.hpp>
  11 # include <boost/static_assert.hpp>
  12 # include <boost/type_traits/add_reference.hpp>
  13 # include <boost/type_traits/add_cv.hpp>
  14 # include <cstddef>
  15
  16 // Data management for potential rvalue conversions from Python to C++
  17 // types. When a client requests a conversion to T* or T&, we
  18 // generally require that an object of type T exists in the source
  19 // Python object, and the code here does not apply**. This implements
  20 // conversions which may create new temporaries of type T. The classic
  21 // example is a conversion which converts a Python tuple to a
  22 // std::vector. Since no std::vector lvalue exists in the Python
  23 // object -- it must be created "on-the-fly" by the converter, and
  24 // which must manage the lifetime of the created object.
  25 //
  26 // Note that the client is not precluded from using a registered
  27 // lvalue conversion to T in this case. In other words, we will
  28 // happily accept a Python object which /does/ contain a std::vector
  29 // lvalue, provided an appropriate converter is registered. So, while
  30 // this is an rvalue conversion from the client's point-of-view, the
  31 // converter registry may serve up lvalue or rvalue conversions for
  32 // the target type.
  33 //
  34 // ** C++ argument from_python conversions to T const& are an
  35 // exception to the rule for references: since in C++, const
  36 // references can bind to temporary rvalues, we allow rvalue
  37 // converters to be chosen when the target type is T const& for some
  38 // T.
  39 namespace boost { namespace python { namespace converter {
  40
  41 // Conversions begin by filling in and returning a copy of this
  42 // structure. The process looks up a converter in the rvalue converter
  43 // registry for the target type. It calls the convertible() function
  44 // of each registered converter, passing the source PyObject* as an
  45 // argument, until a non-null result is returned. This result goes in
  46 // the convertible field, and the converter's construct() function is
  47 // stored in the construct field.
  48 //
  49 // If no appropriate converter is found, conversion fails and the
  50 // convertible field is null. When used in argument conversion for
  51 // wrapped C++ functions, it causes overload resolution to reject the
  52 // current function but not to fail completely. If an exception is
  53 // thrown, overload resolution stops and the exception propagates back
  54 // through the caller.
  55 //
  56 // If an lvalue converter is matched, its convertible() function is
  57 // expected to return a pointer to the stored T object; its
  58 // construct() function will be NULL. The convertible() function of
  59 // rvalue converters may return any non-singular pointer; the actual
  60 // target object will only be available once the converter's
  61 // construct() function is called.
  62 struct rvalue_from_python_stage1_data
  63 {
  64     void* convertible;
  65     constructor_function construct;
  66 };
  67
  68 // Augments rvalue_from_python_stage1_data by adding storage for
  69 // constructing an object of remove_reference<T>::type. The
  70 // construct() function of rvalue converters (stored in m_construct
  71 // above) will cast the rvalue_from_python_stage1_data to an
  72 // appropriate instantiation of this template in order to access that
  73 // storage.
  74 template <class T>
  75 struct rvalue_from_python_storage
  76 {
  77     rvalue_from_python_stage1_data stage1;
  78
  79     // Storage for the result, in case an rvalue must be constructed
  80     typename python::detail::referent_storage<
  81         typename add_reference<T>::type
  82     >::type storage;
  83 };
  84
  85 // Augments rvalue_from_python_storage<T> with a destructor. If
  86 // stage1.convertible == storage.bytes, it indicates that an object of
  87 // remove_reference<T>::type has been constructed in storage and
  88 // should will be destroyed in ~rvalue_from_python_data(). It is
  89 // crucial that successful rvalue conversions establish this equality
  90 // and that unsuccessful ones do not.
  91 template <class T>
  92 struct rvalue_from_python_data : rvalue_from_python_storage<T>
  93 {
  94 # if (!defined(__MWERKS__) || __MWERKS__ >= 0x3000) \
  95         && (!defined(__EDG_VERSION__) || __EDG_VERSION__ >= 245) \
  96         && (!defined(__DECCXX_VER) || __DECCXX_VER > 60590014) \
  97         && !defined(BOOST_PYTHON_SYNOPSIS) /* Synopsis' OpenCXX has trouble parsing this */
  98     // This must always be a POD struct with m_data its first member.
  99     BOOST_STATIC_ASSERT(BOOST_PYTHON_OFFSETOF(rvalue_from_python_storage<T>,stage1) == 0);
 100 # endif
 101
 102     // The usual constructor
 103     rvalue_from_python_data(rvalue_from_python_stage1_data const&);
 104
 105     // This constructor just sets m_convertible -- used by
 106     // implicitly_convertible<> to perform the final step of the
 107     // conversion, where the construct() function is already known.
 108     rvalue_from_python_data(void* convertible);
 109
 110     // Destroys any object constructed in the storage.
 111     ~rvalue_from_python_data();
 112  private:
 113     typedef typename add_reference<typename add_cv<T>::type>::type ref_type;
 114 };
 115
 116 //
 117 // Implementataions
 118 //
 119 template <class T>
 120 inline rvalue_from_python_data<T>::rvalue_from_python_data(rvalue_from_python_stage1_data const& _stage1)
 121 {
 122     this->stage1 = _stage1;
 123 }
 124
 125 template <class T>
 126 inline rvalue_from_python_data<T>::rvalue_from_python_data(void* convertible)
 127 {
 128     this->stage1.convertible = convertible;
 129 }
 130
 131 template <class T>
 132 inline rvalue_from_python_data<T>::~rvalue_from_python_data()
 133 {
 134     if (this->stage1.convertible == this->storage.bytes)
 135         python::detail::destroy_referent<ref_type>(this->storage.bytes);
 136 }
 137
 138 }}} // namespace boost::python::converter
 139
 140 #endif // FROM_PYTHON_AUX_DATA_DWA2002128_HPP