policies

stack modification right before lua call returns

sol::policies is an advanced, low-level modification feature allowing you to take advantage of sol2's abstractions before applying your own stack-based modifications at the last moment. They cover the same functionality as luabind's "return reference to" and "dependency"_ types. A few pre-rolled policies are defined for your use:

+------------------------------------+----------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | policy | usage | modification | +------------------------------------+----------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | sol::returns_self | sol::policies( some_function, sol::returns_self() ) | - takes the argument at stack index 1 (self in member function calls and lambdas that take a specific userdata first) and makes that to be the return value | | | | - rather than creating a new userdata that references the same C++ memory, it copies the userdata, similar to writing obj2 = obj1 just increases the reference count | | | | - saves memory space on top of keeping original memory alive | +------------------------------------+----------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | sol::returns_self_with<int...> | sol::policies( some_function, sol::returns_self_with<2, 3>() ) | - same as above, with the caveat that the self is returned while also putting dependencies into the self | | | | - can keep external dependencies alive | +------------------------------------+----------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | sol::self_dependency | sol::policies( some_function, sol::self_dependency() ); | - this makes the value returned by the bindable take a dependency on the self argument | | | | - useful for returning a reference to a member variable and keeping the parent class of that member variable alive | +------------------------------------+----------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | sol::stack_dependencies | sol::policies( some_function, sol::stack_dependencies( target_index, 2, 1, ... ) ); | - whatever is at target_index on the stack is given a special "keep alive" table with the elements on the stack specified by the integer indices after target_index | | | | - allows you to keep arguments and other things alive for the duration of the existence of the class | +------------------------------------+----------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | custom | sol::policies( some_function, [](lua_State* L, int current_stack_return_count) -> int { ... } )| - whatever you want, so long as it has the form int (lua_State*, int ) | | | | - works with callables (such as lambdas), so long as it has the correct form | | | | - expected to return the number of things on the stack to return to Lua | +------------------------------------+----------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | - "some_function" can be any callable function, member variable, or similar | | - dependency additions only work on userdata | | | | - works with table::set( ... ), table::set_function( ... );, and on all usertype bindings | +-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+

You can specify multiple policies on the same sol::policies call, and can also specify custom policies as long as the signature is correct.

.. _luabind's "return reference to" and "dependency": http://www.rasterbar.com/products/luabind/docs.html#dependency