impotent/README.md

# Impotent

This is an attempt to create a Lua virtual machine capable of true multithreading. Once the nctref compiler matures enough, I intend to plug it into Impotent as a JIT.

Completed features:

1. Per-thread heap /w special heap for exited threads called the "dead heap"
2. Naive mark & sweep GC
3. Completely thread-safe, including lock-free implementation for tables

Impotent is still work-in-progress:

1. Integers are 32-bit only
2. No error handling, meaning any mistake will either crash the VM or make it silently fail
3. The only standard library is `print` and it doesn't work correctly
4. Tables cannot be resized
5. Most operators are still missing
6. The user API is completely different from that of PoC Lua
7. Being lock-free, tables are not split to "array" and "hash" parts
8. Userdata is not yet supported.

Impotent requires C11 and an architecture with 8-byte atomic operations, but otherwise it is completely cross-platform.

Performance-wise, it's surprisingly competitive with PoC Lua, considering how quickly it was made up to the point of writing this README (~2 weeks). By far the worst bottleneck is the GC, since it requires all threads and their heaps to synchronize.

Certain Lua idioms become impossible under Impotent. For example the idiom of appending to tables (`t[#t + 1] = x`) isn't atomic, therefore `table.insert` should be used instead.

## Additions

Obviously, threading. Any thread can access any value from any other thread, including for reading or writing. Operations such as getting or setting are lock-free in the best case scenario, but other operations (such as the `#` operator) must lock the table temporarily.

Besides this, I have no intent to greatly deviate from standard Lua, to keep source-level compatibility as best I can. The only addition to the standard library is the `threads` global, with two methods as of now.

### `threads.run`

Runs a function in a newly created thread. Does not block the caller.

	threads.run(function()
		-- Do something expensive
	end)


### `threads.parallel`

Runs a function in n parallel threads. Blocks the caller until all threads finish.

	threads.parallel(8, function()
		-- Do something parallelizable.
	end)