@flamework-experimental/core 2.0.0-alpha.1 → 2.0.0-alpha.2

package/out/utility/recycleThread.luau

@@ -1,29 +1,48 @@
 -- Compiled with roblox-ts v3.0.0
 local inactiveThread
-local function reusableThread(func)
+local function reusableThread(func, a, b, c, d, e)
 	local thread = coroutine.running()
 	while true do
 		if inactiveThread == thread then
 			inactiveThread = nil
 		end
-		func()
+		func(a, b, c, d, e)
 		-- If there's a different idle thread, we should end the current thread.
 		if inactiveThread ~= nil then
 			break
 		end
 		inactiveThread = thread
-		-- Let go of the callback while idle: it closes over whatever it was run for -- a lifecycle
-		-- listener, a component -- which would otherwise stay reachable from this thread until the
-		-- next callback comes through, and for good when none does.
+		-- Let go of the callback and its arguments while idle: they are whatever it was run for -- a
+		-- lifecycle listener, a component -- which would otherwise stay reachable from this thread
+		-- until the next callback comes through, and for good when none does.
 		func = nil
-		func = coroutine.yield()
+		a = nil
+		b = nil
+		c = nil
+		d = nil
+		e = nil
+		func, a, b, c, d, e = coroutine.yield()
 	end
 end
-local function recycleThread(func)
-	if inactiveThread then
-		task.spawn(inactiveThread, func)
+--[[
+	*
+	 * Runs `func` with the arguments given, on a thread that is kept for the next call once it returns:
+	 * one that yields keeps its thread, and the next call gets a new one.
+	 *
+	 * The arguments are passed through rather than closed over, so that a caller running many callbacks
+	 * -- the per-frame events, once per listener every frame -- creates nothing per call.
+	 
+]]
+local function recycleThread(func, a, b, c, d, e)
+	-- Only while it is parked: a callback that kept `coroutine.running()` and cancelled it later left
+	-- a dead thread here, and every later call, of every module, raised trying to resume it. One that
+	-- is not is dropped, and a new thread takes its place.
+	local idle = inactiveThread
+	if idle ~= nil and coroutine.status(idle) == "suspended" then
+		task.spawn(idle, func, a, b, c, d, e)
 	else
-		task.spawn(reusableThread, func)
+		inactiveThread = nil
+		task.spawn(reusableThread, func, a, b, c, d, e)
 	end
 end
 return {

package/out/utility/threadWaits.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Every thread waiting for another to finish something, to the thread it waits for: an extinguish
+ * waiting in `awaitExtinguished` for one running on another thread, and an ignition waiting for an
+ * `onInit` the lifecycle plugin runs on a thread of its own. Shared by every module, since a chain
+ * of waits runs through several: `awaitExtinguished` follows it to refuse the wait that would close
+ * a circle.
+ *
+ * Or to the Promise it waits for: an ignition waiting for the Promise an `onInit` returned, whose
+ * work runs on a thread nothing can name -- an `async` method's body runs on one of its own, not the
+ * `onInit` thread. A chain that ends at one may end at any thread, the waiting one included.
+ *
+ * An entry is removed by whatever ends the wait -- what is waited for, as it finishes, or the poll
+ * that sees the waiting thread die -- and not by the waiting thread once it resumes: one that is
+ * cancelled never resumes.
+ */
+export declare const threadWaits: Map<thread, thread | Promise<unknown>>;
+/**
+ * How many extinguishes have begun, in any module, counted from the first line of `extinguish()`.
+ * The lifecycle plugin's per-frame walks read it after every callback and ask their module whether
+ * it has begun to extinguish only when it has changed, so that a callback that extinguishes the
+ * module -- itself, on a thread it starts, through a signal it fires -- stops the walk without a
+ * call per listener.
+ */
+export declare const extinguishesBegun: {
+    count: number;
+};
+/**
+ * Whether a thread does Promise work: whether its outermost function -- what it was started with --
+ * is the Promise library's or the one an `async` function's body runs in.
+ *
+ * The lifecycle plugin takes such a thread to be doing the work of the Promise an `onInit` returned
+ * while it waits on one, since nothing records which threads that is: an `async` body that has
+ * yielded, an executor, a chained callback. An unrelated Promise's thread passes too, and a thread
+ * an executor starts itself with `task.spawn` or `task.delay` does not.
+ */
+export declare function runsPromiseWork(thread: thread): boolean;

package/out/utility/threadWaits.luau

@@ -0,0 +1,81 @@
+-- Compiled with roblox-ts v3.0.0
+local TS = _G[script]
+--[[
+	*
+	 * Every thread waiting for another to finish something, to the thread it waits for: an extinguish
+	 * waiting in `awaitExtinguished` for one running on another thread, and an ignition waiting for an
+	 * `onInit` the lifecycle plugin runs on a thread of its own. Shared by every module, since a chain
+	 * of waits runs through several: `awaitExtinguished` follows it to refuse the wait that would close
+	 * a circle.
+	 *
+	 * Or to the Promise it waits for: an ignition waiting for the Promise an `onInit` returned, whose
+	 * work runs on a thread nothing can name -- an `async` method's body runs on one of its own, not the
+	 * `onInit` thread. A chain that ends at one may end at any thread, the waiting one included.
+	 *
+	 * An entry is removed by whatever ends the wait -- what is waited for, as it finishes, or the poll
+	 * that sees the waiting thread die -- and not by the waiting thread once it resumes: one that is
+	 * cancelled never resumes.
+	 
+]]
+local threadWaits = {}
+--[[
+	*
+	 * How many extinguishes have begun, in any module, counted from the first line of `extinguish()`.
+	 * The lifecycle plugin's per-frame walks read it after every callback and ask their module whether
+	 * it has begun to extinguish only when it has changed, so that a callback that extinguishes the
+	 * module -- itself, on a thread it starts, through a signal it fires -- stops the walk without a
+	 * call per listener.
+	 
+]]
+local extinguishesBegun = {
+	count = 0,
+}
+local asyncFunction = TS.async(function() end)
+--[[
+	*
+	 * The scripts a thread doing Promise work starts in: the Promise library, which runs executors and
+	 * chained callbacks on threads of their own, and the runtime library, which runs an `async`
+	 * function's body on one of its own.
+	 
+]]
+local promiseSources = {
+	[(debug.info(TS.Promise.is, "s"))] = true,
+	[(debug.info(asyncFunction, "s"))] = true,
+}
+--[[
+	*
+	 * Whether a thread does Promise work: whether its outermost function -- what it was started with --
+	 * is the Promise library's or the one an `async` function's body runs in.
+	 *
+	 * The lifecycle plugin takes such a thread to be doing the work of the Promise an `onInit` returned
+	 * while it waits on one, since nothing records which threads that is: an `async` body that has
+	 * yielded, an executor, a chained callback. An unrelated Promise's thread passes too, and a thread
+	 * an executor starts itself with `task.spawn` or `task.delay` does not.
+	 
+]]
+local function runsPromiseWork(thread)
+	local outermost
+	local level = 1
+	while true do
+		local source = (debug.info(thread, level, "s"))
+		if source == nil then
+			break
+		end
+		-- A C function (`pcall`, the scheduler's resume) is not where the thread's work comes from.
+		if source ~= "[C]" then
+			outermost = source
+		end
+		level += 1
+	end
+	local _condition = outermost ~= nil
+	if _condition then
+		local _outermost = outermost
+		_condition = promiseSources[_outermost] ~= nil
+	end
+	return _condition
+end
+return {
+	runsPromiseWork = runsPromiseWork,
+	threadWaits = threadWaits,
+	extinguishesBegun = extinguishesBegun,
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flamework-experimental/core",
-  "version": "2.0.0-alpha.1",
+  "version": "2.0.0-alpha.2",
   "main": "out/init.luau",
   "types": "out/index.d.ts",
   "scripts": {