ceph/src/boost/libs/python/doc/reference/to_python_indirect.qbk

   1 [section boost/python/to_python_indirect.hpp]
   2 [section Introduction]
   3  <boost/python/to_python_indirect.hpp> supplies a way to construct new Python objects that hold wrapped C++ class instances via a pointer or smart pointer.
   4  [endsect]
   5 [section Class `to_python_indirect`]
   6 Class template `to_python_indirect` converts objects of its first argument type to python as extension class instances, using the ownership policy provided by its 2nd argument.
   7 [table
   8 [[Parameter][Requirements][Description]]
   9  [[T][Either `U cv&` (where cv is any optional cv-qualification) or a [link concepts.dereferenceable Dereferenceable] type such that `*x` is convertible to `U const&`, where `U` is a class type. ][`A` type deferencing a C++ class exposed to Python using class template [link high_level_components.boost_python_class_hpp.class_template_class_t_bases_hel `class_`]. ]]
  10 [[MakeHolder][`h = MakeHolder::execute(p);` ][A class whose static `execute()` creates an `instance_holder`. ]]
  11  ]
  12 Instantiations of to_python_indirect are models of [link concepts.resultconverter `ResultConverter`].
  13 ``
  14 namespace boost { namespace python
  15 {
  16   template <class T, class MakeHolder>
  17   struct to_python_indirect
  18   {
  19      static bool convertible();
  20      PyObject* operator()(T ptr_or_reference) const;
  21    private:
  22      static PyTypeObject* type();
  23   };
  24 }}
  25 ``
  26 [endsect]
  27 [section Class `to_python_indirect` observers]
  28 ``PyObject* operator()(T x) const;``
  29 [variablelist
  30 [[Requires][`x` refers to an object (if it is a pointer type, it is non-null). `convertible() == true`.]]
  31 [[Effects][Creates an appropriately-typed Boost.Python extension class instance, uses MakeHolder to create an instance_holder from x, installs the instance_holder in the new extension class instance, and returns a pointer to it.]]
  32 ]
  33 [endsect]
  34 [section Class `to_python_indirect` statics]
  35 ``bool convertible()``
  36 [variablelist
  37 [[Effects][Returns true iff any module has registered a Python type corresponding to U. ]]
  38 ]
  39 [endsect]
  40 [endsect]
  41 [section Example]
  42 This example replicates the functionality of [link function_invocation_and_creation.models_of_resultconvertergenerat.boost_python_reference_existing_.class_reference_existing_object `reference_existing_object`], but without some of the compile-time error checking.
  43 ``
  44 struct make_reference_holder
  45 {
  46    typedef boost::python::objects::instance_holder* result_type;
  47    template <class T>
  48    static result_type execute(T* p)
  49    {
  50       return new boost::python::objects::pointer_holder<T*, T>(p);
  51    }
  52 };
  53
  54 struct reference_existing_object
  55 {
  56    // metafunction returning the ResultConverter
  57    template <class T>
  58    struct apply
  59    {
  60       typedef boost::python::to_python_indirect<T,make_reference_holder> type;
  61    };
  62 };
  63 ``
  64 [endsect]
  65 [endsect]