Boost.Python - CallPolicies Concept

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