Boost C++ Libraries

...one of the most highly regarded and expertly designed C++ library projects in the world. Herb Sutter and Andrei Alexandrescu, C++ Coding Standards

Boost.Python - <boost/python/handle.hpp>

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 .