Boost.Python

CallPolicies Concept

Introduction
CallPolicies Composition
Concept Requirements

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:

precall - Python argument tuple management before the wrapped object is invoked
result_converter - C++ return value handling
postcall - Python argument tuple and result management after the wrapped object is invoked

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 unarymetafunction object 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.
Models of CallPolicies are required to be CopyConstructible.

Revised 19 May, 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.

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 unarymetafunction object 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.