@trioforge/crucible 0.1.0 → 0.2.0

package/out/internal/reactive/context.luau

@@ -0,0 +1,149 @@
+-- Compiled with roblox-ts v3.0.0
+local TS = _G[script]
+local _lifecycle = TS.import(script, script.Parent.Parent, "lifecycle")
+local closeScope = _lifecycle.closeScope
+local drain = _lifecycle.drain
+local openScope = _lifecycle.openScope
+local call = TS.import(script, script.Parent.Parent, "runner").call
+--* @internal 
+--* @internal What the running thread is doing for the graph. Only the thread that pushed a frame sees it. 
+local stacks = setmetatable({}, {
+	__mode = "k",
+})
+--* @internal The innermost frame on the running thread. A spawned thread starts with none. 
+local function top()
+	local _arg0 = coroutine.running()
+	local stack = stacks[_arg0]
+	return if stack == nil then nil else stack[#stack]
+end
+--* @internal True on the worker of a body the graph runs, where a nested evaluation runs inline. 
+local function inBody()
+	local _arg0 = coroutine.running()
+	local stack = stacks[_arg0]
+	return stack ~= nil and stack[1] ~= nil and stack[1].kind ~= 2
+end
+--* @internal 
+local function push(frame)
+	local thread = coroutine.running()
+	local stack = stacks[thread]
+	if stack == nil then
+		stack = {}
+		local _stack = stack
+		stacks[thread] = _stack
+	end
+	local _stack = stack
+	local _frame = frame
+	table.insert(_stack, _frame)
+end
+--* @internal Removes `frame` and anything left above it on the running thread, which keeps its emptied stack. 
+local function pop(frame)
+	local _arg0 = coroutine.running()
+	local stack = stacks[_arg0]
+	if stack == nil then
+		return nil
+	end
+	local _frame = frame
+	local index = (table.find(stack, _frame) or 0) - 1
+	if index < 0 then
+		return nil
+	end
+	while #stack > index do
+		stack[#stack] = nil
+	end
+end
+local NONE_OPEN = {}
+--[[
+	*
+	 * @internal
+	 * Takes a finished worker's frames and returns the evaluations it left open, innermost first. A worker that returned
+	 * keeps its emptied stack for its next body.
+	 
+]]
+local function discard(worker, returned)
+	if worker == nil then
+		return NONE_OPEN
+	end
+	local _worker = worker
+	local stack = stacks[_worker]
+	if stack == nil then
+		return NONE_OPEN
+	end
+	local open
+	for i = #stack - 1, 0, -1 do
+		local frame = stack[i + 1]
+		if frame.kind ~= 1 then
+			continue
+		end
+		if open == nil then
+			open = {}
+		end
+		table.insert(open, frame)
+	end
+	if returned then
+		table.clear(stack)
+	else
+		local _worker_1 = worker
+		stacks[_worker_1] = nil
+	end
+	return open or NONE_OPEN
+end
+--* @internal How a body ended, with the evaluations it left open, innermost first. 
+--* A body on its way through `boundary`. It becomes its own completion. 
+--* Starts the worker's stack at the body's frame. 
+local function inner(job)
+	local worker = coroutine.running()
+	job.worker = worker
+	local frame = job.frame
+	if frame ~= nil then
+		local stack = stacks[worker]
+		if stack == nil or #stack > 0 then
+			local _arg1 = { frame }
+			stacks[worker] = _arg1
+		else
+			table.insert(stack, frame)
+		end
+	end
+	return if job.arg == nil then job.body() else job.body(job.arg)
+end
+local function traceback(err)
+	return debug.traceback(tostring(err), 2)
+end
+--[[
+	*
+	 * @internal
+	 * The completion boundary. The body runs under `frame` on a pooled worker inside a lifecycle scope, and `complete`
+	 * runs on this thread before the scope closes, so whatever the body left behind is finished before its requests
+	 * drain. `complete` runs framework code only. A failure there is an internal error and is rethrown here.
+	 
+]]
+local function boundary(owner, frame, body, arg, complete, after)
+	local job = {
+		frame = frame,
+		body = body,
+		arg = arg,
+		after = after,
+		result = 0,
+		value = nil,
+		open = NONE_OPEN,
+	}
+	openScope()
+	local result, value = call(inner, job, nil, owner)
+	job.result = result
+	job.value = value
+	job.open = discard(job.worker, result == 0)
+	local ok, err = xpcall(complete, traceback, job)
+	if closeScope() then
+		drain()
+	end
+	if not ok then
+		error(err, 0)
+	end
+end
+return {
+	top = top,
+	inBody = inBody,
+	push = push,
+	pop = pop,
+	discard = discard,
+	boundary = boundary,
+}

package/out/internal/reactive/flush.d.ts

@@ -0,0 +1 @@
+export {};

package/out/internal/reactive/flush.luau

@@ -0,0 +1,355 @@
+-- Compiled with roblox-ts v3.0.0
+local TS = _G[script]
+local runtimeDiagnostic = TS.import(script, script.Parent.Parent, "diagnostics").runtimeDiagnostic
+local _graph = TS.import(script, script.Parent, "graph")
+local createdBefore = _graph.createdBefore
+local dependenciesMoved = _graph.dependenciesMoved
+local guardPure = _graph.guardPure
+local markEffect = _graph.markEffect
+local observerFrame = _graph.observerFrame
+local originOf = _graph.originOf
+local readUntracked = _graph.readUntracked
+local rewire = _graph.rewire
+local staleAfterRun = _graph.staleAfterRun
+local useScheduler = _graph.useScheduler
+local nextId = _graph.nextId
+local _limits = TS.import(script, script.Parent, "limits")
+local MAX_EFFECT_RUNS_PER_FLUSH = _limits.MAX_EFFECT_RUNS_PER_FLUSH
+local MAX_FLUSH_ROUNDS = _limits.MAX_FLUSH_ROUNDS
+local MAX_RUNS_PER_EFFECT = _limits.MAX_RUNS_PER_EFFECT
+local _ownership = TS.import(script, script.Parent, "ownership")
+local adopt = _ownership.adopt
+local endLifetime = _ownership.endLifetime
+local hold = _ownership.hold
+local newLifetime = _ownership.newLifetime
+local NO_OWNER = _ownership.NO_OWNER
+local ownerLabel = _ownership.ownerLabel
+local resolveOwner = _ownership.resolveOwner
+local retire = _ownership.retire
+local runBody = _ownership.runBody
+local useDescribe = _ownership.useDescribe
+--* @internal What the flush asks of the engine. 
+local port
+--* Every realm starts held, so effects queued while modules load and boot runs wait for the commit. 
+local held = true
+local requested = false
+local flushing = false
+local queue = {}
+--* The entries one round took from the queue, and the index of the first one not yet reached. 
+local batch = {}
+local cursor = 0
+--* The entry being processed, which an internal error stops. 
+local culprit
+--* Every effect whose run count moved this flush. 
+local ran = {}
+--* A bound was reported, and no flush has finished within its bounds since. 
+local boundReported = false
+--* @internal Boot installs the engine's port; until then an enqueue only queues. 
+local function useReactivePort(value)
+	port = value
+	useDescribe(if value == nil then tostring else function(instance)
+		return value.describe(instance)
+	end)
+end
+--* @internal Core edit E2. Idempotent. 
+local function holdBarrier()
+	held = true
+end
+--* @internal Core edit E2. Requests a flush when something is queued. 
+local request
+local function releaseBarrier()
+	held = false
+	if #queue > 0 then
+		request()
+	end
+end
+local flush
+function request()
+	if requested or flushing or held or port == nil then
+		return nil
+	end
+	requested = true
+	local ok = pcall(port.defer, flush)
+	if not ok then
+		requested = false
+	end
+end
+local function enqueue(effect)
+	if effect.queued or effect.stopped then
+		return nil
+	end
+	effect.queued = true
+	local _queue = queue
+	local _effect = effect
+	table.insert(_queue, _effect)
+	request()
+end
+useScheduler(function(effect)
+	return enqueue(effect)
+end)
+local function report(level, message)
+	pcall(runtimeDiagnostic, level, message)
+end
+local function fail(effect, reason)
+	retire(effect)
+	report("error", `Crucible: effect at {effect.origin} ({ownerLabel(effect.parent.owner)}) stopped: {reason}`)
+end
+local function createIn(owner, body)
+	local effect = {
+		kind = 2,
+		id = nextId(),
+		dependencies = {},
+		mark = 2,
+		stopped = false,
+		queued = false,
+		parent = owner,
+		linked = false,
+		body = body,
+		origin = originOf(body),
+		runs = 0,
+	}
+	adopt(owner, effect)
+	enqueue(effect)
+end
+--* @internal 
+local function createEffect(body)
+	guardPure("create effects")
+	local owner = resolveOwner()
+	if owner == nil then
+		error(NO_OWNER, 0)
+	end
+	if owner.ended then
+		return nil
+	end
+	createIn(owner, body)
+end
+local function watchOwner()
+	guardPure("create effects")
+	local owner = resolveOwner()
+	if owner == nil then
+		error(NO_OWNER, 0)
+	end
+	return owner
+end
+--* @internal 
+local watchFrom
+local function createWatch(source, onChange)
+	local owner = watchOwner()
+	local baseline = readUntracked(source)
+	if not owner.ended then
+		watchFrom(owner, source, baseline, onChange)
+	end
+end
+--* @internal A watch whose baseline the caller already read untracked, so `source` is not read again for it. 
+local function createWatchFrom(source, baseline, onChange)
+	local owner = watchOwner()
+	if not owner.ended then
+		watchFrom(owner, source, baseline, onChange)
+	end
+end
+function watchFrom(owner, source, baseline, onChange)
+	local previous = baseline
+	createIn(owner, function()
+		local value = source()
+		if rawequal(value, previous) then
+			return nil
+		end
+		local before = previous
+		previous = value
+		readUntracked(function()
+			return onChange(value, before)
+		end)
+	end)
+end
+--* A run's frame names its effect and its run lifetime. 
+local function complete(completion)
+	local frame = completion.frame
+	local effect = frame.observer
+	local run = frame.lifetime
+	local value = completion.value
+	local failure
+	if completion.result ~= 0 then
+		failure = tostring(value)
+	elseif value ~= nil and not (type(value) == "function") then
+		failure = `returned a {typeof(value)}; an effect returns nothing or a cleanup function`
+	end
+	if failure ~= nil then
+		fail(effect, failure)
+		return nil
+	end
+	if value ~= nil then
+		hold(run, 0, value)
+	end
+	if effect.stopped then
+		return nil
+	end
+	local reads = frame.deps
+	rewire(effect, effect.dependencies, reads)
+	effect.dependencies = reads
+	markEffect(effect, staleAfterRun(effect))
+end
+local function runOnce(effect)
+	local previous = effect.run
+	effect.run = nil
+	if previous ~= nil then
+		endLifetime(previous)
+	end
+	local run = newLifetime(2, effect.parent, effect.parent.owner, effect)
+	effect.run = run
+	runBody(observerFrame(0, effect, run), effect.body, nil, complete)
+end
+local function carry()
+	local rest = {}
+	do
+		local i = cursor
+		local _shouldIncrement = false
+		while true do
+			if _shouldIncrement then
+				i += 1
+			else
+				_shouldIncrement = true
+			end
+			if not (i < #batch) then
+				break
+			end
+			local _arg0 = batch[i + 1]
+			table.insert(rest, _arg0)
+		end
+	end
+	for _, effect in queue do
+		table.insert(rest, effect)
+	end
+	queue = rest
+	batch = {}
+	cursor = 0
+end
+local function reportBound(bound)
+	if boundReported then
+		return nil
+	end
+	boundReported = true
+	local _array = {}
+	local _length = #_array
+	table.move(ran, 1, #ran, _length + 1, _array)
+	local busiest = _array
+	table.sort(busiest, function(a, b)
+		return a.runs > b.runs
+	end)
+	local origins = {}
+	do
+		local i = 0
+		local _shouldIncrement = false
+		while true do
+			if _shouldIncrement then
+				i += 1
+			else
+				_shouldIncrement = true
+			end
+			if not (i < math.min(3, #busiest)) then
+				break
+			end
+			local _arg0 = `{busiest[i + 1].origin} ({busiest[i + 1].runs})`
+			table.insert(origins, _arg0)
+		end
+	end
+	report("warning", `Crucible: the reactive flush reached {bound}; the rest waits for the next flush. Most runs: {table.concat(origins, ", ")}`)
+end
+local function runRounds()
+	local rounds = 0
+	local total = 0
+	while #queue > 0 do
+		if rounds == MAX_FLUSH_ROUNDS then
+			reportBound(`{MAX_FLUSH_ROUNDS} rounds`)
+			return nil
+		end
+		rounds += 1
+		batch = queue
+		queue = {}
+		cursor = 0
+		table.sort(batch, createdBefore)
+		while cursor < #batch do
+			local effect = batch[cursor + 1]
+			cursor += 1
+			culprit = effect
+			effect.queued = false
+			local mark = effect.mark
+			if effect.stopped or mark == 0 then
+				continue
+			end
+			effect.mark = 0
+			if mark == 1 and not dependenciesMoved(effect) then
+				continue
+			end
+			if total == MAX_EFFECT_RUNS_PER_FLUSH then
+				effect.mark = 2
+				effect.queued = true
+				cursor -= 1
+				culprit = nil
+				carry()
+				reportBound(`{MAX_EFFECT_RUNS_PER_FLUSH} effect runs`)
+				return nil
+			end
+			if effect.runs == MAX_RUNS_PER_EFFECT then
+				fail(effect, `ran {MAX_RUNS_PER_EFFECT} times in one flush`)
+				continue
+			end
+			effect.runs += 1
+			total += 1
+			if effect.runs == 1 then
+				table.insert(ran, effect)
+			end
+			runOnce(effect)
+		end
+		culprit = nil
+		batch = {}
+		cursor = 0
+	end
+	boundReported = false
+end
+local function recover(err)
+	local blamed = culprit
+	carry()
+	local stopFailure = ""
+	if blamed ~= nil then
+		local ok, stopErr = pcall(retire, blamed)
+		if not ok then
+			blamed.stopped = true
+			blamed.queued = false
+			stopFailure = `; stopping it failed: {tostring(stopErr)}`
+		end
+	end
+	local where = if blamed == nil then "" else ` while processing the effect at {blamed.origin}`
+	report("error", `Crucible: internal error; the reactive flush recovered{where}: {tostring(err)}{stopFailure}`)
+end
+--* @internal The deferred flush. Runs every queued effect to rest under the bounds. Never throws. 
+function flush()
+	requested = false
+	if held or flushing then
+		return nil
+	end
+	flushing = true
+	local ok, err = pcall(runRounds)
+	if not ok then
+		recover(err)
+	end
+	for _, effect in ran do
+		effect.runs = 0
+	end
+	ran = {}
+	batch = {}
+	cursor = 0
+	culprit = nil
+	flushing = false
+	if #queue > 0 then
+		request()
+	end
+end
+return {
+	useReactivePort = useReactivePort,
+	holdBarrier = holdBarrier,
+	releaseBarrier = releaseBarrier,
+	createEffect = createEffect,
+	createWatch = createWatch,
+	createWatchFrom = createWatchFrom,
+	flush = flush,
+}

package/out/internal/reactive/graph.d.ts

@@ -0,0 +1 @@
+export {};