functional.rst revision 11986:c12e4625ab56
1Functional 2########## 3 4The following features must be enabled by including :file:`pybind11/functional.h`. 5 6 7Callbacks and passing anonymous functions 8========================================= 9 10The C++11 standard brought lambda functions and the generic polymorphic 11function wrapper ``std::function<>`` to the C++ programming language, which 12enable powerful new ways of working with functions. Lambda functions come in 13two flavors: stateless lambda function resemble classic function pointers that 14link to an anonymous piece of code, while stateful lambda functions 15additionally depend on captured variables that are stored in an anonymous 16*lambda closure object*. 17 18Here is a simple example of a C++ function that takes an arbitrary function 19(stateful or stateless) with signature ``int -> int`` as an argument and runs 20it with the value 10. 21 22.. code-block:: cpp 23 24 int func_arg(const std::function<int(int)> &f) { 25 return f(10); 26 } 27 28The example below is more involved: it takes a function of signature ``int -> int`` 29and returns another function of the same kind. The return value is a stateful 30lambda function, which stores the value ``f`` in the capture object and adds 1 to 31its return value upon execution. 32 33.. code-block:: cpp 34 35 std::function<int(int)> func_ret(const std::function<int(int)> &f) { 36 return [f](int i) { 37 return f(i) + 1; 38 }; 39 } 40 41This example demonstrates using python named parameters in C++ callbacks which 42requires using ``py::cpp_function`` as a wrapper. Usage is similar to defining 43methods of classes: 44 45.. code-block:: cpp 46 47 py::cpp_function func_cpp() { 48 return py::cpp_function([](int i) { return i+1; }, 49 py::arg("number")); 50 } 51 52After including the extra header file :file:`pybind11/functional.h`, it is almost 53trivial to generate binding code for all of these functions. 54 55.. code-block:: cpp 56 57 #include <pybind11/functional.h> 58 59 PYBIND11_PLUGIN(example) { 60 py::module m("example", "pybind11 example plugin"); 61 62 m.def("func_arg", &func_arg); 63 m.def("func_ret", &func_ret); 64 m.def("func_cpp", &func_cpp); 65 66 return m.ptr(); 67 } 68 69The following interactive session shows how to call them from Python. 70 71.. code-block:: pycon 72 73 $ python 74 >>> import example 75 >>> def square(i): 76 ... return i * i 77 ... 78 >>> example.func_arg(square) 79 100L 80 >>> square_plus_1 = example.func_ret(square) 81 >>> square_plus_1(4) 82 17L 83 >>> plus_1 = func_cpp() 84 >>> plus_1(number=43) 85 44L 86 87.. warning:: 88 89 Keep in mind that passing a function from C++ to Python (or vice versa) 90 will instantiate a piece of wrapper code that translates function 91 invocations between the two languages. Naturally, this translation 92 increases the computational cost of each function call somewhat. A 93 problematic situation can arise when a function is copied back and forth 94 between Python and C++ many times in a row, in which case the underlying 95 wrappers will accumulate correspondingly. The resulting long sequence of 96 C++ -> Python -> C++ -> ... roundtrips can significantly decrease 97 performance. 98 99 There is one exception: pybind11 detects case where a stateless function 100 (i.e. a function pointer or a lambda function without captured variables) 101 is passed as an argument to another C++ function exposed in Python. In this 102 case, there is no overhead. Pybind11 will extract the underlying C++ 103 function pointer from the wrapped function to sidestep a potential C++ -> 104 Python -> C++ roundtrip. This is demonstrated in :file:`tests/test_callbacks.cpp`. 105 106.. note:: 107 108 This functionality is very useful when generating bindings for callbacks in 109 C++ libraries (e.g. GUI libraries, asynchronous networking libraries, etc.). 110 111 The file :file:`tests/test_callbacks.cpp` contains a complete example 112 that demonstrates how to work with callbacks and anonymous functions in 113 more detail. 114