[ci-skip] Readme updated, benchmarks are now live

README.md

@@ -1,4 +1,4 @@
-## Sol 2.9
+## Sol 2.10
 
 [![Build Status](https://travis-ci.org/ThePhD/sol2.svg?branch=develop)](https://travis-ci.org/ThePhD/sol2)
 [![Documentation Status](https://readthedocs.org/projects/sol2/badge/?version=latest)](http://sol2.readthedocs.org/en/latest/?badge=latest)
@@ -46,19 +46,20 @@ More examples are given in the examples directory.
 
 ## Creating a single header
 
-Check the releases tab on github for a provided single header file for maximum ease of use. A script called `single.py` is provided in the repository if there's some bleeding edge change that hasn't been published on the releases page. You can run this script to create a single file version of the library so you can only include that part of it. Check `single.py --help` for more info.
+You can grab a single header out of the library [here](https://github.com/ThePhD/sol2/tree/develop/single/sol). For stable version, check the releases tab on github for a provided single header file for maximum ease of use. A script called `single.py` is provided in the repository if there's some bleeding edge change that hasn't been published on the releases page. You can run this script to create a single file version of the library so you can only include that part of it. Check `single.py --help` for more info.
 
 ## Features
 
-- [Fastest in the land](http://satoren.github.io/lua_binding_benchmark/) (see: sol2 graph and table entries).
+- [Fastest in the land](http://sol2.readthedocs.io/en/latest/benchmarks.html) (see: sol2 graph and table entries).
 - Supports retrieval and setting of multiple types including `std::string` and `std::map/unordered_map`.
 - Lambda, function, and member function bindings are supported.
 - Intermediate type for checking if a variable exists.
 - Simple API that completely abstracts away the C stack API, including `protected_function` with the ability to use an error-handling function.
 - `operator[]`-style manipulation of tables
-- C++ type representations in lua userdata as `usertype`s with guaranteed cleanup
+- C++ type representations in lua userdata as `usertype`s with guaranteed cleanup.
+- Customization points to allow your C++ objects to be pushed and retrieved from Lua as multiple consecutive objects, or anything else you desire!
 - Overloaded function calls: `my_function(1); my_function("Hello")` in the same lua script route to different function calls based on parameters
-- Support for tables, nested tables, table iteration with `table.for_each`.
+- Support for tables, nested tables, table iteration with `table.for_each` / `begin()` and `end()` iterators.
 
 ## Supported Compilers
 
@@ -69,14 +70,6 @@ officially supported and CI-tested compilers are:
 - Clang 3.5+
 - Visual Studio 2015 Community (Visual C++ 14.0)+
 
-## Caveats
-
-Due to how this library is used compared to the C API, the Lua Stack is completely abstracted away. Not only that, but all
-Lua errors are thrown as exceptions instead: if you don't want to deal with errors thrown by at_panic, you can set your own panic function or use the `protected_function` API. This allows you to handle the errors gracefully without being forced to exit. If you don't want to deal with exceptions, then define `SOL_NO_EXCEPTIONS`. If you also don't like RTTI, you can also define `SOL_NO_RTTI` as well. These macros are automatically defined if the code detects certain compiler-specific macros being turned on or off based on flags like `-fno-rtti` and `-fno-exceptions`
-
-It should be noted that the library itself depends on `lua.hpp` to be found by your compiler. It uses angle brackets, e.g.
-`#include <lua.hpp>`.
-
 ## License
 
 Sol is distributed with an MIT License. You can see LICENSE.txt for more info.

docs/source/benchmarks.rst

@@ -9,10 +9,79 @@ These are some informal and formal benchmarks done by both the developers of sol
 * `lua_binding_benchmarks`_ by satoren (developer of `kaguya`_) (`Sol`_ is the "sol2" entry)
 * `lua-bench`_ by ThePhD (developer of `Sol`_)
 
-As of the writing of this documentation (March 11th, 2016), :doc:`Sol<index>` (Sol2) seems to take the cake in most categories for speed!
+As of the writing of this documentation (July 29th, 2016), :doc:`Sol<index>` (Sol2) seems to take the cake in most categories for speed! Below are some graphs from `lua-bench`_. You can read the benchmarking code there if you think something was done wrong, and submit a pull requests or comment on something to make sure that ThePhD is being honest about his work. All categories are the performance of things described at the top of the :doc:`feature table<features>`.
+
+Note that Sol here makes use of its more performant variants (see :doc:`c_call<doc/c-call>`), and ThePhD also does his best to make use of the most performant variants for other frameworks by disabling type checks where possible as well (Thanks to Liam Devine of OOLua for explaining how to turn off type checks in OOLua).
+
+Lower is better, results are sorted from top to bottom by best to worst:
+
+.. image:: https://raw.githubusercontent.com/ThePhD/lua-bench/master/lua%20-%20results/lua%20bench%20graph%20-%20member%20function%20calls.png
+	:target: https://raw.githubusercontent.com/ThePhD/lua-bench/master/lua%20-%20results/lua%20bench%20graph%20-%20member%20function%20calls.png
+	:alt: bind several member functions to an object and call them in Lua code
+
+.. image:: https://raw.githubusercontent.com/ThePhD/lua-bench/master/lua%20-%20results/lua%20bench%20graph%20-%20member%20variable.png
+	:target: https://raw.githubusercontent.com/ThePhD/lua-bench/master/lua%20-%20results/lua%20bench%20graph%20-%20member%20variable.png
+	:alt: bind a variable to an object and call it in Lua code
+
+.. image:: https://raw.githubusercontent.com/ThePhD/lua-bench/master/lua%20-%20results/lua%20bench%20graph%20-%20c%20function%20through%20lua.png
+	:target: https://raw.githubusercontent.com/ThePhD/lua-bench/master/lua%20-%20results/lua%20bench%20graph%20-%20c%20function%20through%20lua.png
+	:alt: retrieve a C function bound in Lua and call it from C++
+
+.. image:: https://raw.githubusercontent.com/ThePhD/lua-bench/master/lua%20-%20results/lua%20bench%20graph%20-%20stateful%20c%20function.png
+	:target: https://raw.githubusercontent.com/ThePhD/lua-bench/master/lua%20-%20results/lua%20bench%20graph%20-%20stateful%20c%20function.png
+	:alt: bind a stateful C function (e.g., a mutable lambda), retrieve it, and call it from C++
+
+.. image:: https://raw.githubusercontent.com/ThePhD/lua-bench/master/lua%20-%20results/lua%20bench%20graph%20-%20c%20function.png
+	:target: https://raw.githubusercontent.com/ThePhD/lua-bench/master/lua%20-%20results/lua%20bench%20graph%20-%20c%20function.png
+	:alt: call a C function through Lua code
+
+.. image:: https://raw.githubusercontent.com/ThePhD/lua-bench/master/lua%20-%20results/lua%20bench%20graph%20-%20lua%20function.png
+	:target: https://raw.githubusercontent.com/ThePhD/lua-bench/master/lua%20-%20results/lua%20bench%20graph%20-%20lua%20function.png
+	:alt: retrieve a plain Lua function and call it from C++
+
+.. image:: https://raw.githubusercontent.com/ThePhD/lua-bench/master/lua%20-%20results/lua%20bench%20graph%20-%20multi%20return.png
+	:target: https://raw.githubusercontent.com/ThePhD/lua-bench/master/lua%20-%20results/lua%20bench%20graph%20-%20multi%20return.png
+	:alt: return mutliple objects from C++ using std::tuple or through a library-defined mechanism
+
+.. image:: https://raw.githubusercontent.com/ThePhD/lua-bench/master/lua%20-%20results/lua%20bench%20graph%20-%20global%20get.png
+	:target: https://raw.githubusercontent.com/ThePhD/lua-bench/master/lua%20-%20results/lua%20bench%20graph%20-%20global%20get.png
+	:alt: retrieve a value from the global table
+
+.. image:: https://raw.githubusercontent.com/ThePhD/lua-bench/master/lua%20-%20results/lua%20bench%20graph%20-%20global%20set.png
+	:target: https://raw.githubusercontent.com/ThePhD/lua-bench/master/lua%20-%20results/lua%20bench%20graph%20-%20global%20set.png
+	:alt: set a value into the global table
+
+.. image:: https://raw.githubusercontent.com/ThePhD/lua-bench/master/lua%20-%20results/lua%20bench%20graph%20-%20table%20chained%20get.png
+	:target: https://raw.githubusercontent.com/ThePhD/lua-bench/master/lua%20-%20results/lua%20bench%20graph%20-%20table%20chained%20get.png
+	:alt: measures the cost of doing consecutive lookups into a table that exists from C++; some libraries fail here because they do not do lazy evaluation or chaining properly
+
+.. image:: https://raw.githubusercontent.com/ThePhD/lua-bench/master/lua%20-%20results/lua%20bench%20graph%20-%20table%20get.png
+	:target: https://raw.githubusercontent.com/ThePhD/lua-bench/master/lua%20-%20results/lua%20bench%20graph%20-%20table%20get.png
+	:alt: measures the cost of retrieving a value from a table in C++; this nests 1 level so as to not be equivalent to any measured global table get optimzations
+
+.. image:: https://raw.githubusercontent.com/ThePhD/lua-bench/master/lua%20-%20results/lua%20bench%20graph%20-%20table%20chained%20set.png
+	:target: https://raw.githubusercontent.com/ThePhD/lua-bench/master/lua%20-%20results/lua%20bench%20graph%20-%20table%20chained%20set.png
+	:alt: measures the cost of doing consecutive lookups into a table that exists from C++ and setting the final value; some libraries fail here because they do not do lazy evaluation or chaining properly
+
+.. image:: https://raw.githubusercontent.com/ThePhD/lua-bench/master/lua%20-%20results/lua%20bench%20graph%20-%20table%20set.png
+	:target: https://raw.githubusercontent.com/ThePhD/lua-bench/master/lua%20-%20results/lua%20bench%20graph%20-%20table%20set.png
+	:alt: measures the cost of setting a value into a table in C++; this nests 1 level so as to not be equivalent to any measured global table set optimzations
+
+.. image:: https://raw.githubusercontent.com/ThePhD/lua-bench/master/lua%20-%20results/lua%20bench%20graph%20-%20return%20userdata.png
+	:target: https://raw.githubusercontent.com/ThePhD/lua-bench/master/lua%20-%20results/lua%20bench%20graph%20-%20return%20userdata.png
+	:alt: bind a C function which returns a custom class by-value and call it through Lua code
+
+.. image:: https://raw.githubusercontent.com/ThePhD/lua-bench/master/lua%20-%20results/lua%20bench%20graph%20-%20get%20optional.png
+	:target: https://raw.githubusercontent.com/ThePhD/lua-bench/master/lua%20-%20results/lua%20bench%20graph%20-%20get%20optional.png
+	:alt: retrieve an item from a table that does not exist in Lua and check for its existence (testing the cost of the failure case)
+
+.. image:: https://raw.githubusercontent.com/ThePhD/lua-bench/master/lua%20-%20results/lua%20bench%20graph%20-%20base%20from%20derived.png
+	:target: https://raw.githubusercontent.com/ThePhD/lua-bench/master/lua%20-%20results/lua%20bench%20graph%20-%20base%20from%20derived.png
+	:alt: retrieve base class pointer out of Lua without knowing exact derived at compile-time, and have it be correct for multiple-inheritance
+
 
 
 .. _lua-bench: https://github.com/ThePhD/lua-bench
 .. _lua_binding_benchmarks: http://satoren.github.io/lua_binding_benchmark/
 .. _kaguya: https://github.com/satoren/kaguya
-.. _Sol: https://github.com/ThePhD/sol2
+.. _Sol: https://github.com/ThePhD/sol2

docs/source/index.rst

@@ -7,8 +7,8 @@
 	:target: https://github.com/ThePhD/sol2
 	:alt: sol2 repository
 
-Sol 2.9
+Sol 2.10
-=======
+========
 a fast, simple C++ and Lua Binding
 ----------------------------------