C++ Boost

Boost.Python

CallPolicies Concept
Introduction
CallPolicies Composition
Concept Requirements
CallPolicies Concept

Introduction

Models of the CallPolicies concept are used to specialize the behavior of Python callable objects generated by Boost.Python to wrapped C++ objects like function and member function pointers, providing three behaviors:

  1. precall - Python argument tuple management before the wrapped object is invoked
  2. result_converter - C++ return value handling
  3. postcall - Python argument tuple and result management after the wrapped object is invoked
  4. extract_return_type - metafunction for extracting the return type from a given signature type sequence

CallPolicies Composition

In order to allow the use of multiple models of CallPolicies in the same callable object, Boost.Python's CallPolicies class templates provide a chaining interface which allows them to be recursively composed. This interface takes the form of an optional template parameter, Base which defaults to default_call_policies. By convention, the precall function of the Base is invoked after the precall function supplied by the outer template, and the postcall function of the Base is invoked before the postcall function of the outer template. If a result_converter is supplied by the outer template, it replaces any result_converter supplied by the Base. For an example, see return_internal_reference.

Concept Requirements

CallPolicies Concept

In the table below, x denotes an object whose type P is a model of CallPolicies, a denotes a PyObject* pointing to a Python argument tuple object, and r denotes a PyObject* referring to a "preliminary" result object.

Expression Type Result/Semantics
x.precall(a) convertible to bool returns false and PyErr_Occurred() != 0 upon failure, true otherwise.
P::result_converter A model of ResultConverterGenerator. An MPL unary Metafunction Class used produce the "preliminary" result object.
x.postcall(a, r) convertible to PyObject* 0 0 and PyErr_Occurred() != 0 upon failure. Must "conserve references" even in the event of an exception. In other words, if r is not returned, its reference count must be decremented; if another existing object is returned, its reference count must be incremented.
P::extract_return_type A model of Metafunction. An MPL unary Metafunction used extract the return type from a given signature. By default it is derived from mpl::front.
Models of CallPolicies are required to be CopyConstructible.

Revised 13 November, 2002

© Copyright Dave Abrahams 2002.

Permission to copy, use, modify, sell and distribute this software is granted provided this copyright notice appears in all copies. This software is provided "as is" without express or implied warranty, and with no claim as to its suitability for any purpose.