avoid C++ -> Python -> C++ overheads when passing around function objects
diff --git a/docs/advanced.rst b/docs/advanced.rst
index 2a0e268..43f5200 100644
--- a/docs/advanced.rst
+++ b/docs/advanced.rst
@@ -185,21 +185,32 @@
>>> plus_1(number=43)
44L
-.. note::
-
- This functionality is very useful when generating bindings for callbacks in
- C++ libraries (e.g. a graphical user interface library).
-
- The file :file:`example/example5.cpp` contains a complete example that
- demonstrates how to work with callbacks and anonymous functions in more detail.
-
.. 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. Copying the same function back and
- forth between Python and C++ many times in a row will cause these wrappers
- to accumulate, which can decrease performance.
+ 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 Example 5.
+
+.. 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:`example/example5.cpp` contains a complete example that
+ demonstrates how to work with callbacks and anonymous functions in more detail.
Overriding virtual functions in Python
======================================