getting performance
===================
*things to make sol as fast as possible*


As shown by the :doc:`benchmarks<benchmarks>`, sol is very performant with its abstractions. However, in the case where you need every last drop of performance from sol, a number of tips and API usage tricks will be documented here. PLEASE benchmark / profile your code before you start invoking these, as some of them trade in readability / clarity for performance.

* If you have a bound function call / bound member function that you are going to call in a very tight, performance-heavy loop, considering using :doc:`sol::c_call<api/c_call>`
* Be wary of passing by value / reference, and what it means by reading :ref:`this note<function-argument-handling>`.
* It is currently undocumented that usertypes will "inherit" member function / member variables from bound classes, mostly because the semantics are unclear and it is not the most performant (although it is flexible: you can register base classes after / whenever you want in relation to the derived class, provided that derived class has its bases listed). Specifying all member functions / member variables for the usertype constructor / ``new_usertype`` function call and not relying on base lookup will boost performance of member lookup
* Use the :doc:`sol::stack_{}<api/stack_reference>` versions of functions in order to achieve maximum performance benefits when doing things like calling a function from Lua and knowing that certain arguments of certain Lua types will be on the stack. This can save you a very small fraction of performance to not copy to the register (but is also more dangerous and usually not terribly worth it).
* Specifying base classes can make getting the usertype out of sol a bit slower since we have to check and cast; if you know the exact type wherever you're retrieving it, considering not specifying the bases, retrieving the exact type from sol, and then casting to a base type yourself
* Member variables can sometimes cost an extra lookup to occur within the Lua system (as mentioned :doc:`bottom of the usertype page<api/usertype>`); until we find out a safe way around this, member variables will always incur that extra lookup cost


Working with things that are already on the stack can also boost performance. Last time regular, call overhead was measured, it was around 5-11 nanoseconds for a single C++ call on a recent (2015) machine. The range is for how slim you make the call, what kind of arguments, et cetera.

If you find some form of the performance unacceptable to you, also feel free to open an issue at the github.