Confusion Regarding 'Good Signal' by Stravant

Here we have stravants script for a custom signal class, “Good Signal”:

--------------------------------------------------------------------------------
--               Batched Yield-Safe Signal Implementation                     --
-- This is a Signal class which has effectively identical behavior to a       --
-- normal RBXScriptSignal, with the only difference being a couple extra      --
-- stack frames at the bottom of the stack trace when an error is thrown.     --
-- This implementation caches runner coroutines, so the ability to yield in   --
-- the signal handlers comes at minimal extra cost over a naive signal        --
-- implementation that either always or never spawns a thread.                --
--                                                                            --
-- API:                                                                       --
--   local Signal = require(THIS MODULE)                                      --
--   local sig = Signal.new()                                                 --
--   local connection = sig:Connect(function(arg1, arg2, ...) ... end)        --
--   sig:Fire(arg1, arg2, ...)                                                --
--   connection:Disconnect()                                                  --
--   sig:DisconnectAll()                                                      --
--   local arg1, arg2, ... = sig:Wait()                                       --
--                                                                            --
-- Licence:                                                                   --
--   Licenced under the MIT licence.                                          --
--                                                                            --
-- Authors:                                                                   --
--   stravant - July 31st, 2021 - Created the file.                           --
--------------------------------------------------------------------------------

-- The currently idle thread to run the next handler on
local freeRunnerThread = nil

-- Function which acquires the currently idle handler runner thread, runs the
-- function fn on it, and then releases the thread, returning it to being the
-- currently idle one.
-- If there was a currently idle runner thread already, that's okay, that old
-- one will just get thrown and eventually GCed.
local function acquireRunnerThreadAndCallEventHandler(fn, ...)
	local acquiredRunnerThread = freeRunnerThread
	freeRunnerThread = nil
	fn(...)
	-- The handler finished running, this runner thread is free again.
	freeRunnerThread = acquiredRunnerThread
end

-- Coroutine runner that we create coroutines of. The coroutine can be 
-- repeatedly resumed with functions to run followed by the argument to run
-- them with.
local function runEventHandlerInFreeThread()
	-- Note: We cannot use the initial set of arguments passed to
	-- runEventHandlerInFreeThread for a call to the handler, because those
	-- arguments would stay on the stack for the duration of the thread's
	-- existence, temporarily leaking references. Without access to raw bytecode
	-- there's no way for us to clear the "..." references from the stack.
	while true do
		acquireRunnerThreadAndCallEventHandler(coroutine.yield())
	end
end

-- Connection class
local Connection = {}
Connection.__index = Connection

function Connection.new(signal, fn)
	return setmetatable({
		_connected = true,
		_signal = signal,
		_fn = fn,
		_next = false,
	}, Connection)
end

function Connection:Disconnect()
	self._connected = false

	-- Unhook the node, but DON'T clear it. That way any fire calls that are
	-- currently sitting on this node will be able to iterate forwards off of
	-- it, but any subsequent fire calls will not hit it, and it will be GCed
	-- when no more fire calls are sitting on it.
	if self._signal._handlerListHead == self then
		self._signal._handlerListHead = self._next
	else
		local prev = self._signal._handlerListHead
		while prev and prev._next ~= self do
			prev = prev._next
		end
		if prev then
			prev._next = self._next
		end
	end
end

-- Make Connection strict
setmetatable(Connection, {
	__index = function(tb, key)
		error(("Attempt to get Connection::%s (not a valid member)"):format(tostring(key)), 2)
	end,
	__newindex = function(tb, key, value)
		error(("Attempt to set Connection::%s (not a valid member)"):format(tostring(key)), 2)
	end
})

-- Signal class
local Signal = {}
Signal.__index = Signal

function Signal.new()
	return setmetatable({
		_handlerListHead = false,
	}, Signal)
end

function Signal:Connect(fn)
	local connection = Connection.new(self, fn)
	if self._handlerListHead then
		connection._next = self._handlerListHead
		self._handlerListHead = connection
	else
		self._handlerListHead = connection
	end
	return connection
end

-- Disconnect all handlers. Since we use a linked list it suffices to clear the
-- reference to the head handler.
function Signal:DisconnectAll()
	self._handlerListHead = false
end

-- Signal:Fire(...) implemented by running the handler functions on the
-- coRunnerThread, and any time the resulting thread yielded without returning
-- to us, that means that it yielded to the Roblox scheduler and has been taken
-- over by Roblox scheduling, meaning we have to make a new coroutine runner.
function Signal:Fire(...)
	local item = self._handlerListHead
	while item do
		if item._connected then
			if not freeRunnerThread then
				freeRunnerThread = coroutine.create(runEventHandlerInFreeThread)
				-- Get the freeRunnerThread to the first yield
				coroutine.resume(freeRunnerThread)
			end
			task.spawn(freeRunnerThread, item._fn, ...)
		end
		item = item._next
	end
end

-- Implement Signal:Wait() in terms of a temporary connection using
-- a Signal:Connect() which disconnects itself.
function Signal:Wait()
	local waitingCoroutine = coroutine.running()
	local cn;
	cn = self:Connect(function(...)
		cn:Disconnect()
		task.spawn(waitingCoroutine, ...)
	end)
	return coroutine.yield()
end

-- Implement Signal:Once() in terms of a connection which disconnects
-- itself before running the handler.
function Signal:Once(fn)
	local cn;
	cn = self:Connect(function(...)
		if cn._connected then
			cn:Disconnect()
		end
		fn(...)
	end)
	return cn
end

-- Make signal strict
setmetatable(Signal, {
	__index = function(tb, key)
		error(("Attempt to get Signal::%s (not a valid member)"):format(tostring(key)), 2)
	end,
	__newindex = function(tb, key, value)
		error(("Attempt to set Signal::%s (not a valid member)"):format(tostring(key)), 2)
	end
})

return Signal

Looking at the code, we see coroutine.yield() is passed into the acquirerunnertheadandcalleventhandler function. How does that work? what am I missing? To the best of my knowledge and after reading the documentation, coroutine.yield() doesn’t return anything, so what’s actually being passed into there? I know coroutine.yield() returns values back to where coroutine.resume() was called, but that doesn’t seem to be the mechanism at play here, since they’re not passing anything into the yield call and not recieving anything where they’re calling coroutine.resume(). I’m left to assume that the task.spawn() is resuming the courotine at exactly where it stopped, and passing in the parameters in place of the yield call, but I’m genuinely not sure what to make of this.

I have no idea, but I am curious… what would you get if you try to print what is being passed into acquireRunnertreadAndCallEventHandler.

Does it print a nil or something?

the only difference between those 2

task.spawn seems to be faster while coroutine.resume is like 2 miliseconds slower (using task.delay because coroutine.yield won’t suspend current coroutine in same frame)



when i reverse order sometimes task.spawn is faster than coroutine.resume by 1 milisecond

forgot to mention: you can pass as much as you want arguments to task.spawn or coroutine.resume and it will return all of them

i hope that helped you understand what coroutine.yield, coroutine.resume, task.spawn does when combined with coroutine.yield

no offense but this might be the worst way to do benchmarks that i have ever seen :sob:

yep my fault blame me i didn’t add os.clock check for this “benchmark” :skull:

In your example, it’s clear that coroutine.yield() is producing some value in some way. To the best of my knowledge the documentation doesn’t give details on that. The docs say that calling yield passes values to resume, but not the other way around. Can you explain this please?


The original runEventHandlerInFreeThread was just a wrapper for passing a vararg to acquireRunnerThreadAndCallEventHandler, but this turned out to leak memory as the ... would keep a strong reference to its arguments as long as the freeRunnerThread was still running.

The whole while true run(coroutine.yield()) end thing is meant to mimic passing a vararg (because coroutine.yield returns any arguments passed by coroutine.resume/task.spawn implicity). This guarantees the arguments aren’t strongly referenced and can still get collected.

Maybe I just didn’t see it, but the docs don’t say anything about that function of coroutine.yield(). It says it returns a tuple, but doesn’t specify anywhere the details you just stated. That’s what was confusing to me. Thanks for replying. But that begs the question, do resume() and yield() both have the capabilities to send and receive information from each other? How does one design based on that?

I sort of misinterpreted what you were asking. The memory leak thing was just caused by the runner preemptively calling the handler for the first time the thread runs, which isn’t directly related to what you were asking.

What GoodSignal is really doing when you fire a signal is:

  1. Iterate over each connection in the linked list.

  2. If the freeRunnerThread doesn’t exist, we create one out of runEventHandlerInFreeThread and resume it so it will yield in the first while iteration.

  3. We spawn the thread with the connection’s callback and the arguments we fired the signal with, which resumes the coroutine.yield() and passes the arguments into acquireRunnerThreadAndCallEventHandler.

  4. There, the acquirer nils out the freeRunnerThread and calls the callback function with the rest of the arguments and then sets the freeRunnerThread back after the callback has finished (either instantly or after the thread finishes yielding, which it might never).

  5. Repeat the process for the rest of the connections in the list. If the thread is still being used, we create a new one, and if it isn’t, we reuse the old one to save memory.


Yeah, coroutine.yield and coroutine.resume return any arguments they pass into each other. That’s how things like task.wait return stuff.

local function callback(x, y, z)
	print("thread:", x, y, z) -- thread: true, false, nil
	
	-- yield and pass 1, 2, 3 to the resumer
	-- when the thread resumes, yield will return what resume passed
	local a, b, c = coroutine.yield(1, 2, 3)
	
	print("thread:", a, b, c) -- thread: foo, bar, baz
end

local thread = coroutine.create(callback)

-- start the thread and pass in some arguments
-- when it yields, it will return a boolean telling if it errored
-- and also a vararg of what was passed to yield
local success, x, y, z = coroutine.resume(thread, true, false, nil)

print("resumer: ", x, y, z) -- resumer: 1, 2, 3

-- resume the thread with more arguments
-- this will pass these back into a, b, c
coroutine.resume(thread, "foo", "bar", "baz")

Okay, after understanding this, everything else in Good Signal made perfect sense. It was a fundamental misunderstanding that made this confusing. Thanks for the help.