mcell/libs/pybind11/docs/advanced/cast/functional.rst

Functional
##########

The following features must be enabled by including :file:`pybind11/functional.h`.


Callbacks and passing anonymous functions
=========================================

The C++11 standard brought lambda functions and the generic polymorphic
function wrapper ``std::function<>`` to the C++ programming language, which
enable powerful new ways of working with functions. Lambda functions come in
two flavors: stateless lambda function resemble classic function pointers that
link to an anonymous piece of code, while stateful lambda functions
additionally depend on captured variables that are stored in an anonymous
*lambda closure object*.

Here is a simple example of a C++ function that takes an arbitrary function
(stateful or stateless) with signature ``int -> int`` as an argument and runs
it with the value 10.

.. code-block:: cpp

    int func_arg(const std::function<int(int)> &f) {
        return f(10);
    }

The example below is more involved: it takes a function of signature ``int -> int``
and returns another function of the same kind. The return value is a stateful
lambda function, which stores the value ``f`` in the capture object and adds 1 to
its return value upon execution.

.. code-block:: cpp

    std::function<int(int)> func_ret(const std::function<int(int)> &f) {
        return [f](int i) {
            return f(i) + 1;
        };
    }

This example demonstrates using python named parameters in C++ callbacks which
requires using ``py::cpp_function`` as a wrapper. Usage is similar to defining
methods of classes:

.. code-block:: cpp

    py::cpp_function func_cpp() {
        return py::cpp_function([](int i) { return i+1; },
           py::arg("number"));
    }

After including the extra header file :file:`pybind11/functional.h`, it is almost
trivial to generate binding code for all of these functions.

.. code-block:: cpp

    #include <pybind11/functional.h>

    PYBIND11_MODULE(example, m) {
        m.def("func_arg", &func_arg);
        m.def("func_ret", &func_ret);
        m.def("func_cpp", &func_cpp);
    }

The following interactive session shows how to call them from Python.

.. code-block:: pycon

    $ python
    >>> import example
    >>> def square(i):
    ...     return i * i
    ...
    >>> example.func_arg(square)
    100L
    >>> square_plus_1 = example.func_ret(square)
    >>> square_plus_1(4)
    17L
    >>> plus_1 = func_cpp()
    >>> plus_1(number=43)
    44L

.. warning::

    Keep in mind that passing a function from C++ to Python (or vice versa)
    will instantiate a piece of wrapper code that translates function
    invocations between the two languages. Naturally, this translation
    increases the computational cost of each function call somewhat. A
    problematic situation can arise when a function is copied back and forth
    between Python and C++ many times in a row, in which case the underlying
    wrappers will accumulate correspondingly. The resulting long sequence of
    C++ -> Python -> C++ -> ... roundtrips can significantly decrease
    performance.

    There is one exception: pybind11 detects case where a stateless function
    (i.e. a function pointer or a lambda function without captured variables)
    is passed as an argument to another C++ function exposed in Python. In this
    case, there is no overhead. Pybind11 will extract the underlying C++
    function pointer from the wrapped function to sidestep a potential C++ ->
    Python -> C++ roundtrip. This is demonstrated in :file:`tests/test_callbacks.cpp`.

.. note::

    This functionality is very useful when generating bindings for callbacks in
    C++ libraries (e.g. GUI libraries, asynchronous networking libraries, etc.).

    The file :file:`tests/test_callbacks.cpp` contains a complete example
    that demonstrates how to work with callbacks and anonymous functions in
    more detail.