Updated docs.

This commit is contained in:
Bruce Hill 2018-02-12 02:31:08 -08:00
parent 04c20ab009
commit b4bc3065d5

View File

@ -88,6 +88,9 @@ assert(Immutable{x=1} == Immutable{x=1})
assert(Immutable{a=1,b=2,c=3} == Immutable{a=1,b=2,c=3})
```
## Performance
This library is pretty dang fast, but it's still slower than native Lua tables. Based on my benchmarks, in Lua 5.3.3, creating a new 2-member immutable tables takes about 2.83 nanoseconds (compared to 0.47 for a lua table), but creating a new 2-member immutable table that matches one already in memory takes about the same time as making a lua table (0.46 nanoseconds). Accessing members takes about 0.171 nanoseconds on the immutable table, compared to about 0.016 nanoseconds on a lua table. And accessing class members takes about 0.16 nanoseconds on an immutable table, compared to about 0.038 nanoseconds accessing the `__index` of a lua table's metatable. The numbers on LuaJIT are a bit hard to suss out because LuaJIT does a lot of optimizations on table access, but roughly speaking, immutable tables are faster when running on LuaJIT, but there is a greater discrepancy
## Implementation details
Under the hood, immutable tables are implemented in C as a userdata (that stores a hash value) with a metatable. That metatable has a weak-keyed mapping from hash -> userdata -> associated data. Immutable tables *are* garbage collected, so if you no longer have any references to the userdata, the userdata will get garbage collected, which will result in the entry being removed from the metatable's mapping. When new instances are created, a hash value is computed, and all the data in the associated hash bucket is scanned to look for duplicates. If a match is found, that existing instance is returned, otherwise a new one is created and added to the hash bucket. The following lua pseudocode approximates the C implementation's behavior:
```lua