policies
stack modification right before lua call returns
sol::policies
is an advanced, low-level modification feature allowing you to take advantage of sol3’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.