ImmuTable

This is a native Lua library that allows the creation of immutable tables.

Build

This code has been tested with Lua 5.1.5, Lua 5.2.3, Lua 5.3.5, and LuaJIT 2.0.5. To build, simply make or for LuaJIT: make LUA=luajit (you can also optionally specify LUA_INC=<path to the directory containing lua.h and lauxlib.h> or LUA_BIN=<path to the directory containing the lua binary>).

Usage

Here's a simple implementation of a 2-d vector using immutable tables:

immutable = require "immutable"
Vec = immutable({"x","y"}, {
    name='Vector',
    len2=function(self)
        return self.x*self.x + self.y*self.y
    end,
    class_variable = "classvar",
    __add=function(self, other)
        local cls = getmetatable(self)
        return cls(self.x+other.x, self.y+other.y)
    end,
})
v = Vec(2, 3)
assert(v.x == 2 and v.y == 3)
also_v = Vec(2, 3)
assert(v == also_v)
t = {[v]='yep'}
assert(t[also_v] == 'yep')
assert(v + Vec(0,1) == Vec(2,4))
assert(#v == 2)
assert(v:len2() == 13)
assert(v.class_variable == "classvar")
assert(tostring(v) == 'Vector(x=2, y=3)')
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))
end
NotVec = immutable({"x","y"})
assert(NotVec(1,2) ~= Vec(1,2))

Singleton recipe

Singletons are pretty straightforward:

Singleton = immutable()
assert(Singleton() == Singleton())

Or if you want methods/class variables:

DogSingleton = immutable(0, {name="DogSingleton", bark=function(self) print("woof") end})
DogSingleton():bark()

Tuples

If no field names are passed in, immutable() defaults to creating immutable tables that behave like Python's tuples:

local Tuple = immutable()
local t0 = Tuple()
local t1 = Tuple(1,2)
local t2 = Tuple(1,2,3,4,5)
assert(t0 == Tuple())
assert(({[t1]='yep'})[Tuple(1,2)])
assert(tostring(Tuple(1,2)) == "(1, 2)")

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.

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!

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:

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