Bruce/lua-immutable
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Moved implementation doc into a different file.

Browse Source
This commit is contained in:
Bruce Hill 2018-03-16 15:49:29 -07:00
parent b77e4bdbe5
commit 5b486d4d69
2 changed files with 46 additions and 43 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

45
README.md
View File

@ -89,46 +89,5 @@ assert(Immutable{a=1,b=2,c=3} == Immutable{a=1,b=2,c=3})
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!
## 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
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[extract_hash(self)][self]
return data[key] or cls[key]
end,
...also: __len, __pairs, __ipairs, __tostring, from_table, is_instance...
}
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
cls.__instances = setmetatable({}, {__mode='v', __index=function(self, key)
local bucket = setmetatable({}, {__mode='k'})
self[key] = bucket
return bucket
end})
cls.__buckets = setmetatable({}, {__mode='k'})
return setmetatable(cls, {
__call=function(cls, ...)
local hash = calculate_hash(...)
local bucket = cls.__instances[hash]
for userdata, data in pairs(bucket) do
local match = true
for i=1,select('#',...) do
if data[i] ~= select(i, ...) then
match = false
break
end
end
if match then return userdata end
end
local userdata = setmetatable(new_userdata(hash), cls)
cls.__buckets[userdata] = bucket
bucket[userdata] = {...}
return userdata
end
})
end
```
You can read more about the implementation details in the [implementation documentation](./implementation.md).

44
implementation.md Normal file
View File

@ -0,0 +1,44 @@
# 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
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[extract_hash(self)][self]
return data[key] or cls[key]
end,
...also: __len, __pairs, __ipairs, __tostring, from_table, is_instance...
}
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
cls.__instances = setmetatable({}, {__mode='v', __index=function(self, key)
local bucket = setmetatable({}, {__mode='k'})
self[key] = bucket
return bucket
end})
cls.__buckets = setmetatable({}, {__mode='k'})
return setmetatable(cls, {
__call=function(cls, ...)
local hash = calculate_hash(...)
local bucket = cls.__instances[hash]
for userdata, data in pairs(bucket) do
local match = true
for i=1,select('#',...) do
if data[i] ~= select(i, ...) then
match = false
break
end
end
if match then return userdata end
end
local userdata = setmetatable(new_userdata(hash), cls)
cls.__buckets[userdata] = bucket
bucket[userdata] = {...}
return userdata
end
})
end
```