From 898f92d20a15de8b7cedabddd7a1a8dd3928c150 Mon Sep 17 00:00:00 2001 From: Bruce Hill Date: Mon, 4 Jun 2018 19:13:05 -0700 Subject: [PATCH] Updated rockspec and documentation. --- README.md | 52 ++++++++++++++++------------------ immutable-table-scm-1.rockspec | 2 +- implementation.md | 26 +++++++++++------ 3 files changed, 42 insertions(+), 38 deletions(-) diff --git a/README.md b/README.md index 5aed7be..8951da2 100644 --- a/README.md +++ b/README.md @@ -38,18 +38,31 @@ assert(Vec:is_instance(v) and not Vec:is_instance({x=2,y=3})) for k, v in pairs(v) do assert((k == 'x' and v == 2) or (k == 'y' and v == 3)) end -for i, v in ipairs(v) do - assert((i == 1 and v == 2) or (i == 2 and v == 3)) +DifferentVec = immutable({"x","y"}) +assert(DifferentVec(1,2) ~= Vec(1,2)) +``` + +Immutable tables work similarly to regular Lua tables, except that `nil` can be explicitly stored in an immutable table. The first arguments to the constructor are used for named fields, and all extra arguments are stored in numeric indices. +```lua +local Foo = immutable({"x","y"}) +local f = Foo(4,5,6,7) +assert(f.x == 4 and f.y == 5 and f[1] == 6 and f[2] == 7) +assert(#f == 2) +for k,v in pairs(f) do + print(k.."="..v) -- prints 1=6,2=7,x=4,y=5 +end +for i,v in ipairs(f) do + print(k.."="..v) -- prints 1=6,2=7 end -NotVec = immutable({"x","y"}) -assert(NotVec(1,2) ~= Vec(1,2)) ``` ## Singleton recipe Singletons are pretty straightforward: ```lua -Singleton = immutable({}) +Singleton = immutable() assert(Singleton() == Singleton()) +DifferentSingleton = immutable() +assert(Singleton() ~= DifferentSingleton()) ``` Or if you want methods/class variables: ```lua @@ -58,12 +71,13 @@ DogSingleton():bark() ``` ## Tuples -If no field names are passed in, `immutable()` defaults to creating immutable tables that behave like Python's tuples: +If the number of arguments is greater than the number of field names when constructing an immutable table, the extra values are stored in numeric indices. This can be used to create immutable tables that behave like Python's tuples, by using no field names: ```lua -local Tuple = immutable() +local Tuple = immutable({}) local t0 = Tuple() local t1 = Tuple(1,2) local t2 = Tuple(1,2,3,4,5) +assert(#t2 == 5) assert(t0 == Tuple()) assert(({[t1]='yep'})[Tuple(1,2)]) assert(tostring(Tuple(1,2)) == "(1, 2)") @@ -100,37 +114,19 @@ local f = Foo(1,nil) assert(f.x == 1 and f.y == "nil inst value" and f.classvar == 23 and f.asdf == 999) ``` -All of the normal Lua metamethods are also redundantly stored with a `raw` prefix (e.g. `__rawindex` for `__index`), in case you want to reference them in your implementation of the metamethod: +There is also a `__super` field which points to a table with all of the default implementations of the metamethods, which can be used when overriding: ```lua local -local BiggerOnTheInside = immutable(nil, { +local BiggerOnTheInside = immutable({}, { __len = function(self, key) local cls = getmetatable(self) - local len = cls.__rawlen(self) + local len = cls.__super.__len(self) return math.floor(len/2) end }) assert(#BiggerOnTheInside(1,2,3,4,5,6) == 3) ``` -## General purpose immutable table recipe -Using tuples, you can make a function that returns an immutable version of a table with arbitrary keys, though it is a little bit hacky. -```lua -local Tuple = immutable() -local immutable_classes = {} -Immutable = function(t) - local keys = {} - for k,_ in pairs(t) do keys[#keys+1] = k end - keys = Tuple(unpack(keys)) - if not immutable_classes[keys] then - immutable_classes[keys] = immutable(keys, {name="Immutable"}) - end - return immutable_classes[keys]:from_table(t) -end -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 local testing, immutable tables add a couple nanoseconds to table operations in the worst case scenario. In LuaJIT, there is a bigger performance discrepancy because regular tables are more heavily optimized in LuaJIT. Your mileage may vary, but I'd say that immutable tables will probably never be a performance bottleneck for your program, especially if you use them in place of code that already used a constructor function and metatables. In some cases, immutable tables may also help reduce your program's memory footprint (if your program has many duplicate objects in memory) and may even improve speed (e.g. if your program uses a lot of deep equality checks). Don't trust this paragraph though! If in doubt, profile your code! diff --git a/immutable-table-scm-1.rockspec b/immutable-table-scm-1.rockspec index 2f30f4d..104ba98 100644 --- a/immutable-table-scm-1.rockspec +++ b/immutable-table-scm-1.rockspec @@ -1,5 +1,5 @@ package = "immutable-table" -version = "scm-1" +version = "scm-2" source = { url = "git+https://spilt@bitbucket.org/spilt/lua-immutable.git" } diff --git a/implementation.md b/implementation.md index 57da736..cebcc33 100644 --- a/implementation.md +++ b/implementation.md @@ -1,16 +1,24 @@ # Implementation details Under the hood, immutable tables are implemented in C as a userdata (that stores a hash value and length) 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, the 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 +local metamethods = { + __index = function(self, key) + local cls = getmetatable(self) + local values = cls.__instances[cls.__hash(self)][self] + if cls.__indices[key] then + return values[cls.__indices[key]] + elseif type(key) == 'number' and 1 <= key and key <= #values - #cls.__fields then + return values[key - #cls.__fields] + else + return cls[key] + end + end, + ...also: __len, __pairs, __ipairs, __tostring, from_table, is_instance... +} function immutable(fields, class_fields) - local cls = { - __index = function(self, key) - local cls = getmetatable(self) - key = cls.__indices[key] or key - local data = cls.__instances[cls.__hash(self)][self] - return data[key] or cls[key] - end, - ...also: __len, __pairs, __ipairs, __tostring, from_table, is_instance... - } + local cls = {} + for k,v in pairs(metamethods) do cls[k] = v end + cls.__super = metamethods for k,v in pairs(class_fields) do cls[k] = v end cls.__fields, cls.__indices = fields, {} for i,f in ipairs(fields) do cls.__indices[f] = i end