Boost.Python Header

Contents

Introduction

Classes

Class template handle

Class handle synopsis

Class handle constructors and destructor

Class handle modifier functions

Class handle observer functions

Functions

borrowed

allow_null

---

Introduction

provides class template handle, a smart pointer for managing reference-counted Python objects.

Classes

Class template handle

handle is a smart pointer to a Python object type; it holds a pointer of type T*, where T is its template parameter. T must be either a type derived from PyObject or a POD type whose initial sizeof(PyObject) bytes are layout-compatible with PyObject. Use handle<> at the boundary between the Python/'C' API and high-level code; prefer object for a generalized interface to Python objects.

In this document, the term "upcast" refers to an operation which converts a pointer Y* to a base class pointer T* via static_cast if Y is derived from T, or via C-style cast (T*) if it is not. However, in the latter case the "upcast" is ill-formed if the initial sizeof(PyObject) bytes of Y are not layout-compatible with PyObject.

Class template handle synopsis

namespace boost { namespace python
{
  template 
  class handle
  {
      typedef unspecified-member-function-pointer bool_type;

   public: // types
      typedef T element_type;

   public: // member functions
      ~handle();

      template 
      explicit handle(detail::borrowed >* p);

      template 
      explicit handle(null_ok >* p);

      template 
      explicit handle(detail::borrowed* p);

      template 
      explicit handle(null_ok* p);

      template 
      explicit handle(Y* p);

      handle();

      handle& operator=(handle const& r);

      template
      handle& operator=(handle const & r); // never throws


      template 
      handle(handle const& r);

      handle(handle const& r);

      T* operator-> () const;
      T& operator* () const;
      T* get() const;
      void reset();
      T* release();

      operator bool_type() const; // never throws
   private:
      T* m_p;
  };
  
  template  struct null_ok;
  namespace detail { template  struct borrowed; }
}}

Class handle constructors and destructor

virtual ~handle();

Effects: Py_XDECREF(upcast(m_p))

template 
explicit handle(detail::borrowed >* p);

Effects: Py_XINCREF(upcast(p)); m_p = upcast(p);

template 
explicit handle(null_ok >* p);

Effects: Py_XINCREF(upcast(p)); m_p = upcast(p);

template 
explicit handle(detail::borrowed* p);

Effects: Py_XINCREF(upcast(p)); m_p = upcast(expect_non_null(p));

template 
explicit handle(null_ok* p);

Effects: m_p = upcast(p);

template 
explicit handle(Y* p);

Effects: m_p = upcast(expect_non_null(p));

handle();

Effects: m_p = 0;

template 
handle(handle const& r);
handle(handle const& r);

Effects: m_p = r.m_p; Py_XINCREF(upcast(m_p));

Class handle modifiers

handle& operator=(handle const& r);
template
handle& operator=(handle const & r); // never throws

Effects: Py_XINCREF(upcast(r.m_p)); Py_XDECREF( upcast(m_p)); m_p = r.m_p;

T* release();

Effects: T* x = m_p; m_p = 0;return x;

void reset();

Effects: *this = handle();

Class handle observers

T* operator-> () const;
T* get() const;

Returns: m_p;

T& operator* () const;

Returns: *m_p;

operator bool_type() const; // never throws

Returns: 0 if m_p == 0, a pointer convertible to true otherwise.

Functions

borrowed

template 
detail::borrowed* borrowed(T* p)
{
    return (detail::borrowed*)p;
}

allow_null

template 
null_ok* allow_null(T* p)
{
    return (null_ok*)p;
}

Revised 13 November, 2002

© Copyright Dave Abrahams 2002 .