Document the new waitqueue design

[tlively]

Specify the new types and instructions for a waitqueue design that
decouples the waitqueue itself from the control word. This is both
more geenral and simpler to implement than the previous waitqueue
design.

Closes #102.

[tlively]

Also cc @manoskouk.

[rossberg]

Looks right, except for table and memory types.

I'm not too fond of how this overloads the different equality operators. That is quite at odds with having i32.eq, i64.eq, and ref.eq as separate instructions, as well as with the two memory.waitN instructions. I understand that this saves a few opcodes, but wouldn't it be more consistent if we had separate wait32, wait64, and wait_ref variants for all?

[rossberg]

Suggested change

	relative timeout in nanoseconds (where negative arguments are interpreted as meaning infinite timeout).
	relative timeout in nanoseconds (interpreted as signed, where negative arguments are interpreted as meaning infinite timeout).

[rossberg]

Suggested change

	C |- table.wait x : [(ref null (shared waitqueue)) i32 t i64] -> [i32]
	-- C.tables[x] = shared? table t'
	-- t = wait_expected(t')
	C |- table.wait x : [(ref null (shared waitqueue)) at t i64] -> [i32]
	-- C.tables[x] = shared? table at lim t'
	-- t = wait_expected(t')

[rossberg]

Suggested change

	C |- memory.wait32 x : [(ref null (shared waitqueue)) t i32 i64] -> [i32]
	-- C.memories[x] = shared? memory t
	C |- memory.wait64 x : [(ref null (shared waitqueue)) t i64 i64] -> [i32]
	-- C.memories[x] = shared? memory t
	C |- memory.wait32 x : [(ref null (shared waitqueue)) at i32 i64] -> [i32]
	-- C.memories[x] = shared? memory at lim
	C |- memory.wait64 x : [(ref null (shared waitqueue)) at i64 i64] -> [i32]
	-- C.memories[x] = shared? memory at lim

[tlively]

I'm not too fond of how this overloads the different equality operators. That is quite at odds with having i32.eq, i64.eq, and ref.eq as separate instructions, as well as with the two memory.waitN instructions. I understand that this saves a few opcodes, but wouldn't it be more consistent if we had separate wait32, wait64, and wait_ref variants for all?

It's rather meant to be consistent with things like struct.get or table.get, which work for any field or element type. It's also consistent with the long-standing documented design for {struct,array,global}.atomic.rmw.cmpxchg, which also works for i32, i64, and eqref elements.

We could of course just add more instructions if we really wanted to, but I don't see any benefit.

[rossberg]

Well, get and set only perform "parametric" reads/writes, they don't inspect or operate on the values themselves (only the _s/u variants do, and they are fixed to a single type). But I agree that cmpxchg is in the same class.

We used to have "no overloading" as one of our slogans. That informed a lot of Wasm's design. I'm not sure what to think about dropping that in passing without a wider discussion, and some agreement about where to draw the line in the future.