Chapter 1. Concepts

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
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

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` 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`.