diff --git a/.lute/styling.luau b/.lute/styling.luau index e782a53..7c6f094 100644 --- a/.lute/styling.luau +++ b/.lute/styling.luau @@ -1,6 +1,6 @@ local process = require("@lute/process") -local cmd = { "stylua", ".lute", "src", "tests" } +local cmd = { "stylua", ".lute", "src", "tests", "bench" } -- kinda cursed but, easiest way to do this. table.insert(cmd, "--check") diff --git a/.vscode/settings.json b/.vscode/settings.json index 7a4a07c..ba0c5a4 100644 --- a/.vscode/settings.json +++ b/.vscode/settings.json @@ -15,8 +15,6 @@ "luau-lsp.completion.imports.stringRequires.enabled": true, - "luau-lsp.types.definitionFiles": ["types/globals.d.luau"], - "luau-lsp.sourcemap.autogenerate": false, "luau-lsp.sourcemap.enabled": false, "luau-lsp.sourcemap.includeNonScripts": true, diff --git a/ERRORS.md b/ERRORS.md index 7094ed7..d804e8d 100644 --- a/ERRORS.md +++ b/ERRORS.md @@ -67,3 +67,7 @@ Self explanatory. ## stable_parent_assertion_failed ## invalid_parent_scope + +## too_many_edges + +A node read more than 65535 different nodes in one run, or more than 65535 nodes are reading it at once. Split the reads across derives, so no single node has to read or be read by that many. diff --git a/README.md b/README.md index 7a8ff87..4b3a738 100644 --- a/README.md +++ b/README.md @@ -19,7 +19,7 @@ This section details the interesting bits where Fluid has an advantage. - Push-pull reactive graph with deferred mode - `interval` utility to poll values. `fluid.interval` will run at the specified hz - Exported `UsedAs` type -- `_G.__DEV__` for development mode, which will enhance error messages & print useful information at the cost of performance. +- `fluid.dev()` for development mode, which adds extra checks (e.g. erroring when a reactive function yields) at the cost of performance. ## Prior Art diff --git a/bench/bench.luau b/bench/bench.luau new file mode 100644 index 0000000..076e34b --- /dev/null +++ b/bench/bench.luau @@ -0,0 +1,177 @@ +-- reactive graph benchmark, run with `lute run bench/bench.luau` +-- pass dev (`lute run bench/bench.luau dev`) to benchmark with dev mode enabled + +local BENCH, START = require("@vendor/testkit").benchmark() +local fluid = require("@src/") +local process = require("@lute/process") + +-- the first arg is the script's path +local DEV = process.args[2] == "dev" +if DEV then + fluid.dev() +end + +local step = fluid.provide_scheduler() + +-- roots are destroyed after each benchmark, so teardown isn't measured +local destroy: () -> () = function() end + +print(`dev = {DEV}`) + +BENCH("create effect", function() + destroy = fluid.root(function() + local src = fluid.source(0) + + for _ = 1, START(10000) do + fluid.effect(function() + src() + end) + end + end) +end) +destroy() + +BENCH("set source with 1000 eager dependents", function() + local src = fluid.source(0) + + destroy = fluid.root(function() + for _ = 1, 1000 do + fluid.effect(function() + src() + end) + end + end) + + for i = 1, START(200) do + src(i) + end +end) +destroy() + +BENCH("set source of effect with 10 dependencies", function() + local sources = {} + for i = 1, 10 do + sources[i] = fluid.source(0) + end + + destroy = fluid.root(function() + fluid.effect(function() + for i = 1, 10 do + sources[i]() + end + end) + end) + + for i = 1, START(5000) do + sources[i % 10 + 1](i) + end +end) +destroy() + +BENCH("set + flush deferred effect behind 5 derives", function() + local src = fluid.source(0) + + destroy = fluid.root(function() + local previous: () -> number = src + for _ = 1, 5 do + local read = previous + previous = fluid.derive(function() + return read() + 1 + end) + end + + local last = previous + fluid.deferred(function() + last() + end) + end) + + for i = 1, START(2000) do + src(i) + step(1 / 60) + end +end) +destroy() + +BENCH("set + flush 50 derives that don't change", function() + local src = fluid.source(0) + local unrelated = fluid.source(0) + + destroy = fluid.root(function() + local gate = fluid.derive(function() + return unrelated() > 1e9 + end) + + local consumers = {} + for i = 1, 50 do + consumers[i] = fluid.derive(function() + src() + gate() + return i + end) + end + + fluid.deferred(function() + for i = 1, 50 do + consumers[i]() + end + end) + end) + + for i = 1, START(2000) do + -- alternates between rerunning everything, and only rerunning the gate + if i % 2 == 0 then + src(i) + else + unrelated(i) + end + step(1 / 60) + end +end) +destroy() + +BENCH("step 1000 springs", function() + local targets = {} + + destroy = fluid.root(function() + for i = 1, 1000 do + local target = fluid.source(0) + targets[i] = target + + local spring = fluid.spring(target, 10, 0.5) + fluid.effect(function() + spring() + end) + end + end) + + for i = 1, 1000 do + targets[i](100) + end + + for _ = 1, START(300) do + step(1 / 60) + end +end) +destroy() + +BENCH("step 100 intervals", function() + destroy = fluid.root(function() + for _ = 1, 100 do + local elapsed = 0 + local value = fluid.interval(function(dt) + elapsed += dt + return elapsed + end) + + fluid.effect(function() + value() + end) + end + end) + + for _ = 1, START(600) do + step(1 / 60) + end +end) +destroy() diff --git a/roblox-tests.project.json b/roblox-tests.project.json index 9ed0f31..87237a9 100644 --- a/roblox-tests.project.json +++ b/roblox-tests.project.json @@ -4,6 +4,7 @@ "emitLegacyScripts": false, "tree": { + "$ignoreUnknownInstances": true, "$className": "DataModel", "ReplicatedStorage": { diff --git a/src/anim/lerp.luau b/src/anim/lerp.luau index 4a32b6a..67198a1 100644 --- a/src/anim/lerp.luau +++ b/src/anim/lerp.luau @@ -3,24 +3,21 @@ local oklab = require("../utils/oklab") local read = require("../utils/read") local types = require("../reactive/types") +local DEFERRED = graph.evaluation.DEFERRED local active_animations = {} -local function vector_lerp(a: vector, b: vector, t: number): vector - return a + (b - a) * t -end - local function general_lerp(a: any, b: any, t: number): any return a + (b - a) * t end local lerp_functions: { [string]: (a: any, b: any, t: number) -> any } = { number = math.lerp, - Vector3 = vector_lerp, + Vector3 = vector.lerp, Vector2 = general_lerp, Color3 = function(a: Color3, b: Color3, t) local initial_vector = oklab.from_srgb(vector.create(a.R, a.G, a.B)) local goal_vector = oklab.from_srgb(vector.create(b.R, b.G, b.B)) - local interpolated_vector = vector_lerp(initial_vector, goal_vector, t) + local interpolated_vector = vector.lerp(initial_vector, goal_vector, t) local result_vector = vector.clamp(oklab.to_srgb(interpolated_vector), vector.zero, vector.one) return Color3.new(result_vector.x, result_vector.y, result_vector.z) @@ -52,7 +49,7 @@ function lerp.create(goal: types.UsedAs, takes: types.UsedAs) return nil end - graph.create_reactive_node(graph.assert_stable_parent(), effect, "deferred") + graph.create_reactive_node(graph.assert_stable_parent(), effect, DEFERRED) return function() graph.push_dependency(output) diff --git a/src/anim/spring/spring_file.luau b/src/anim/spring/spring_file.luau index fb8ba1d..189474d 100644 --- a/src/anim/spring/spring_file.luau +++ b/src/anim/spring/spring_file.luau @@ -4,6 +4,7 @@ local oklab = require("../../utils/oklab") local read = require("../../utils/read") local types = require("../../reactive/types") +local DEFERRED = graph.evaluation.DEFERRED local SLEEP_VELOCITY = 1e-3 local SLEEP_DISTANCE = 1e-5 @@ -177,7 +178,7 @@ function spring_file.create( end -- set up the dependency - local input_node = graph.create_reactive_node(graph.assert_stable_parent(), on_update, "deferred", read(input)) + local input_node = graph.create_reactive_node(graph.assert_stable_parent(), on_update, DEFERRED, read(input)) graph.evaluate_node(input_node) diff --git a/src/dev.luau b/src/dev.luau new file mode 100644 index 0000000..09b4dd1 --- /dev/null +++ b/src/dev.luau @@ -0,0 +1,7 @@ +-- dev mode adds extra checks (e.g. erroring when a reactive function yields) at the cost of performance. +-- enabled through fluid.dev() +local dev = { + enabled = false, +} + +return dev diff --git a/src/init.luau b/src/init.luau index 34108a4..4263ba8 100644 --- a/src/init.luau +++ b/src/init.luau @@ -2,10 +2,10 @@ local action = require("@self/instances/action") local async = require("@self/reactive/async") local bind = require("@self/instances/bind") local changed = require("@self/instances/changed") -local cleanup = require("@self/reactive/cleanup") local create = require("@self/instances/create") local deferred = require("@self/reactive/deferred") local derive = require("@self/reactive/derive") +local dev = require("@self/dev") local effect = require("@self/reactive/effect") local for_keys = require("@self/instances/for_keys") local for_values = require("@self/instances/for_values") @@ -31,8 +31,22 @@ export type Source = types.Source export type Action = action.Identity export type PropertiesFor = create.PropertiesFor +type Destroyable = { destroy: (any) -> () } | { Destroy: (any) -> () } +type Disconnectable = { disconnect: (any) -> () } | { Disconnect: (any) -> () } + local scheduler_thread: thread? = nil +-- values are stored as is, the graph works out how to clean them up when the scope reruns or dies +local function cleanup(value: graph.Cleanup) + local scope = graph.get_scope() + + if not scope then + error("cannot cleanup outside a stable or reactive scope") + end + + graph.push_cleanup(scope, value) +end + local function step(delta_time: number) -- This will call intervals scheduler.step(delta_time) @@ -70,7 +84,8 @@ fluid.action = action.create fluid.is_action = action.is_action -- Reactive graph -fluid.cleanup = cleanup +fluid.cleanup = + cleanup :: ((callback: () -> ()) -> ()) & ((thread: thread) -> ()) & ((instance: Destroyable) -> ()) & ((connection: Disconnectable) -> ()) & ((instance: Instance) -> ()) & ((connection: RBXScriptConnection) -> ()) fluid.derive = derive fluid.effect = effect fluid.deferred = deferred @@ -102,6 +117,12 @@ fluid.provide_scheduler = function(): (delta_time: number) -> () return step end +-- toggles dev mode, which adds extra checks (e.g. erroring when a reactive function yields) +-- at the cost of performance. call this before mounting anything +fluid.dev = function() + dev.enabled = true +end + fluid.__SCHEDULER_INTERFACE = scheduler return fluid diff --git a/src/instances/bind.luau b/src/instances/bind.luau index f052a1d..2002d98 100644 --- a/src/instances/bind.luau +++ b/src/instances/bind.luau @@ -2,6 +2,20 @@ local action = require("./action") local graph = require("../reactive/graph") local types = require("../reactive/types") +type Result = Instance | { Result } | () -> Result + +type ReactiveChild = { + children: { [Instance]: number }, -- [child]: update said child was last in the result of + callback: () -> Result, + instance: Instance, + update_id: number, +} + +local DEFERRED = graph.evaluation.DEFERRED +local EAGER = graph.evaluation.EAGER +local EVENTS = table.create< ()>>(20) +local TOTAL_EVENTS = 0 + local function set_property(inst: Instance, property: string, value: any) (inst :: any)[property] = value end @@ -11,130 +25,147 @@ local function get_property(inst: Instance, property: string): any end local function bind_property(inst: Instance, property: string, value: types.Readable) - local property_node = graph.create_reactive_node(graph.assert_stable_parent(), function() + local property_node = graph.create_effect_node(graph.assert_stable_parent(), function() set_property(inst, property, value()) return nil - end, "eager", nil) + end, EAGER, nil) - graph.evaluate_node(property_node) + graph.refresh_node(property_node) end -type Result = Instance | { Result } | () -> Result - -local function reactive_child_effect( - inst: Instance, - func: () -> Result, - sets: { - new: { [Instance]: true }, - current: { [Instance]: true }, - } -) - local new_child_set = sets.new - local current_child_set = sets.current - local source_result = func() - - if not source_result then - for old_inst in current_child_set do - old_inst.Parent = nil - end - - return sets - end - - local function process_child(child: Result) - if typeof(child) == "Instance" then - new_child_set[child] = true +local reactive_child_effect: (reactive_child: ReactiveChild) -> ReactiveChild - if current_child_set[child] then - current_child_set[child] = nil - return - end - - child.Parent = inst +local function process_child(instance: Instance, children: { [Instance]: number }, update_id: number, child: Result) + if typeof(child) == "Instance" then + local seen = children[child] + -- already parented if it's in the result more than once + if seen == update_id then return end - if typeof(child) == "function" then - local children: { new: { [Instance]: true }, current: { [Instance]: true } } = { new = {}, current = {} } - - graph.create_reactive_node(graph.get_scope(), function(value) - return reactive_child_effect(inst, child, value) - end, "deferred", children) - - graph.push_cleanup(graph.get_scope(), function() - for child in children.current do - child.Parent = nil - end - end) + children[child] = update_id - return + if not seen then + child.Parent = instance end + return + end - for _, child in child do - process_child(child) - end + if typeof(child) == "function" then + local scope = graph.assert_scope() + local reactive_child: ReactiveChild = { instance = instance, callback = child, children = {}, update_id = 0 } + graph.create_effect_node(scope :: any, reactive_child_effect, DEFERRED, reactive_child) + graph.push_cleanup(scope, function() + for child in reactive_child.children do + child.Parent = nil + end + end) return end - process_child(source_result) - - for child in current_child_set do - child.Parent = nil + for _, nested_child in child do + process_child(instance, children, update_id, nested_child) end +end - table.clear(current_child_set) - sets.current, sets.new = new_child_set, current_child_set +function reactive_child_effect(reactive_child: ReactiveChild): ReactiveChild + local children = reactive_child.children + local update_id = reactive_child.update_id + 1 + reactive_child.update_id = update_id - return sets -end + local result = reactive_child.callback() + if result then + process_child(reactive_child.instance, children, update_id, result) + end -local function bind_reactive_child(inst: Instance, func: () -> Result) - local stable_node = graph.get_scope() :: graph.StableNode + -- removes the children that weren't in this result + for child, seen in children do + if seen ~= update_id then + children[child] = nil + child.Parent = nil + end + end - local children: { new: { [Instance]: true }, current: { [Instance]: true } } = { new = {}, current = {} } + return reactive_child +end - local property_node = graph.create_reactive_node(stable_node :: any, function(value) - return reactive_child_effect(inst, func, value) - end, "deferred", children) +local function bind_reactive_child(instance: Instance, func: () -> Result) + local reactive_child: ReactiveChild = { instance = instance, callback = func, children = {}, update_id = 0 } + local property_node = + graph.create_effect_node(graph.get_scope() :: any, reactive_child_effect, DEFERRED, reactive_child) - graph.evaluate_node(property_node) + graph.refresh_node(property_node) end -local function bind(inst: Instance, props: { [unknown & number]: unknown }) +local function bind(instance: Instance, props: { [unknown & number]: unknown }) + local parent: (Instance | () -> Instance)? + -- starting index for the event connections being attached to this instance in the EVENTS array + local events_start = TOTAL_EVENTS + for key: any, value: any in props do - local key_type, value_type = type(key), typeof(value) + local value_type = typeof(value) + local key_type = type(key) if key_type == "string" then - local property_value = get_property(inst, key) - if typeof(property_value) ~= "RBXScriptSignal" then - if value_type == "function" then - bind_property(inst, key, value) + if key == "Parent" then + parent = value + -- only functions can be event handlers, so other values skip reading the property + elseif value_type ~= "function" then + set_property(instance, key, value) + else + local property_value = get_property(instance, key) + + if typeof(property_value) ~= "RBXScriptSignal" then + bind_property(instance, key, value) else - set_property(inst, key, value) + TOTAL_EVENTS += 1 + EVENTS[TOTAL_EVENTS] = property_value + TOTAL_EVENTS += 1 + EVENTS[TOTAL_EVENTS] = value end - elseif value_type == "function" then - local connection = property_value:Connect(value) - - graph.push_cleanup(graph.assert_scope(), function() - connection:Disconnect() - end) end else if value_type == "Instance" then - value.Parent = inst + value.Parent = instance elseif value_type == "table" then if value.__ACTION_SYMBOL == action.symbol then - value.callback(inst) + value.callback(instance) else - bind(inst, value) + bind(instance, value) end elseif value_type == "function" then - bind_reactive_child(inst, value) + bind_reactive_child(instance, value) end end end - return inst + + -- connecting events last so that property setting during construction can't trigger events before the instance is parented + if TOTAL_EVENTS ~= events_start then + local scope = graph.assert_scope() + + -- iterating backwards so each pair can be cleared right after it's connected + -- without luau converting the EVENTS array into a hash + for index = TOTAL_EVENTS, events_start + 2, -2 do + local event_index = index - 1 + graph.push_cleanup(scope, (EVENTS[event_index] :: RBXScriptSignal):Connect(EVENTS[index] :: () -> ())) + EVENTS[index] = nil + EVENTS[event_index] = nil + end + + TOTAL_EVENTS = events_start + end + + -- setting parent last to avoid datamodel change tracking whilst the instance is being constructed + if parent then + if type(parent) == "function" then + bind_property(instance, "Parent", parent) + else + instance.Parent = parent + end + end + + return instance end return bind diff --git a/src/instances/changed.luau b/src/instances/changed.luau index 90e9a9b..bff5eaf 100644 --- a/src/instances/changed.luau +++ b/src/instances/changed.luau @@ -9,9 +9,7 @@ local function changed(property: string, fn: (any) -> ()) fn((instance :: any)[property]) end) - graph.push_cleanup(graph.assert_scope(), function() - con:Disconnect() - end) + graph.push_cleanup(graph.assert_scope(), con) end) end diff --git a/src/instances/create.luau b/src/instances/create.luau index 77a90dc..c6a621d 100644 --- a/src/instances/create.luau +++ b/src/instances/create.luau @@ -210,19 +210,25 @@ export type function PropertiesFor(class_name: type): type return properties end -local function try_create_instance(class_name: string): Instance - local success, call_result = pcall(Instance.new, class_name) - assert(success, call_result) - - return call_result -end +-- cached per class, so creating an instance doesn't also create a new closure every time +-- weak so constructors that don't get used often will be cleared +local constructors: { [string]: ({}) -> Instance } = setmetatable({}, { __mode = "v" }) local function create( class_name: ClassName | keyof | "" ): (props: PropertiesFor) -> GetInstance - return function(properties) - return bind(try_create_instance(class_name), properties) :: any + local name = class_name :: string + local constructor = constructors[name] + + if not constructor then + function constructor(props: {}) + return bind(Instance.new(name), props :: any) + end + + constructors[name] = constructor end + + return constructor :: any end return create diff --git a/src/instances/for_keys.luau b/src/instances/for_keys.luau index d00900d..31c9339 100644 --- a/src/instances/for_keys.luau +++ b/src/instances/for_keys.luau @@ -3,6 +3,8 @@ local read = require("../utils/read") local scheduler = require("../scheduler") local types = require("../reactive/types") +local LAZY = graph.evaluation.LAZY + local function indexes( input: types.UsedAs<{ read [K]: VI }>, transform: (() -> VI, K, active: types.Readable) -> (VO, number?) @@ -19,7 +21,7 @@ local function indexes( local output_delays: { [K]: number? } = {} local output_active: { [K]: graph.SourceNode } = {} local destruction_threads: { [K]: thread } = {} - local reactive_node = graph.create_reactive_node<>(child_parent, false, "lazy", {}) + local reactive_node = graph.create_reactive_node<>(child_parent, false, LAZY, {} :: any) -- due to how the hybrid push pull graph works, we can't invalidate the reactive -- node. doing so will cause the graph to look at it's dependencies and -- make the correct assumption that the reactive node hasn't updated. @@ -47,7 +49,7 @@ local function indexes( -- remove unused values for key in input_nodes do - if input[key] or destruction_threads[key] then + if input[key] ~= nil or destruction_threads[key] then continue end local node = output_active[key] diff --git a/src/instances/for_values.luau b/src/instances/for_values.luau index 2a9b5f6..b025ead 100644 --- a/src/instances/for_values.luau +++ b/src/instances/for_values.luau @@ -3,6 +3,8 @@ local read = require("../utils/read") local scheduler = require("../scheduler") local types = require("../reactive/types") +local LAZY = graph.evaluation.LAZY + local function values( input: types.UsedAs<{ read [KI]: V }>, transform: ( @@ -23,7 +25,7 @@ local function values( local output_delays: { [V]: number? } = {} local output_active: { [V]: graph.SourceNode } = {} local destruction_threads: { [V]: thread } = {} - local reactive_node = graph.create_reactive_node<>(child_parent, false, "lazy", {}) + local reactive_node = graph.create_reactive_node<>(child_parent, false, LAZY, {} :: any) -- due to how the hybrid push pull graph works, we can't invalidate the reactive -- node. doing so will cause the graph to look at it's dependencies and -- make the correct assumption that the reactive node hasn't updated. @@ -38,7 +40,6 @@ local function values( output_active[value] = nil output_delays[value] = nil destruction_threads[value] = nil - graph.invalidate(reactive_node) end local function destroy_delayed(value: V) @@ -94,9 +95,9 @@ local function values( return key_node.cached_value end - local function read_active(): KI + local function read_active(): boolean graph.push_dependency(active_node) - return active_node.cached_value + return active_node.cached_value :: any end local result: KO, delay: number? = diff --git a/src/logging.luau b/src/logging.luau index 9de65d3..ca48c6a 100644 --- a/src/logging.luau +++ b/src/logging.luau @@ -1,5 +1,5 @@ --!optimize 1 -local dev_mode = true +local task = (task or require("@lute/task")) :: typeof(task) local function format(text: string): string return (string.format("[fluid]: %*", text)) @@ -27,8 +27,12 @@ function logging.error(text: string) error(format(text)) end +function logging.report_error(text: string) + task.spawn(error, format(text), 0) +end + function logging.warn_traceback(text: string, thread: thread) - logging.__warn_facade(debug.traceback(thread, format(text), 2)) + warn(debug.traceback(thread, format(text), 2)) end function logging.errors.inst_prop_nonexistent(inst_class: string, inst_property: string) @@ -95,6 +99,10 @@ function logging.errors.graph_stable_parent_assertion_failed() return `STABLE PARENT ASSERTION FAILED: {debug.info(2, "n")}:{debug.info(2, "l")}` end +function logging.errors.graph_too_many_edges(max: number) + return `A node can't depend on or be depended on by more than {max} nodes [too_many_edges]` +end + function logging.errors.graph_cant_call_while_parent_scope_reactive(func_name: string) return `Can't call fluid.{func_name} while the current scope is reactive` end diff --git a/src/reactive/async.luau b/src/reactive/async.luau index 547c925..bfe0520 100644 --- a/src/reactive/async.luau +++ b/src/reactive/async.luau @@ -7,7 +7,7 @@ type State = "busy" | "ok" --[[ async nodes creates a source node for the latest valid value and for the state. -it also creates a reactive node which spawns a new thread that it runs under it's +it also creates a reactive node which runs the callback on a thread under it's own scope. when created, the async node gets immediately evaluated similar to an effect. @@ -15,38 +15,59 @@ unlike an effect though, all evaluations are deferred since we make the assumpti that async yields every single time. ]] +local ASYNC = graph.evaluation.ASYNC +local free_runner: thread? = nil + +local function runner_loop(run: () -> ()) + local thread = coroutine.running() + + while true do + free_runner = nil + run() + free_runner = thread + run = coroutine.yield() + end +end + local function async(callback: (set: (T) -> ()) -> T): (() -> T, () -> State) local reactive_node: graph.ReactiveNode local value: graph.SourceNode = graph.create_source_node(nil) local state: graph.SourceNode = graph.create_source_node("busy") :: any + local running: thread? = nil local function set(new: T) graph.update_node(value :: any, new) end - local function update() - assert(reactive_node, "reactive node does not exist") - graph.update_node(state, "busy") + local function run() + running = coroutine.running() + local ok, result = graph.run_as(reactive_node, callback, set) + running = nil - -- manually set the node to be busy - local thread = task.spawn(function() - local ok, call = graph.run_as(reactive_node, callback, set) + if ok then + set(result) + else + logging.report_error((result :: any).trace) + end - if ok then - set(call) - else - logging.warn(call.trace) - end - - graph.update_node(state, "ok") - end) + graph.update_node(state, "ok") + end - graph.push_cleanup(reactive_node, function() + local function cancel() + local thread = running + if thread then + running = nil scheduler.cancel(thread) - end) + end + end + + local function update() + graph.update_node(state, "busy") + graph.push_cleanup(reactive_node, cancel) + task.spawn(free_runner or coroutine.create(runner_loop), run) end - reactive_node = graph.create_reactive_node(graph.assert_stable_parent(), update :: any, "async") + reactive_node = graph.create_reactive_node(graph.assert_stable_parent(), update :: any, ASYNC) graph.evaluate_node(reactive_node) diff --git a/src/reactive/cleanup.luau b/src/reactive/cleanup.luau index 5a2d7e2..1df5b38 100644 --- a/src/reactive/cleanup.luau +++ b/src/reactive/cleanup.luau @@ -1,49 +1,48 @@ -local graph = require("./graph") -local get_scope = graph.get_scope -local push_cleanup = graph.push_cleanup +local scheduler = require("../scheduler") -local function helper(obj: any) - return if typeof(obj) == "RBXScriptConnection" - then function() - obj:Disconnect() - end - elseif type(obj) == "thread" then function() - task.cancel(obj) - end - elseif typeof(obj) == "Instance" then function() - obj:Destroy() - end - elseif obj.destroy then function() - obj:destroy() - end - elseif obj.disconnect then function() - obj:disconnect() - end - elseif obj.Destroy then function() - obj:Destroy() - end - elseif obj.Disconnect then function() - obj:Disconnect() - end - else error("cannot cleanup given object") -end +-- objects are stored as is and get disconnected/cancelled/destroyed, instead of needing a +-- closure for each one +export type CleanupObject = + { destroy: (self: any) -> () } + | { disconnect: (self: any) -> () } + | { Destroy: (self: any) -> () } + | { Disconnect: (self: any) -> () } -local function cleanup(value: unknown) - local scope = get_scope() +export type Cleanup = (() -> ()) | thread | RBXScriptConnection | Instance | CleanupObject - if not scope then - error("cannot cleanup outside a stable or reactive scope") - end - assert(scope) +-- the solver can't narrow CleanupObject by which key it has, so cleanup looks for the method through this +type CleanupMethods = { + read destroy: ((self: any) -> ())?, + read disconnect: ((self: any) -> ())?, + read Destroy: ((self: any) -> ())?, + read Disconnect: ((self: any) -> ())?, +} + +-- cleans up a value that was passed to fluid.cleanup, the graph calls it when the scope reruns or dies +local function cleanup(value: Cleanup) + local kind = typeof(value) - if type(value) == "function" then - push_cleanup(scope, value :: () -> ()) + if kind == "function" then + (value :: () -> ())() + elseif kind == "RBXScriptConnection" then + (value :: any):Disconnect() + elseif kind == "thread" then + scheduler.cancel(value :: thread) + elseif kind == "Instance" then + (value :: any):Destroy() else - push_cleanup(scope, helper(value)) + local object = (value :: CleanupObject) :: CleanupMethods + + if object.destroy then + object:destroy() + elseif object.disconnect then + object:disconnect() + elseif object.Destroy then + object:Destroy() + elseif object.Disconnect then + object:Disconnect() + end end end -type Destroyable = { destroy: (any) -> () } | { Destroy: (any) -> () } -type Disconnectable = { disconnect: (any) -> () } | { Disconnect: (any) -> () } - -return cleanup :: ((callback: () -> ()) -> ()) & ((thread: thread) -> ()) & ((instance: Destroyable) -> ()) & ((connection: Disconnectable) -> ()) & ((instance: Instance) -> ()) & ((connection: RBXScriptConnection) -> ()) +return cleanup diff --git a/src/reactive/deferred.luau b/src/reactive/deferred.luau index 22199d5..1fda3fd 100644 --- a/src/reactive/deferred.luau +++ b/src/reactive/deferred.luau @@ -1,10 +1,12 @@ local graph = require("./graph") local types = require("./types") +local DEFERRED = graph.evaluation.DEFERRED + local function deferred(callback: types.Effect, initial_value: T) - local node = graph.create_reactive_node(graph.assert_stable_parent(), callback, "deferred", initial_value) + local node = graph.create_effect_node(graph.assert_stable_parent(), callback, DEFERRED, initial_value) - graph.evaluate_node(node) + graph.refresh_node(node) end -- cover effect(function() end) and effect(function() return 1 end, 1) diff --git a/src/reactive/derive.luau b/src/reactive/derive.luau index a8187bb..e036571 100644 --- a/src/reactive/derive.luau +++ b/src/reactive/derive.luau @@ -1,11 +1,14 @@ local graph = require("./graph") local types = require("./types") +local evaluate_node = graph.evaluate_node +local LAZY = graph.evaluation.LAZY + local function derive(source: types.Effect): types.Readable - local node = graph.create_reactive_node(graph.assert_stable_parent(), source, "lazy") + local node = graph.create_reactive_node(graph.assert_stable_parent(), source, LAZY) local function evaluate() - return graph.evaluate_node(node) + return evaluate_node(node) end return evaluate diff --git a/src/reactive/effect.luau b/src/reactive/effect.luau index 2279674..deba787 100644 --- a/src/reactive/effect.luau +++ b/src/reactive/effect.luau @@ -1,10 +1,12 @@ local graph = require("./graph") local types = require("./types") +local EAGER = graph.evaluation.EAGER + local function effect(callback: types.Effect, initial_value: T) - local node = graph.create_reactive_node(graph.assert_stable_parent(), callback, "eager", initial_value) + local node = graph.create_effect_node(graph.assert_stable_parent(), callback, EAGER, initial_value) - graph.evaluate_node(node) + graph.refresh_node(node) end -- cover effect(function() end) and effect(function() return 1 end, 1) diff --git a/src/reactive/graph.luau b/src/reactive/graph.luau index bd94fd2..3f97753 100644 --- a/src/reactive/graph.luau +++ b/src/reactive/graph.luau @@ -1,161 +1,346 @@ +local cleanup = require("./cleanup") +local dev = require("../dev") local exception = require("../utils/exception") local logging = require("../logging") -local reactive_fn_calls = require("../utils/reactive_fn_calls") +local no_yield_call = require("../utils/no_yield_call") local scheduler = require("../scheduler") local types = require("./types") -local dev_mode = true -local deferred_thread: thread? = nil -local pending_eval: { ReactiveNode } = {} -local processing_node: { [thread]: Node } = {} -local deferred_nodes: { Node } = {} -local version = 0 - export type SourceNode = { + --- Version the value last changed at last_evaluation: number, - state: "clean", + --- The node's kind and state, see the flags above + flags: number, effect: false, - cached_value: T, --- Other nodes that depend on the result of this node. - dependents: { ReactiveNode }, + dependents: { Computation }, + --- stores the index of this node in each dependant's depending_on array + dependent_slots: buffer, + --- epoch of the last run that read this node, so reading it multiple times in one run doesn't add duplicate edges + tracked_epoch: number, } export type StableNode = { last_evaluation: number, - parent: Node | false, - children: { Node }, - - --- Describes the effect to run to compute the result of this node. + flags: number, effect: false, - - state: "clean", cached_value: T, - -- Cleanup functions run when the node dies - cleanups: { () -> () }, + parent: Node | false, + --- index of this node in its parent's children + child_index: number, + children: { Node }, + cleanups: { Cleanup }, } export type ReactiveNode = { last_evaluation: number, - parent: Node | false, - children: { Node }, - + flags: number, --- Describes the effect to run to compute the result of this node. effect: types.Effect | false, - -- async is similar to eager, but unlike eager does not actually update the - -- value. this is necessary to support a proper async reactive primitive - evaluation: "eager" | "deferred" | "lazy" | "dead" | "async", + cached_value: T, + + parent: Node | false, + child_index: number, + children: { Node }, + cleanups: { Cleanup }, - -- clean: the cached_value result can be used immediately - -- dirty: you need to recompute the node - -- thread: the node is already being recomputed - throw an error! - -- dead: the node is dead - state: "clean" | "dirty" | thread | "dead", + --- the version the node was last known to be up to date at, deps that changed after it make the node rerun + verified_at: number, + depending_on: { SourceNode | ReactiveNode }, + --- stores the index of this node in each dependant's dependents array + depending_on_slots: buffer, + --- the epoch of the last run of the node + epoch: number, + --- how many dependencies have been read in the current run; reads are matched against depending_on by position, + --- so edges that are read again in the same order get kept instead of being removed and added again + tracking_index: number, + + dependents: { Computation }, + dependent_slots: buffer, + tracked_epoch: number, +} +-- node that runs an effect but never gets read by another node (effect(), deferred(), property bindings, reactive children), +-- so it has nothing for tracking dependents to save memory +export type EffectNode = { + last_evaluation: number, + flags: number, + effect: types.Effect | false, cached_value: T, - cleanups: { () -> () }, + parent: Node | false, + child_index: number, + children: { Node }, + cleanups: { Cleanup }, + verified_at: number, depending_on: { SourceNode | ReactiveNode }, - dependents: { ReactiveNode }, + depending_on_slots: buffer, + epoch: number, + tracking_index: number, } -export type Node = ReactiveNode | StableNode +--- Nodes that run an effect +export type Computation = ReactiveNode | EffectNode -local function find_and_swap_pop(t: { T }, v: T) - local i = table.find(t, v) :: number - local n = #t - t[i] = t[n] - t[n] = nil +export type Node = ReactiveNode | EffectNode | StableNode + +export type CleanupObject = cleanup.CleanupObject +export type Cleanup = cleanup.Cleanup + +-- weak so threads that errored or got cancelled while they had a scope can be collected +local processing_nodes: { [thread]: Node } = setmetatable({}, { __mode = "ks" }) +local deferred_nodes: { Computation } = {} +local pending_eval: { Computation } = {} +local TOTAL_PENDING_EVAL = 0 +local deferred_thread: thread? = nil +local version = 0 +-- increments every time a node runs, so reads can tell which run they happened in +local epoch = 0 + +-- a node's flags hold what kind of node it is in the low bits, and the state it's in above them. the state bits +-- are ordered so most checks are comparisons: below RUNNING is clean, DIRTY and up is dirty or dead. +-- DIRTY and DEAD are never set together + +-- the kind of computation a node is, set when it's created. sources and stable nodes don't have one +local EAGER = 1 +local DEFERRED = 2 +local LAZY = 4 +local ASYNC = 8 -- async is similar to eager, but unlike eager it does not actually update the value. +local KIND = EAGER + DEFERRED + LAZY + ASYNC + +local RUNNING = 16 -- running its effect right now, reading it returns cached_value +local DIRTY = 32 -- has to be recomputed before cached_value can be used +local DEAD = 64 + +-- most nodes never get children or cleanups, so they share this until the first one gets added +local EMPTY_TABLE = table.freeze({}) :: { any } + +-- slot indexes are stored as u16s in buffers, with the first u16 indicating how many slots the current buffer can hold +local EMPTY_BUFFER = buffer.create(2) +local MAX_SLOTS = 65_535 + +@native +local function IS_DIRTY_AND_ALIVE(flags: number): boolean + return flags >= DIRTY and flags < DEAD end -local function flush_cleanups(node: Node) - for _, fn in node.cleanups do - fn() +@native +local function grow_slots(slots: buffer): buffer + local capacity = buffer.readu16(slots, 0) + if capacity == MAX_SLOTS then + logging.error(logging.errors.graph_too_many_edges(MAX_SLOTS)) end - table.clear(node.cleanups) + local grown_capacity = if capacity == 0 then 8 else math.min(math.ceil(capacity * 1.5), MAX_SLOTS) + local grown = buffer.create(grown_capacity * 2 + 2) + buffer.writeu16(grown, 0, grown_capacity) + buffer.copy(grown, 2, slots, 2) + return grown end -local function remove_dependencies(node: Node) - if not node.effect then +@native +local function add_child(parent: Node, node: Node) + local children = parent.children + + if children == EMPTY_TABLE then + children = { node } + parent.children = children + node.child_index = 1 + else + local index = #children + 1 + children[index] = node + node.child_index = index + end +end + +-- swap pops the node out of its parent's children, pointing the child that gets moved into its place at its new index +@native +local function remove_child(parent: Node, node: Node) + local children = parent.children + local index = node.child_index + local last = #children + + if index ~= last then + local moved = children[last] + children[index] = moved + moved.child_index = index + end + + children[last] = nil +end + +local function flush_cleanups(node: Node) + local cleanups = node.cleanups + if not cleanups[1] then return end - for idx, dependency in node.depending_on do - find_and_swap_pop(dependency.dependents, node) + for _, value in cleanups do + cleanup(value) + end + table.clear(cleanups) +end + +@native +local function unlink_dependency(node: Computation, index: number, dependency: SourceNode | ReactiveNode) + local slot = buffer.readu16(node.depending_on_slots, index * 2) + local dependents = dependency.dependents + local last = #dependents + + if slot ~= last then + local dependent_slots = dependency.dependent_slots + local moved = dependents[last] + local moved_slot = buffer.readu16(dependent_slots, last * 2) + + dependents[slot] = moved + buffer.writeu16(dependent_slots, slot * 2, moved_slot) + buffer.writeu16(moved.depending_on_slots, moved_slot * 2, slot) end - table.clear(node.depending_on) + + dependents[last] = nil end -local function bump_version() +@native +local function remove_dependencies_from(node: Computation, index: number) + local depending_on = node.depending_on + + for i = #depending_on, index, -1 do + unlink_dependency(node, i, depending_on[i]) + depending_on[i] = nil + end +end + +@native +local function remove_dependencies(node: Node) + if node.effect then + remove_dependencies_from(node, 1) + end +end + +@native +local function bump_version(): number version += 1 return version end local function get_scope() - return processing_node[coroutine.running()] + return processing_nodes[coroutine.running()] end local function set_scope(node: Node?) - processing_node[coroutine.running()] = node + processing_nodes[coroutine.running()] = node end -local function run_as_unsafe(node: Node?, fn: (U...) -> T..., ...: U...): T... +-- nothing run in a scope returns more than 2 values (e.g. for_keys transforms return the result and a delay), +-- so they're hardcoded instead of passing a vararg pack through +local function run_as_unsafe(node: Node?, fn: (U...) -> (A, B), ...: U...): (A, B) local co = coroutine.running() - local old = processing_node[co] - processing_node[co] = node + local old = processing_nodes[co] + processing_nodes[co] = node local a, b = fn(...) - processing_node[co] = old + processing_nodes[co] = old return a, b end -local function is_similar(a: unknown, b: unknown): boolean - local both_are_tables = type(a) == "table" - and type(b) == "table" - and not table.isfrozen(a) - and not table.isfrozen(b) +-- dev mode runs reactive functions on a fresh thread from no_yield_call, so there's no previous scope to restore. +local function run_on_new_thread(node: Node?, fn: (U...) -> T, ...: U...): T + processing_nodes[coroutine.running()] = node + return fn(...) +end - return if both_are_tables then false else a == b +-- mutable tables are never similar so mutating a table and setting it again pushes an update, +-- frozen tables are compared by reference. checks == first since most updates are changes +@native +local function is_similar(a: unknown, b: unknown): boolean + return a == b and (type(a) ~= "table" or table.isfrozen(a :: {}) or table.isfrozen(b :: {})) end +@native local function push_dependency_to_active_scope(node: SourceNode | ReactiveNode) local scope = get_scope() if not (scope and scope.effect) then return end - assert(scope ~= node, `node tried to add itself as dependency`) + -- already read during this run. if another node read it in between this just adds a duplicate edge, which is harmless + local scope_epoch = scope.epoch + if node.tracked_epoch == scope_epoch then + return + end + node.tracked_epoch = scope_epoch + + if scope == node then + error("node tried to add itself as dependency") + end + + local depending_on = scope.depending_on + local index = scope.tracking_index + 1 + scope.tracking_index = index + + -- nodes usually read the same dependencies in the same order every run, so the edge from the last run can be kept + local existing = depending_on[index] + if existing == node then + return + end + + local dependents = node.dependents + local slot = #dependents + 1 + + local depending_on_slots = scope.depending_on_slots + + if index > buffer.readu16(depending_on_slots, 0) then + depending_on_slots = grow_slots(depending_on_slots) + scope.depending_on_slots = depending_on_slots + end - table.insert(node.dependents, scope) - table.insert(scope.depending_on, node) + local dependent_slots = node.dependent_slots + if slot > buffer.readu16(dependent_slots, 0) then + dependent_slots = grow_slots(dependent_slots) + node.dependent_slots = dependent_slots + end + + if existing then + unlink_dependency(scope, index, existing) + end + + depending_on[index] = node + dependents[slot] = scope + buffer.writeu16(depending_on_slots, index * 2, slot) + buffer.writeu16(dependent_slots, slot * 2, index) end +@native local function node_destroy(node: Node) + -- marked dead so it can't rerun if it's still queued in pending_eval / deferred_nodes + node.flags = bit32.band(node.flags, KIND) + DEAD flush_cleanups(node) remove_dependencies(node) - if node.parent then - find_and_swap_pop(node.parent.children, node) - + local parent = node.parent + if parent then + remove_child(parent, node) node.parent = false end - while node.children[1] do - node_destroy(node.children[1]) + -- destroying a child removes it from children, so this empties it + local children = node.children + while children[1] do + node_destroy(children[1]) end - table.clear(node.children) end +@native local function node_destroy_owned(node: Node) - while node.children[1] do - node_destroy(node.children[1]) + local children = node.children + while children[1] do + node_destroy(children[1]) end - table.clear(node.children) end local function effect_yield(thread: thread) @@ -186,259 +371,365 @@ end local graph = {} -local function graph_run_as(node: Node?, fn: (U...) -> T..., ...: U...): (boolean, T...) - local previous_processing = get_scope() - set_scope(node) - - local is_async_node = (node and node.effect and node.evaluation == "async") - - local yielding_errors = dev_mode and not is_async_node - - local ok, a, b - if yielding_errors then - -- ok, call = reactive_fn_calls.call(fn, effect_err, ...) - ok, a, b = reactive_fn_calls.no_yield_call(run_as_unsafe, effect_err, effect_yield, node, fn, ...) - else - ok, a, b = xpcall(fn, effect_err, ...) +local function graph_run_as(node: Node?, fn: (U...) -> T, ...: U...): (boolean, T) + if dev.enabled and not (node and bit32.band(node.flags, ASYNC) ~= 0) then + return no_yield_call(run_on_new_thread, effect_err, effect_yield, node, fn, ...) end - set_scope(previous_processing) + local co = coroutine.running() + local previous_processing = processing_nodes[co] + processing_nodes[co] = node + + local ok, result = xpcall(fn, effect_err, ...) - return ok, a, b + processing_nodes[co] = previous_processing + return ok, result end -local function graph_defer_node(node: ReactiveNode) - if node.state == "dirty" then +@native +local function graph_defer_node(node: Computation) + local flags = node.flags + -- already queued, or dead + if flags >= DIRTY then return end - node.state = "dirty" + node.flags = flags + DIRTY table.insert(deferred_nodes, node) - if deferred_thread == nil then - deferred_thread = scheduler.defer(function() - assert(graph) - - graph.flush_deferred_nodes() - deferred_thread = nil - end) + if not deferred_thread then + deferred_thread = scheduler.defer(graph.flush_deferred_nodes) end end -local function graph_update_node(node: ReactiveNode): T - local should_reevaluate = #node.depending_on == 0 - for _, dependency in node.depending_on do - -- a dependency was evaluated after this dependency was invalidated - if dependency.last_evaluation > node.last_evaluation then +@native +local function graph_update_node(node: Computation) + local depending_on = node.depending_on + local verified_at = node.verified_at + local should_reevaluate = #depending_on == 0 + + for _, dependency in depending_on do + -- the dependency changed since this node was last up to date + if dependency.last_evaluation > verified_at then should_reevaluate = true break - elseif dependency.state == "clean" then - continue end - -- the dependency is dirty, so we have to reevaluate that dependency - if dependency.state == "dirty" then - graph_update_node(dependency) - if dependency.last_evaluation < node.last_evaluation then - continue + + -- the dependency is dirty, so we have to reevaluate that dependency. one that's mid evaluation + -- (e.g. its effect set a source this node depends on) just keeps its cached value + local dependency_flags = dependency.flags + if dependency_flags >= DIRTY and dependency_flags < DEAD then + graph_update_node(dependency :: ReactiveNode) + + -- the dependency can own this node, rerunning it destroys this node + if node.flags >= DEAD then + return + end + + if dependency.last_evaluation > verified_at then + should_reevaluate = true + break end - should_reevaluate = true - break - end - -- if the dependency is running on the same thread, we have a recursive dependency, otherwise - -- it's fine to just recompute the value and have it invalidate later - if dependency.state == coroutine.running() then - error( - `a recursive dependency has been found, which may result in an infinite loop. this should be unreachable` - ) end end + local kind = bit32.band(node.flags, KIND) + if not should_reevaluate then - node.state = "clean" - return node.cached_value + node.flags = kind + node.verified_at = version + return end - flush_cleanups(node) - node_destroy_owned(node) - remove_dependencies(node) + -- untrack() swaps the effect out while it runs, so it has to be restored if it errored + local effect = node.effect :: types.Effect + + if node.cleanups[1] then + flush_cleanups(node) + end + if node.children[1] then + node_destroy_owned(node) + end + + -- dependencies are kept, and matched against what gets read during this run + epoch += 1 + node.epoch = epoch + node.tracking_index = 0 - node.state = coroutine.running() + local evaluated_at = version + node.flags = kind + RUNNING local previous_result = node.cached_value - local success, res = graph_run_as(node, node.effect, previous_result) - -- we mark it as clean and bump the evaluation value since we don't - -- want to re-run the node even if it errored - node.state = "clean" + local success, res = graph_run_as(node, effect, previous_result) + node.effect = effect + + local flags = node.flags + local destroyed = flags >= DEAD + if destroyed then + -- destroyed by its own effect, anything it read afterwards shouldn't stay subscribed + remove_dependencies(node) + else + -- anything that wasn't read this run isn't a dependency anymore + remove_dependencies_from(node, node.tracking_index + 1) + -- if it got invalidated while running (e.g. it set a source it depends on), changes + -- made during the run still have to count as newer + node.verified_at = if flags >= DIRTY then evaluated_at else version + -- we mark it as clean and bump the evaluation value since we don't + -- want to re-run the node even if it errored + node.flags = kind + end - if success then - push_dependency_to_active_scope(node) + if not success then + error((res :: any).trace) + end - if node.evaluation ~= "eager" and is_similar(previous_result, res) or node.evaluation == "async" then - return node.cached_value + if destroyed or kind == ASYNC then + return + elseif kind == LAZY then + -- only lazy nodes get read by other nodes, so they're the only ones that need to track when their + -- value changed. eager and deferred nodes just keep it as the previous value for their next run + if is_similar(previous_result, res) then + return end node.last_evaluation = bump_version() - node.cached_value = res - - return node.cached_value - else - -- logging.warn(res.trace) - error(res.trace) end + + node.cached_value = res end -local function is_dirty(node: ReactiveNode) - if node.state == "clean" then - return false +-- brings a node up to date without tracking it as a dependency of anything +@native +local function refresh_node(node: Computation): T + if IS_DIRTY_AND_ALIVE(node.flags) then + graph_update_node(node) end - for _, dependency in node.depending_on do - -- if a dependent was evaluated after this node was evaluated, it's dirty - if dependency.effect and dependency.state == "dirty" then - -- make sure the dependency isn't dirty - graph_update_node(dependency :: ReactiveNode) - end + return node.cached_value +end - if dependency.last_evaluation > node.last_evaluation then - return true +@native +local function graph_evaluate_node(node: SourceNode | ReactiveNode): T + local flags = node.flags + + -- sources are always clean + if flags >= RUNNING then + if IS_DIRTY_AND_ALIVE(flags) then + graph_update_node(node :: ReactiveNode) + else + -- dead, or mid evaluation. reading a node while it's evaluating can happen without a + -- recursive dependency (e.g. its effect sets a source something reading it depends on) + return node.cached_value end end - return #node.depending_on == 0 + push_dependency_to_active_scope(node) + return node.cached_value end -local function graph_evaluate_node(node: SourceNode | ReactiveNode): T - if node.effect == false or node.state == "clean" then - push_dependency_to_active_scope(node) - - return node.cached_value - elseif coroutine.running() == node.state then - error(exception.new({ - kind = "fluid", - trace = debug.traceback(logging.errors.graph_recursive_dependency_coeqnost()), - })) - elseif type(node.state) == "thread" then - --todo: should this be allowed? - return node.cached_value - elseif node.state == "dead" then - return node.cached_value - elseif is_dirty(node) then - return graph_update_node(node) - else - node.state = "clean" - return node.cached_value +-- brings a node up to date outside of whatever's reading, reporting errors instead of unwinding the caller +local function evaluate_detached(node: Computation) + local success, err = xpcall(refresh_node, effect_err, node) + + if not success then + -- if a dependency errored, the node never got to run. it has to be marked clean + -- since dirty nodes don't get queued again, otherwise it'd never update again + local flags = node.flags + if IS_DIRTY_AND_ALIVE(flags) then + node.flags = bit32.band(flags, KIND) + end + + logging.report_error((err :: any).trace) end end +@native local function graph_invalidate_loop(node: SourceNode | ReactiveNode) - if node.state == "dirty" then - return - end + for _, dependent in node.dependents do + local flags = dependent.flags + -- already invalidated through another path, or dead + if flags >= DIRTY then + continue + end + + local kind = bit32.band(flags, KIND) + if kind == DEFERRED then + graph_defer_node(dependent) + else + dependent.flags = flags + DIRTY - for _, value in node.dependents do - graph_invalidate_loop(value) - if value.evaluation == "eager" or value.evaluation == "async" then - value.state = "dirty" - table.insert(pending_eval, value) - elseif value.evaluation == "deferred" then - graph_defer_node(value) - elseif value.evaluation == "lazy" then - value.state = "dirty" + if kind ~= LAZY then + TOTAL_PENDING_EVAL += 1 + pending_eval[TOTAL_PENDING_EVAL] = dependent + end + + -- eager and deferred nodes are never read, so only lazy and async nodes can have dependents to invalidate + if kind ~= EAGER then + -- the solver can't refine through the kind local, only reactive nodes are lazy or async + graph_invalidate_loop(dependent :: ReactiveNode) + end end end end +@native local function invalidate(node: ReactiveNode | SourceNode) + -- an invalidation that happens while evaluating (e.g. an effect setting a source) only evaluates what it + -- queued itself, the rest is left to the outer invalidation. otherwise every nested one would evaluate + -- the rest of the queue inside of it, which overflows the stack with enough nodes + local start = TOTAL_PENDING_EVAL + 1 graph_invalidate_loop(node) - - for _, node in pending_eval do - for _, dependent in node.depending_on do - local success, value = graph_run_as(nil, graph_evaluate_node, dependent) - - if not success then - logging.warn(value.trace) + -- nested invalidations push after this and set TOTAL_PENDING_EVAL back before returning, so this stays the end + local finish = TOTAL_PENDING_EVAL + + for idx = start, finish do + local pending = pending_eval[idx] + + -- dependencies get evaluated first, so an erroring dependency doesn't stop the node itself from running. + -- sources are always clean, so they're skipped by the flags check + for _, dependency in pending.depending_on do + if IS_DIRTY_AND_ALIVE(dependency.flags) then + evaluate_detached(dependency :: ReactiveNode) + + -- the dependency can own this node, rerunning it destroys this node + if pending.flags >= DEAD then + break + end end end - local success, value = graph_run_as(nil, graph_evaluate_node, node) - if not success then - logging.warn(value.trace) - end + evaluate_detached(pending) end - table.clear(pending_eval) + + for idx = finish, start, -1 do + pending_eval[idx] = nil + end + + TOTAL_PENDING_EVAL = start - 1 end function graph.flush_deferred_nodes() + deferred_thread = nil + for _, node in deferred_nodes do - graph_evaluate_node(node) + evaluate_detached(node) end table.clear(deferred_nodes) end +@native function graph.create_reactive_node( parent: Node | false, effect: types.Effect | false, - evaluation: "eager" | "deferred" | "lazy" | "async", + evaluation: number, cached_value: T ): ReactiveNode local node: ReactiveNode = { - parent = parent, last_evaluation = bump_version(), - + flags = evaluation + DIRTY, effect = effect, - evaluation = evaluation, - state = "dirty", cached_value = cached_value, + + parent = parent, + child_index = 0, + children = EMPTY_TABLE, + cleanups = EMPTY_TABLE, + + verified_at = 0, depending_on = {}, + depending_on_slots = EMPTY_BUFFER, + epoch = 0, + tracking_index = 0, + dependents = {}, + dependent_slots = EMPTY_BUFFER, + tracked_epoch = 0, + } + + if parent then + add_child(parent, node) + end - children = {}, - cleanups = {}, + if evaluation == DEFERRED then + table.insert(deferred_nodes, node) + end + + return node +end + +@native +function graph.create_effect_node( + parent: Node | false, + effect: types.Effect, + evaluation: number, -- only EAGER or DEFERRED are allowed + cached_value: T +): EffectNode + local node: EffectNode = { + last_evaluation = 0, + flags = evaluation + DIRTY, + effect = effect, + cached_value = cached_value, + + parent = parent, + child_index = 0, + children = EMPTY_TABLE, + cleanups = EMPTY_TABLE, + + verified_at = 0, + depending_on = {}, + depending_on_slots = EMPTY_BUFFER, + epoch = 0, + tracking_index = 0, } if parent then - table.insert(parent.children, node) + add_child(parent, node) end - if evaluation == "deferred" then + if evaluation == DEFERRED then table.insert(deferred_nodes, node) end return node end +@native function graph.create_stable_node(parent: Node | false) local node: StableNode = { - parent = parent, - - effect = false, - state = "clean", last_evaluation = bump_version(), - + flags = 0, + effect = false, cached_value = nil, - children = {}, - cleanups = {}, + parent = parent, + child_index = 0, + children = EMPTY_TABLE, + cleanups = EMPTY_TABLE, } if parent then - table.insert(parent.children, node) + add_child(parent, node) end return node end +@native function graph.create_source_node(value: T): SourceNode local node: SourceNode = { last_evaluation = bump_version(), + flags = 0, effect = false, cached_value = value, - state = "clean", + dependents = {}, + dependent_slots = EMPTY_BUFFER, + tracked_epoch = 0, } return node end +@native function graph.update_node(node: ReactiveNode | SourceNode, value: T) if is_similar(node.cached_value, value) then return @@ -448,11 +739,17 @@ function graph.update_node(node: ReactiveNode | SourceNode, value: T) invalidate(node) end -function graph.push_cleanup(scope: Node, cleanup: () -> ()) - table.insert(scope.cleanups, cleanup) +@native +function graph.push_cleanup(scope: Node, value: Cleanup) + local cleanups = scope.cleanups + if cleanups == EMPTY_TABLE then + scope.cleanups = { value } + else + table.insert(cleanups, value) + end end -function graph.assert_scope(): ReactiveNode | StableNode +function graph.assert_scope(): Node return assert(get_scope(), "reactive scope error thing, TODO error message") end @@ -481,6 +778,13 @@ graph.destroy = node_destroy graph.run_as_unsafe = run_as_unsafe graph.push_dependency = push_dependency_to_active_scope graph.evaluate_node = graph_evaluate_node +graph.refresh_node = refresh_node graph.run_as = graph_run_as - -return graph +graph.evaluation = table.freeze({ + DEFERRED = DEFERRED, + EAGER = EAGER, + ASYNC = ASYNC, + LAZY = LAZY, +}) + +return table.freeze(graph) diff --git a/src/reactive/root.luau b/src/reactive/root.luau index 55123ec..2f8ebb0 100644 --- a/src/reactive/root.luau +++ b/src/reactive/root.luau @@ -3,8 +3,13 @@ local types = require("./types") local refs: { [graph.Node]: true? } = {} +-- the scope only passes 1 value through, so the results get put in a table instead of using a closure to capture them +local function call_packed(fn: (destroy: types.Cleanup) -> ...unknown, destroy: types.Cleanup) + return { fn(destroy) } +end + local function root(fn: (destroy: types.Cleanup) -> T...): (types.Cleanup, T...) - local node = graph.create_stable_node(graph.get_scope()) + local node = graph.create_stable_node(graph.get_scope() or false) -- prevent gc of root node refs[node] = true @@ -17,20 +22,15 @@ local function root(fn: (destroy: types.Cleanup) -> T...): (types.Cleanup, graph.destroy(node) end - local results = {} - - local success, result = graph.run_as(node, function(destroy) - results = { fn(destroy) } - return nil - end, destroy) + local success, results = graph.run_as(node, call_packed, fn, destroy) if not success then destroy() - error(result.trace) + error((results :: any).trace) end -- luau type issue w generic type packs - return destroy, unpack(results) :: any + return destroy, table.unpack(results :: any) end return root diff --git a/src/reactive/source.luau b/src/reactive/source.luau index fb3c55d..6e2d9b2 100644 --- a/src/reactive/source.luau +++ b/src/reactive/source.luau @@ -1,31 +1,23 @@ local graph = require("./graph") local types = require("./types") -local function get_argument_from(...: T): (boolean, T) - if select("#", ...) == 0 then - return false, nil - end - - local first_value = ... - return true, first_value -end +local push_dependency = graph.push_dependency +local update_node = graph.update_node local function source(initial_value: T): types.Source local node = graph.create_source_node(initial_value) -- This uses varargs so we can tell the difference between f(), f(nil), and f(value) return function(...: T): T - local has_value, value = get_argument_from(...) - - if has_value then - -- setting the source node - graph.update_node(node, value) - return value - else + if select("#", ...) == 0 then -- dependency, returning the value - graph.push_dependency(node) + push_dependency(node) return node.cached_value end + + local value = ... + update_node(node, value) + return value end end diff --git a/src/scheduler.luau b/src/scheduler.luau index bf27571..94750f9 100644 --- a/src/scheduler.luau +++ b/src/scheduler.luau @@ -2,7 +2,8 @@ local task = (task or require("@lute/task")) :: typeof(task) type RenderCallback = (delta_time: number) -> () -local cancel = task.cancel or coroutine.close +-- giving this a type because coroutine.close has returns and task.cancel doesn't +local cancel: (thread) -> () = task.cancel or coroutine.close local connections: { RenderCallback } = {} @@ -10,9 +11,25 @@ local scheduler = { connections = connections, } +local free_runner: thread? = nil + +local function run_callback(callback: RenderCallback, delta_time: number) + free_runner = nil + callback(delta_time) + free_runner = coroutine.running() +end + +local function runner_loop(callback: RenderCallback, delta_time: number) + run_callback(callback, delta_time) + + while true do + run_callback(coroutine.yield()) + end +end + function scheduler.step(delta_time: number) for _, callback in connections do - task.spawn(callback, delta_time) + task.spawn(free_runner or coroutine.create(runner_loop), callback, delta_time) end end diff --git a/src/utils/interval.luau b/src/utils/interval.luau index 9e7da21..7e3b7e3 100644 --- a/src/utils/interval.luau +++ b/src/utils/interval.luau @@ -1,7 +1,8 @@ +local dev = require("../dev") local exception = require("./exception") local graph = require("../reactive/graph") local logging = require("../logging") -local reactive_fn_calls = require("./reactive_fn_calls") +local no_yield_call = require("./no_yield_call") local scheduler = require("../scheduler") local function interval_err_handler(err: unknown): exception.Identity @@ -64,10 +65,23 @@ local function interval_yield_handler(thread: thread): exception.Identity }) end +local function silent_interval_yield_handler(): exception.Identity + return exception.new({ + kind = "yielded", + trace = debug.traceback(logging.errors.interval_user_yielded(), 2), + }) +end + local function interval(func: (dt: number) -> T, hz: number?, offset: number?): () -> T local scope = graph.assert_stable_parent() - local ok, res = reactive_fn_calls.no_yield_call(func, interval_err_handler, interval_yield_handler, 0) + local ok, res + + if dev.enabled then + ok, res = no_yield_call(func, interval_err_handler, interval_yield_handler, 0) + else + ok, res = xpcall(func, interval_err_handler, 0) + end if not ok then logging.error(res.trace) @@ -76,24 +90,26 @@ local function interval(func: (dt: number) -> T, hz: number?, offset: number? local node = graph.create_source_node(res) local last_eval = offset and -offset or 0 local last_ok = true + local period = hz and 1 / hz local function on_render(dt: number) - if hz ~= nil then + if period then last_eval += dt - if last_eval <= 1 / hz then + if last_eval <= period then return end dt = last_eval last_eval = 0 end + local ok, res + if not last_ok then - local ok, res = reactive_fn_calls.no_yield_call(func, silent_interval_err_handler, function() - return exception.new({ - kind = "yielded", - trace = debug.traceback(logging.errors.interval_user_yielded(), 2), - }) - end, dt) + if dev.enabled then + ok, res = no_yield_call(func, silent_interval_err_handler, silent_interval_yield_handler, dt) + else + ok, res = xpcall(func, silent_interval_err_handler, dt) + end if ok then last_ok = true @@ -102,7 +118,11 @@ local function interval(func: (dt: number) -> T, hz: number?, offset: number? return end - local ok, res = reactive_fn_calls.no_yield_call(func, interval_err_handler, interval_yield_handler, dt) + if dev.enabled then + ok, res = no_yield_call(func, interval_err_handler, interval_yield_handler, dt) + else + ok, res = xpcall(func, interval_err_handler, dt) + end if ok then graph.update_node(node, res) diff --git a/src/utils/reactive_fn_calls.luau b/src/utils/no_yield_call.luau similarity index 57% rename from src/utils/reactive_fn_calls.luau rename to src/utils/no_yield_call.luau index 410bf92..6c0299c 100644 --- a/src/utils/reactive_fn_calls.luau +++ b/src/utils/no_yield_call.luau @@ -1,9 +1,7 @@ local exception = require("./exception") local scheduler = require("../scheduler") -local reactive_fn_calls = {} - -function reactive_fn_calls.no_yield_call( +local function no_yield_call( func: (T...) -> U..., err_handler: (unknown) -> exception.Identity, yield_handler: (thread) -> exception.Identity, @@ -15,18 +13,10 @@ function reactive_fn_calls.no_yield_call( if coroutine.status(co) == "suspended" then local value = yield_handler(co) scheduler.cancel(co) - return false, value + return false, value :: any end - return ok, a, b, c, d, e -end - -function reactive_fn_calls.call( - fn: (T...) -> U..., - err_handler: (unknown) -> exception.Identity, - ...: T... -): (boolean, U...) - return xpcall(fn, err_handler, ...) + return ok, a, b, c, d, e :: any end -return reactive_fn_calls +return no_yield_call diff --git a/src/utils/switch_delay.luau b/src/utils/switch_delay.luau index f24f151..ec1a653 100644 --- a/src/utils/switch_delay.luau +++ b/src/utils/switch_delay.luau @@ -12,8 +12,26 @@ type SwitchGraph = { delay_by: { [Condition]: number? }, threads: { [Condition]: thread? }, result_values: { [Condition]: Result }, + -- result_values as an array, rebuilt when the node updates instead of on every read + values: { Result }, } +local LAZY = graph.evaluation.LAZY + +local function destroy(p: SwitchGraph, c: Condition) + graph.destroy(p.scopes[c]) + p.scopes[c] = nil + p.active_nodes[c] = nil + p.delay_by[c] = nil + p.threads[c] = nil + p.result_values[c] = nil +end + +local function destroy_delayed(p: SwitchGraph, c: Condition, update_counter: graph.SourceNode) + destroy(p, c) + graph.update_node(update_counter, update_counter.cached_value + 1) +end + local function switch(condition: () -> Key) return function(options: { [Key]: (types.Readable) -> (Result, number?) }): () -> { Result } local parent_node = graph.assert_stable_parent() @@ -25,32 +43,14 @@ local function switch(condition: () -> Key) return options[condition()] end) - local function destroy(p: SwitchGraph, c: Condition) - graph.destroy(p.scopes[c]) - p.scopes[c] = nil - p.active_nodes[c] = nil - p.delay_by[c] = nil - p.threads[c] = nil - p.result_values[c] = nil - end - - local function destroy_delayed(p: SwitchGraph, c: Condition) - destroy(p, c) - graph.update_node(update_counter, update_counter.cached_value + 1) - end - - local function update(p: SwitchGraph) - graph.push_dependency(update_counter) - - local previous_effect = p.previous_effect + local function switch_effect( + p: SwitchGraph, + previous_effect: Condition?, + active_effect: Condition? + ) local scopes = p.scopes local active_nodes = p.active_nodes local result_values = p.result_values - local active_effect = callback() - - if previous_effect == active_effect then - return p - end -- previous effect isn't the same as active effect, so destroy previous effect if previous_effect and not p.threads[previous_effect] and p.scopes[previous_effect] then @@ -59,7 +59,8 @@ local function switch(condition: () -> Key) graph.update_node(p.active_nodes[previous_effect], false) if delay_by then - p.threads[previous_effect] = scheduler.delay(delay_by, destroy_delayed, p, previous_effect) + p.threads[previous_effect] = + scheduler.delay(delay_by, destroy_delayed, p, previous_effect, update_counter) else destroy(p, previous_effect) end @@ -68,7 +69,7 @@ local function switch(condition: () -> Key) p.previous_effect = active_effect if not active_effect then - return p + return end -- first see if an old node was in the process of getting destroyed. @@ -78,7 +79,7 @@ local function switch(condition: () -> Key) scheduler.cancel(thread) p.threads[active_effect] = nil graph.update_node(p.active_nodes[active_effect], true) - return p + return end -- otherwise, create a new node @@ -94,27 +95,42 @@ local function switch(condition: () -> Key) active_nodes[active_effect] = active result_values[active_effect], p.delay_by[active_effect] = graph.run_as_unsafe(node, active_effect, read_active) + end + + local function update(p: SwitchGraph) + graph.push_dependency(update_counter) + + local previous_effect = p.previous_effect + local active_effect = callback() + + if previous_effect ~= active_effect then + switch_effect(p, previous_effect, active_effect) + end + + -- result values can also change from delayed destruction, which bumps update_counter + local values = {} + for _, value in p.result_values do + table.insert(values, value) + end + p.values = values return p end - local reactive = graph.create_reactive_node(parent_node, update, "lazy", { + local reactive = graph.create_reactive_node(parent_node, update, LAZY, { previous_effect = nil, scopes = {}, active_nodes = {}, delay_by = {}, threads = {}, result_values = {}, + values = {}, }) return function() local result: SwitchGraph = graph.evaluate_node(reactive) - - local values = {} - for _, value in result.result_values do - table.insert(values, value) - end - return values + -- a copy, so consumers mutating it don't mutate the actual values + return table.clone(result.values) end end end diff --git a/src/utils/tags.luau b/src/utils/tags.luau index a3d7d69..02a893e 100644 --- a/src/utils/tags.luau +++ b/src/utils/tags.luau @@ -1,11 +1,12 @@ local action = require("../instances/action") -local cleanup = require("../reactive/cleanup") local graph = require("../reactive/graph") +local DEFERRED = graph.evaluation.DEFERRED + local function bind_tag(instance: Instance, tag: string) instance:AddTag(tag) - cleanup(function() + graph.push_cleanup(graph.assert_scope(), function() instance:RemoveTag(tag) end) end @@ -17,10 +18,10 @@ local function tags(tags: { string | () -> string? }): action.Identity bind_tag(instance, tag) continue end - graph.create_reactive_node(graph.assert_stable_parent(), function(): nil + graph.create_effect_node(graph.assert_stable_parent(), function(): nil local current = tag() return if current then bind_tag(instance, current) else nil - end, "deferred", nil) + end, DEFERRED, nil) end end) end diff --git a/tests/hooks/logging.luau b/tests/hooks/logging.luau index 6383adf..757a5c7 100644 --- a/tests/hooks/logging.luau +++ b/tests/hooks/logging.luau @@ -43,6 +43,23 @@ local function set_on_warn(hook: OnWarn?) on_warn_hook = hook end +-- same as on_warn, but for errors fluid reports without unwinding (logging.report_error) +local on_error_hook: OnWarn? + +local original_report_error = logging.report_error +function logging.report_error(...) + if on_error_hook then + on_error_hook(...) + else + original_report_error(...) + end +end + +local function set_on_error(hook: OnWarn?) + on_error_hook = hook +end + return { on_warn = set_on_warn, + on_error = set_on_error, } diff --git a/tests/init.luau b/tests/init.luau index f8b8e8a..dac60fe 100644 --- a/tests/init.luau +++ b/tests/init.luau @@ -13,6 +13,9 @@ function tests.fuzz() end function tests.unit_tests() + -- the yield checks are dev mode behavior + require("@src/").dev() + require("@self/unit_tests/logging.spec") call_tests(require("@self/unit_tests/reactive_graph.spec")) require("@self/unit_tests/scheduler.spec") diff --git a/tests/unit_tests/interval.spec.luau b/tests/unit_tests/interval.spec.luau index 2f07473..9b03cec 100644 --- a/tests/unit_tests/interval.spec.luau +++ b/tests/unit_tests/interval.spec.luau @@ -1,4 +1,5 @@ local TEST, CASE, CHECK = require("@vendor/testkit").test() +local dev = require("@src/dev") local fluid = require("@src/") local hooks = require("@tests/hooks") local task = require("@lute/task") @@ -229,6 +230,21 @@ local function tests() CHECK(did_yield_count == 1) hooks.logging.on_warn(nil) end + + do + CASE("runs on the caller's thread outside dev mode") + local caller = coroutine.running() + local thread + + dev.enabled = false + fluid.interval(function() + thread = coroutine.running() + return 0 + end) + dev.enabled = true + + CHECK(thread == caller) + end end) ) end diff --git a/tests/unit_tests/reactive_graph.spec.luau b/tests/unit_tests/reactive_graph.spec.luau index edb9328..db9fe9e 100644 --- a/tests/unit_tests/reactive_graph.spec.luau +++ b/tests/unit_tests/reactive_graph.spec.luau @@ -1,4 +1,5 @@ local TEST, CASE, CHECK = require("@vendor/testkit").test() +local dev = require("@src/dev") local fluid = require("@src/") local graph = require("../../src/reactive/graph") local hooks = require("@tests/hooks") @@ -21,9 +22,40 @@ local function tests() end end + -- slots are u16s, each one is where the edge back is in the other node's array + local function edges_consistent(node: any): boolean + local dependents = node.dependents + if dependents then + for idx, dependent in dependents do + local slot = buffer.readu16(node.dependent_slots, idx * 2) + if + dependent.depending_on[slot] ~= node + or buffer.readu16(dependent.depending_on_slots, slot * 2) ~= idx + then + return false + end + end + end + + local depending_on = node.depending_on + if depending_on then + for idx, dependency in depending_on do + local slot = buffer.readu16(node.depending_on_slots, idx * 2) + if + dependency.dependents[slot] ~= node + or buffer.readu16(dependency.dependent_slots, slot * 2) ~= idx + then + return false + end + end + end + + return true + end + --[=[ Run garbage collection. We need to do garbage collection tests with this because we're still using Luau GC - + Fusion does scopes to avoid using Luau GC because it's easy for memory leaks to happen. But that's horrific for DX ]=] @@ -54,6 +86,40 @@ local function tests() CHECK(count == 1) end + + do + CASE("cleanup accepts objects") + local calls = {} + local thread = coroutine.create(function() + coroutine.yield() + end) + coroutine.resume(thread) + + -- methods get called with the object as self + local function record(name: string) + return function(_self: any) + table.insert(calls, name) + end + end + + local destroy = fluid.root(function() + fluid.cleanup({ destroy = record("destroy") }) + fluid.cleanup({ disconnect = record("disconnect") }) + fluid.cleanup({ Destroy = record("Destroy") }) + fluid.cleanup({ Disconnect = record("Disconnect") }) + -- same priority as before, destroy wins over Destroy + fluid.cleanup({ destroy = record("priority"), Destroy = record("wrong") }) + fluid.cleanup(function() + table.insert(calls, "function") + end) + fluid.cleanup(thread) + end) + + CHECK(#calls == 0) + destroy() + CHECK(table.concat(calls, ",") == "destroy,disconnect,Destroy,Disconnect,priority,function") + CHECK(coroutine.status(thread) == "dead") + end end) TEST( @@ -286,6 +352,151 @@ local function tests() CHECK(cleaned[2] == 1) end + do + CASE("derive doesn't rerun if nothing changed since its last run") + local first = fluid.source(0) + local second = fluid.source(0) + local gate = fluid.derive(function() + return second() > 100 + end) + + local runs = 0 + local value = fluid.derive(function() + first() + gate() + runs += 1 + return 0 + end) + + value() + first(1) -- reruns, but returns the same value + value() + CHECK(runs == 2) + second(1) -- gate reruns, but doesn't change + value() + CHECK(runs == 2) + end + + do + CASE("keeps dependency on a dirty derive that didn't change") + local first = fluid.source(0) + local condition = fluid.source(1) + local text = fluid.source("a") + + local positive = fluid.derive(function() + return condition() > 0 + end) + local value = fluid.derive(function() + return if positive() then text() else "none" + end) + + local seen + fluid.deferred(function() + first() + seen = value() + end) + + CHECK(seen == "a") + condition(2) -- positive reruns, but stays true + first(1) + step_scheduler() + text("b") + step_scheduler() + CHECK(seen == "b") + end + + do + CASE("node destroyed by its owner rerunning doesn't run again") + local src = fluid.source(0) + local other = fluid.source(0) + local runs = 0 + + local owner: () -> number + owner = fluid.derive(function() + local value = src() + + -- owned by the derive, so the derive rerunning destroys it + fluid.untrack(function() + fluid.deferred(function() + other() + owner() + runs += 1 + end) + return nil + end) + + return value + end) + + owner() + CHECK(runs == 1) + + -- it couldn't depend on owner while owner was running, so this run adds that edge + other(1) + step_scheduler() + CHECK(runs == 2) + + -- updating it reruns owner first, which destroys it and creates a new one + src(1) + step_scheduler() + CHECK(runs == 3) + + -- only the new one is still subscribed + other(2) + step_scheduler() + CHECK(runs == 4) + end + + do + CASE("destroying a node with dependents keeps edges consistent") + local scope = graph.assert_scope() + local src = graph.create_source_node(0) + local other = graph.create_source_node(0) + + local derived = graph.create_reactive_node(scope, function() + graph.evaluate_node(src) + return math.random() + end, graph.evaluation.LAZY, nil) + + local readers: { graph.Computation } = {} + for i = 1, 5 do + readers[i] = graph.create_effect_node(scope, function() + -- the dead node's edge ends up in the middle of depending_on + graph.evaluate_node(other) + graph.evaluate_node(derived) + graph.evaluate_node(src) + return nil + end, graph.evaluation.EAGER, nil) + graph.refresh_node(readers[i]) + end + + local function all_consistent(): boolean + local ok = edges_consistent(src) and edges_consistent(other) and edges_consistent(derived) + for _, reader in readers do + ok = ok and edges_consistent(reader) + end + return ok + end + + CHECK(#derived.dependents == 5) + graph.destroy(derived) + -- the dead node keeps its dependents until they rerun + CHECK(#derived.depending_on == 0) + CHECK(all_consistent()) + + graph.update_node(other, 1) + CHECK(#derived.dependents == 0) + CHECK(all_consistent()) + + local still_reading = false + for _, reader in readers do + if table.find(reader.depending_on, derived :: any) then + still_reading = true + end + end + CHECK(not still_reading) + end + -- do -- CASE("garbage collection") -- -- check that `b` does not allow gc of `a` @@ -362,6 +573,279 @@ local function tests() CHECK(count == 2) end + + do + CASE("destroyed nodes don't rerun") + local src = fluid.source(0) + local child_runs = 0 + + fluid.effect(function() + src() + + fluid.untrack(function() + fluid.effect(function() + src() + child_runs += 1 + end) + return nil + end) + end) + + CHECK(child_runs == 1) + src(1) + CHECK(child_runs == 2) + src(2) + CHECK(child_runs == 3) + end + + do + CASE("error inside untrack doesn't kill the node") + local src = fluid.source(0) + local runs = 0 + + hooks.logging.on_warn(function() end) + hooks.logging.on_error(function() end) + + fluid.effect(function() + local value = src() + runs += 1 + + fluid.untrack(function() + if value == 1 then + error("untracked boom") + end + return nil + end) + end) + + src(1) + src(2) + hooks.logging.on_warn(nil) + hooks.logging.on_error(nil) + + CHECK(runs == 3) + end + + do + CASE("many effects setting sources in one invalidation don't nest") + local src = fluid.source(0) + local reads = 0 + + for _ = 1, 300 do + local own = fluid.source(0) + + fluid.effect(function() + own(src()) + end) + + fluid.effect(function() + own() + reads += 1 + end) + end + + reads = 0 + src(1) + CHECK(reads == 300) + end + + do + CASE("erroring deferred node doesn't stop the flush") + local src = fluid.source(0) + local other_runs = 0 + local reported = 0 + + hooks.logging.on_error(function(text) + if string.find(text, "deferred boom") then + reported += 1 + end + end) + + fluid.deferred(function() + if src() == 1 then + error("deferred boom") + end + end) + + fluid.deferred(function() + src() + other_runs += 1 + end) + + src(1) + local ok = pcall(fluid.provide_scheduler(), 1 / 60) + hooks.logging.on_error(nil) + + CHECK(ok) + CHECK(reported == 1) + CHECK(other_runs == 2) + end + + do + CASE("dependencies are exactly what was read in the last run") + local scope = graph.assert_scope() + local a = graph.create_source_node(0) + local b = graph.create_source_node(0) + local c = graph.create_source_node(0) + local trigger = graph.create_source_node(0) + local reads: { { graph.SourceNode } } = { { a, b }, { b, a }, { a }, {}, { c, a, c } } + local runs = 0 + + local node = graph.create_reactive_node(scope, function() + runs += 1 + graph.evaluate_node(trigger) + for _, dependency in reads[runs] do + graph.evaluate_node(dependency) + end + return nil + end, graph.evaluation.EAGER, nil) + + local function depends_on(expected: { graph.SourceNode }): boolean + local depending_on = node.depending_on + if depending_on[1] ~= trigger or #depending_on ~= #expected + 1 then + return false + end + + for idx, dependency in expected do + if depending_on[idx + 1] ~= dependency then + return false + end + end + + -- and every source only has an edge back if it's still a dependency + for _, source in { a, b, c } do + local edges = 0 + for _, dependent in source.dependents do + if dependent == node then + edges += 1 + end + end + + if edges ~= (if table.find(expected, source) then 1 else 0) then + return false + end + end + + return true + end + + graph.evaluate_node(node) + CHECK(depends_on({ a, b })) + graph.update_node(trigger, 1) + CHECK(depends_on({ b, a })) + graph.update_node(trigger, 2) + CHECK(depends_on({ a })) + -- b was only read in earlier runs, so it shouldn't rerun the node anymore + graph.update_node(b, 1) + CHECK(runs == 3) + graph.update_node(trigger, 3) + CHECK(depends_on({})) + graph.update_node(trigger, 4) + CHECK(depends_on({ c, a })) + end + + do + CASE("reading a dependency multiple times adds one edge") + local scope = graph.assert_scope() + local src = graph.create_source_node(0) + local runs = 0 + + local node = graph.create_reactive_node(scope, function() + graph.evaluate_node(src) + graph.evaluate_node(src) + graph.evaluate_node(src) + runs += 1 + return nil + end, graph.evaluation.EAGER, nil) + graph.evaluate_node(node) + + CHECK(#src.dependents == 1) + CHECK(#node.depending_on == 1) + + graph.update_node(src, 1) + CHECK(runs == 2) + CHECK(#src.dependents == 1) + CHECK(#node.depending_on == 1) + end + + do + CASE("dependency edges stay consistent") + math.randomseed(1) + local scope = graph.assert_scope() + local sources: { graph.SourceNode } = {} + local nodes: { graph.ReactiveNode } = {} + + for i = 1, 8 do + sources[i] = graph.create_source_node(0) + end + + -- lazy nodes reading random sources, then eager ones reading random sources & lazy nodes. + -- duplicate reads are intentional, and what's read changes every run + for i = 1, 16 do + local is_lazy = i <= 4 + nodes[i] = graph.create_reactive_node(scope, function() + for _ = 1, math.random(0, 6) do + if is_lazy or math.random() < 0.6 then + graph.evaluate_node(sources[math.random(1, 8)]) + else + graph.evaluate_node(nodes[math.random(1, 4)]) + end + end + return math.random() + end, if is_lazy then graph.evaluation.LAZY else graph.evaluation.EAGER, nil) + end + + for i = 1, 16 do + graph.evaluate_node(nodes[i]) + end + + for step = 1, 300 do + graph.update_node(sources[math.random(1, 8)], math.random()) + + if step == 150 then + for i = 5, 8 do + graph.destroy(nodes[i]) + end + end + end + + for _, node in sources do + CHECK(edges_consistent(node)) + end + + for _, node in nodes do + CHECK(edges_consistent(node)) + end + + CHECK(#nodes[5].depending_on == 0) + end + + do + CASE("reading more nodes than a u16 can index errors") + local scope = graph.assert_scope() + local sources: { graph.SourceNode } = {} + for i = 1, 65536 do + sources[i] = graph.create_source_node(i) + end + + local reads = 0 + local node = graph.create_reactive_node(scope, function() + for _, source in sources do + graph.evaluate_node(source) + reads += 1 + end + return nil + end, graph.evaluation.EAGER, nil) + + local ok, err = pcall(graph.evaluate_node, node) + CHECK(not ok) + CHECK(string.find(tostring(err), "too_many_edges", 1, true) ~= nil) + -- the last index a u16 can hold still works + CHECK(reads == 65535) + -- and hitting the limit didn't leave a half added edge behind + local destroyed = pcall(graph.destroy, node) + CHECK(destroyed) + end end) ) @@ -747,6 +1231,57 @@ local function tests() CHECK(#data() == 1) CHECK(updates == 2) end + + do + CASE("keeps false values") + local input = source({ a = false } :: { [string]: boolean }) + local creations = 0 + + local output = for_keys(input, function(value) + creations += 1 + return value() + end) + + output() + input({ a = false, b = true }) + output() + CHECK(creations == 2) + end + + do + CASE("nil outputs are left out, false is kept") + local input = source({ 1, 2, 3 }) + + local output = for_keys(input, function(value) + local v = value() + return if v == 2 then nil elseif v == 3 then false else v + end) + + local result = output() + CHECK(#result == 2) + CHECK(result[1] == 1) + CHECK(result[2] == false) + end + + do + CASE("active is false while being removed") + local items = source({ 1 }) + local active: () -> boolean = nil :: any + + local data = for_keys(items, function(_, _, is_active) + active = is_active + return 1, 0 + end) + + data() + CHECK(active() == true) + items({}) + data() + CHECK(active() == false) + items({ 1 }) + data() + CHECK(active() == true) + end end) ) @@ -959,6 +1494,36 @@ local function tests() CHECK(#data() == 1) CHECK(updates == 2) end + + do + CASE("false values") + local items = source({ false, true }) + local created = 0 + + local output = for_values(items, function(value) + created += 1 + return value + end) + + CHECK(#output() == 2) + items({ true, false }) + CHECK(#output() == 2) + CHECK(created == 2) + end + + do + CASE("duplicate values use the last key") + local input = source({ "a", "a" }) + local read_key: () -> number = nil :: any + + local output = for_values(input, function(_, key) + read_key = key + return true + end) + + CHECK(#output() == 1) + CHECK(read_key() == 2) + end end) ) @@ -1214,6 +1779,20 @@ local function tests() CHECK(src() == 2) CHECK(run_count == 2) end + + do + CASE("effects run on the caller's thread outside dev mode") + local caller = coroutine.running() + local thread + + dev.enabled = false + fluid.effect(function() + thread = coroutine.running() + end) + dev.enabled = true + + CHECK(thread == caller) + end end) ) end diff --git a/tests/unit_tests/scheduler.spec.luau b/tests/unit_tests/scheduler.spec.luau index 29236c1..147c3e7 100644 --- a/tests/unit_tests/scheduler.spec.luau +++ b/tests/unit_tests/scheduler.spec.luau @@ -42,6 +42,25 @@ TEST("scheduler stepping", function() step_scheduler(1) CHECK(counted_seconds == 1) end + + do + CASE("yielding callback doesn't stall the others") + table.clear(scheduler.connections) + local ran = 0 + + scheduler.on_render(function() + coroutine.yield() + end) + scheduler.on_render(function() + ran += 1 + end) + + step_scheduler(1) + CHECK(ran == 1) + step_scheduler(1) + CHECK(ran == 2) + table.clear(scheduler.connections) + end end) TEST( diff --git a/types/globals.d.luau b/types/globals.d.luau deleted file mode 100644 index ac5774c..0000000 --- a/types/globals.d.luau +++ /dev/null @@ -1,3 +0,0 @@ -declare _G: { - __DEV__: boolean? -} \ No newline at end of file diff --git a/vendor/testkit.luau b/vendor/testkit.luau index 56d7c66..f52fbce 100644 --- a/vendor/testkit.luau +++ b/vendor/testkit.luau @@ -66,6 +66,9 @@ local function convert_units(unit: string, value: number): (number, string) } local order = 0 + -- scaled without the sign, a negative value (e.g. memory going down because the gc ran) never gets above 1 + local sign = if value < 0 then -1 else 1 + value = math.abs(value) while value >= 1000 do order += 1 @@ -85,7 +88,7 @@ local function convert_units(unit: string, value: number): (number, string) value = math.floor(value * 1e2) / 1e2 end - return value, prefix_colors[order](prefixes[order] .. unit) + return value * sign, prefix_colors[order](prefixes[order] .. unit) end local WALL = color.white("│") @@ -471,4 +474,4 @@ return table.freeze({ print = print2, deq = deep_eq, color = color, -}) \ No newline at end of file +}) diff --git a/wally.toml b/wally.toml index 1f486da..a28c817 100644 --- a/wally.toml +++ b/wally.toml @@ -6,6 +6,7 @@ license = "MIT" realm = "shared" exclude = [ + "bench", ".github", ".lune", ".vscode",