functional.rst revision 12391
111986Sandreas.sandberg@arm.comFunctional 211986Sandreas.sandberg@arm.com########## 311986Sandreas.sandberg@arm.com 411986Sandreas.sandberg@arm.comThe following features must be enabled by including :file:`pybind11/functional.h`. 511986Sandreas.sandberg@arm.com 611986Sandreas.sandberg@arm.com 711986Sandreas.sandberg@arm.comCallbacks and passing anonymous functions 811986Sandreas.sandberg@arm.com========================================= 911986Sandreas.sandberg@arm.com 1011986Sandreas.sandberg@arm.comThe C++11 standard brought lambda functions and the generic polymorphic 1111986Sandreas.sandberg@arm.comfunction wrapper ``std::function<>`` to the C++ programming language, which 1211986Sandreas.sandberg@arm.comenable powerful new ways of working with functions. Lambda functions come in 1311986Sandreas.sandberg@arm.comtwo flavors: stateless lambda function resemble classic function pointers that 1411986Sandreas.sandberg@arm.comlink to an anonymous piece of code, while stateful lambda functions 1511986Sandreas.sandberg@arm.comadditionally depend on captured variables that are stored in an anonymous 1611986Sandreas.sandberg@arm.com*lambda closure object*. 1711986Sandreas.sandberg@arm.com 1811986Sandreas.sandberg@arm.comHere is a simple example of a C++ function that takes an arbitrary function 1911986Sandreas.sandberg@arm.com(stateful or stateless) with signature ``int -> int`` as an argument and runs 2011986Sandreas.sandberg@arm.comit with the value 10. 2111986Sandreas.sandberg@arm.com 2211986Sandreas.sandberg@arm.com.. code-block:: cpp 2311986Sandreas.sandberg@arm.com 2411986Sandreas.sandberg@arm.com int func_arg(const std::function<int(int)> &f) { 2511986Sandreas.sandberg@arm.com return f(10); 2611986Sandreas.sandberg@arm.com } 2711986Sandreas.sandberg@arm.com 2811986Sandreas.sandberg@arm.comThe example below is more involved: it takes a function of signature ``int -> int`` 2911986Sandreas.sandberg@arm.comand returns another function of the same kind. The return value is a stateful 3011986Sandreas.sandberg@arm.comlambda function, which stores the value ``f`` in the capture object and adds 1 to 3111986Sandreas.sandberg@arm.comits return value upon execution. 3211986Sandreas.sandberg@arm.com 3311986Sandreas.sandberg@arm.com.. code-block:: cpp 3411986Sandreas.sandberg@arm.com 3511986Sandreas.sandberg@arm.com std::function<int(int)> func_ret(const std::function<int(int)> &f) { 3611986Sandreas.sandberg@arm.com return [f](int i) { 3711986Sandreas.sandberg@arm.com return f(i) + 1; 3811986Sandreas.sandberg@arm.com }; 3911986Sandreas.sandberg@arm.com } 4011986Sandreas.sandberg@arm.com 4111986Sandreas.sandberg@arm.comThis example demonstrates using python named parameters in C++ callbacks which 4211986Sandreas.sandberg@arm.comrequires using ``py::cpp_function`` as a wrapper. Usage is similar to defining 4311986Sandreas.sandberg@arm.commethods of classes: 4411986Sandreas.sandberg@arm.com 4511986Sandreas.sandberg@arm.com.. code-block:: cpp 4611986Sandreas.sandberg@arm.com 4711986Sandreas.sandberg@arm.com py::cpp_function func_cpp() { 4811986Sandreas.sandberg@arm.com return py::cpp_function([](int i) { return i+1; }, 4911986Sandreas.sandberg@arm.com py::arg("number")); 5011986Sandreas.sandberg@arm.com } 5111986Sandreas.sandberg@arm.com 5211986Sandreas.sandberg@arm.comAfter including the extra header file :file:`pybind11/functional.h`, it is almost 5311986Sandreas.sandberg@arm.comtrivial to generate binding code for all of these functions. 5411986Sandreas.sandberg@arm.com 5511986Sandreas.sandberg@arm.com.. code-block:: cpp 5611986Sandreas.sandberg@arm.com 5711986Sandreas.sandberg@arm.com #include <pybind11/functional.h> 5811986Sandreas.sandberg@arm.com 5912391Sjason@lowepower.com PYBIND11_MODULE(example, m) { 6011986Sandreas.sandberg@arm.com m.def("func_arg", &func_arg); 6111986Sandreas.sandberg@arm.com m.def("func_ret", &func_ret); 6211986Sandreas.sandberg@arm.com m.def("func_cpp", &func_cpp); 6311986Sandreas.sandberg@arm.com } 6411986Sandreas.sandberg@arm.com 6511986Sandreas.sandberg@arm.comThe following interactive session shows how to call them from Python. 6611986Sandreas.sandberg@arm.com 6711986Sandreas.sandberg@arm.com.. code-block:: pycon 6811986Sandreas.sandberg@arm.com 6911986Sandreas.sandberg@arm.com $ python 7011986Sandreas.sandberg@arm.com >>> import example 7111986Sandreas.sandberg@arm.com >>> def square(i): 7211986Sandreas.sandberg@arm.com ... return i * i 7311986Sandreas.sandberg@arm.com ... 7411986Sandreas.sandberg@arm.com >>> example.func_arg(square) 7511986Sandreas.sandberg@arm.com 100L 7611986Sandreas.sandberg@arm.com >>> square_plus_1 = example.func_ret(square) 7711986Sandreas.sandberg@arm.com >>> square_plus_1(4) 7811986Sandreas.sandberg@arm.com 17L 7911986Sandreas.sandberg@arm.com >>> plus_1 = func_cpp() 8011986Sandreas.sandberg@arm.com >>> plus_1(number=43) 8111986Sandreas.sandberg@arm.com 44L 8211986Sandreas.sandberg@arm.com 8311986Sandreas.sandberg@arm.com.. warning:: 8411986Sandreas.sandberg@arm.com 8511986Sandreas.sandberg@arm.com Keep in mind that passing a function from C++ to Python (or vice versa) 8611986Sandreas.sandberg@arm.com will instantiate a piece of wrapper code that translates function 8711986Sandreas.sandberg@arm.com invocations between the two languages. Naturally, this translation 8811986Sandreas.sandberg@arm.com increases the computational cost of each function call somewhat. A 8911986Sandreas.sandberg@arm.com problematic situation can arise when a function is copied back and forth 9011986Sandreas.sandberg@arm.com between Python and C++ many times in a row, in which case the underlying 9111986Sandreas.sandberg@arm.com wrappers will accumulate correspondingly. The resulting long sequence of 9211986Sandreas.sandberg@arm.com C++ -> Python -> C++ -> ... roundtrips can significantly decrease 9311986Sandreas.sandberg@arm.com performance. 9411986Sandreas.sandberg@arm.com 9511986Sandreas.sandberg@arm.com There is one exception: pybind11 detects case where a stateless function 9611986Sandreas.sandberg@arm.com (i.e. a function pointer or a lambda function without captured variables) 9711986Sandreas.sandberg@arm.com is passed as an argument to another C++ function exposed in Python. In this 9811986Sandreas.sandberg@arm.com case, there is no overhead. Pybind11 will extract the underlying C++ 9911986Sandreas.sandberg@arm.com function pointer from the wrapped function to sidestep a potential C++ -> 10011986Sandreas.sandberg@arm.com Python -> C++ roundtrip. This is demonstrated in :file:`tests/test_callbacks.cpp`. 10111986Sandreas.sandberg@arm.com 10211986Sandreas.sandberg@arm.com.. note:: 10311986Sandreas.sandberg@arm.com 10411986Sandreas.sandberg@arm.com This functionality is very useful when generating bindings for callbacks in 10511986Sandreas.sandberg@arm.com C++ libraries (e.g. GUI libraries, asynchronous networking libraries, etc.). 10611986Sandreas.sandberg@arm.com 10711986Sandreas.sandberg@arm.com The file :file:`tests/test_callbacks.cpp` contains a complete example 10811986Sandreas.sandberg@arm.com that demonstrates how to work with callbacks and anonymous functions in 10911986Sandreas.sandberg@arm.com more detail. 110