github.com/kaydxh/golang@v0.0.131/pkg/gocv/cgo/third_path/pybind11/docs/advanced/cast/functional.rst (about)

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