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

package/README.md

@@ -27,6 +27,7 @@ bun install
 bun run build          # builds every package in dependency order
 bun run test           # build + transformer tests + runtime specs
 bun run lint
+bun run test:place     # the in-place suite in Roblox Studio (tests/place); needs Studio, Rojo and Lune
 ```
 
 ### Packages
@@ -64,3 +65,8 @@ Two suites, both run by `bun run test`:
 
 Specs live in [`packages/specs`](packages/specs) and are compiled by `rbxtsc` like any other
 Flamework consumer, so they exercise the transformer and the runtime together.
+
+A third suite runs against the real engine and is left out of `bun run test`: the
+[test place](tests/place/README.md), a small game linked to the packages' builds, whose
+`@flamework-experimental/testing` sections `bun run test:place` runs in Roblox Studio, both realms,
+under four Rojo projects (see [Testing in Roblox Studio](docs/testing/studio.md)).

package/flamework.build

@@ -1,15 +1,15 @@
 {
 	"version": 1,
-	"flameworkVersion": "2.0.0-alpha.1",
+	"flameworkVersion": "2.0.0-alpha.3",
 	"identifiers": {
 		"@flamework-experimental/core:out/module/module@Module": "$:module/module@Module",
 		"@flamework-experimental/core:out/lifecycle/lifecyclePlugin@LifecycleProvider": "$:lifecycle/lifecyclePlugin@LifecycleProvider",
 		"@flamework-experimental/core:out/lifecycle/lifecyclePlugin@LifecyclePluginOptions": "$:lifecycle/lifecyclePlugin@LifecyclePluginOptions",
-		"@flamework-experimental/core:out/lifecycle/lifecycleInterfaces@OnInit": "$:lifecycle/lifecycleInterfaces@OnInit",
-		"@flamework-experimental/core:out/lifecycle/lifecycleInterfaces@OnStart": "$:lifecycle/lifecycleInterfaces@OnStart",
 		"@flamework-experimental/core:out/lifecycle/lifecycleInterfaces@OnTick": "$:lifecycle/lifecycleInterfaces@OnTick",
 		"@flamework-experimental/core:out/lifecycle/lifecycleInterfaces@OnRender": "$:lifecycle/lifecycleInterfaces@OnRender",
 		"@flamework-experimental/core:out/lifecycle/lifecycleInterfaces@OnPhysics": "$:lifecycle/lifecycleInterfaces@OnPhysics",
+		"@flamework-experimental/core:out/lifecycle/lifecycleInterfaces@OnInit": "$:lifecycle/lifecycleInterfaces@OnInit",
+		"@flamework-experimental/core:out/lifecycle/lifecycleInterfaces@OnStart": "$:lifecycle/lifecycleInterfaces@OnStart",
 		"@flamework-experimental/core:out/lifecycle/lifecycleInterfaces@OnExtinguished": "$:lifecycle/lifecycleInterfaces@OnExtinguished"
 	},
 	"idGenerationMode": "full",

package/out/flamework.luau

@@ -1,6 +1,7 @@
 -- Compiled with roblox-ts v3.0.0
 local TS = _G[script]
 local Reflect = TS.import(script, script.Parent, "reflect").Reflect
+local getClassImplements = TS.import(script, script.Parent, "utility", "getClassImplements").getClassImplements
 local ModuleBuilder = TS.import(script, script.Parent, "module", "moduleBuilder").ModuleBuilder
 local PluginDefinition = TS.import(script, script.Parent, "plugin", "pluginDefinition").PluginDefinition
 local LifecyclePlugin = TS.import(script, script.Parent, "lifecycle", "lifecyclePlugin").LifecyclePlugin
@@ -55,6 +56,13 @@ do
 	_container.isScopeActive = isScopeActive
 	--* @hidden 
 	local function _implements(object, id)
+		-- A table -- an instance, a class -- through the list kept per class.
+		local _object = object
+		if type(_object) == "table" then
+			local _exp = getClassImplements(object)
+			local _id = id
+			return table.find(_exp, _id) ~= nil
+		end
 		local _exp = Reflect.getMetadatas(object, "flamework:implements")
 		-- ▼ ReadonlyArray.some ▼
 		local _result = false

package/out/lifecycle/lifecyclePlugin.d.ts

@@ -29,10 +29,35 @@ export declare class LifecycleProvider {
     onPhysics: Set<OnPhysics>;
     onRender: Set<OnRender>;
     onExtinguished: Set<OnExtinguished>;
+    private tickListeners;
+    private physicsListeners;
+    private renderListeners;
     private identifiers;
     private moduleConnections;
     private lateProviders;
+    /** Late providers resolved since the last turn began, in the order they were resolved: the next turn's. */
+    private lateQueue;
+    /** Whether a turn is deferred that takes whatever joins `lateQueue`. */
+    private hasLateTurn;
+    /** The turns still running `onInit`, by their thread, to the providers each walks. */
+    private lateTurns;
+    /** The provider whose `onInit` each turn is running, by the turn's thread. */
+    private lateTurnInits;
+    /** Late providers whose turn came while the module was still igniting, for `start` to schedule again. */
+    private heldLateProviders;
+    /** What each provider's constructor was given, until its `onInit` has waited for theirs. */
+    private initDependencies;
+    /**
+     * What joined `onExtinguished` once `extinguished` had begun -- a lazy provider resolved for the
+     * first time by a handler, or by an extinguished hook after this one -- and has not been told
+     * yet. Nothing else can join then: `listen` and `createClassInstance` refuse a module that is
+     * extinguishing.
+     */
+    private untold;
+    /** Set as `extinguished` begins its walk, for `untold`; not whether the module has begun to extinguish. */
+    private isExtinguishing;
     private hasStarted;
+    private module?;
     private isProfiling;
     constructor(options: LifecyclePluginOptions);
     private getIdentifier;
@@ -50,25 +75,161 @@ export declare class LifecycleProvider {
      * next frame look it up again.
      */
     private forget;
-    private profile;
+    private observeFrameEvent;
+    /**
+     * A provider on a per-frame event does not tick before the pending `onInit`s of what its
+     * constructor took have finished, as its `onStart` does not start before them: during ignition
+     * the ignition waits for them (see `postIgnite`), and afterwards one without an `onInit` or
+     * `onStart` of its own gets a turn for it, which keeps it out of the per-frame events until then.
+     */
+    private addFrameProvider;
+    /**
+     * Calls a per-frame event's method on every listener attached to it, each on a recycled thread.
+     *
+     * Walked in place (see `FrameListeners`): one attached during the walk gets its first call on the
+     * next frame, and one detached before its turn is passed over. A late provider still waiting on
+     * its `onInit` is passed over too, as an eager provider does not tick before every `onInit` has
+     * run; with none, nothing is looked up.
+     *
+     * Nothing once the module has begun to extinguish, and the walk stops when a callback begins it:
+     * that callback returns here as soon as a later step of the extinguish yields, and by then
+     * everything may have been told `onExtinguished` while still in the sets, which only `release`
+     * empties. Checked once before the walk, and then only when an extinguish has begun somewhere
+     * since (`extinguishesBegun`), so that a frame costs no call per listener.
+     *
+     * The callback is read off the listener and called with it as `self`, and its arguments are
+     * handed to the thread rather than closed over, so that a frame creates nothing per listener.
+     */
+    private walkFrame;
     /**
      * Runs `onInit` synchronously, waiting on a returned Promise, so that initialisation happens in
      * dependency order and is complete before anything starts.
      */
     private runInit;
+    /**
+     * Calls `onInit` on a thread of its own, waiting for it if it yields, and hands back what it
+     * returned or raises what it raised.
+     *
+     * Its own so that the memory category profiling files it under stays on it: a category belongs
+     * to the thread it is set on and cannot be read back to be restored, so one set on the caller's
+     * -- the thread that called `ignite()` -- outlived the call. An `onInit` that raised left the
+     * provider's category there, and one that returned reset the caller's own to the default. The
+     * same thread whether profiling or not, so that Studio and a live server run `onInit` alike.
+     */
+    private callInit;
+    /**
+     * Whether the module has begun to extinguish: from the first line of `extinguish()`. Not from
+     * this plugin's `extinguished` hook, which runs after the importers have gone down and the hooks
+     * ahead of it have run -- any of which may yield, and let a late provider start, the providers
+     * start or the frame loops tick against a module that is on its way out.
+     */
+    private hasBegunExtinguishing;
     private runStart;
     /**
      * A provider constructed after ignition (a lazy one) still gets `onInit` and `onStart`, in that
      * order, once every one of its interfaces has been attached. Instances attached late through
      * `listen` or `createClassInstance` do not; they are owned by whoever created them.
+     *
+     * Until its `onInit` has finished it stays in `lateProviders`, which keeps it out of the
+     * per-frame events, as an eager provider is kept out of them until every `onInit` has run: it
+     * is attached to them at once, and used to tick before it was initialised.
      */
     private scheduleLateProvider;
+    /**
+     * Queues a late provider for the next turn, which one deferred thread takes for everything queued
+     * by then, the way `postIgnite` and `start` take the eager providers: every `onInit` in the order
+     * the providers were resolved -- a dependency, constructed as a constructor parameter, before
+     * what needs it -- each finished before the next begins, then every `onStart`. A thread per
+     * provider ran the next one's `onInit` as soon as the one before yielded, and started it before
+     * its dependency had finished initialising.
+     *
+     * One that an `onInit` of a running turn resolves joins that turn, as one an eager `onInit`
+     * resolves joins ignition's. One resolved anywhere else once a turn has begun gets the next turn
+     * and does not wait for that one's `onInit`s: a single turn for everything held it back behind
+     * an `onInit` it had nothing to do with that yielded -- for good, when that `onInit` waited for it.
+     * It waits only for the `onInit`s of what its constructor took, when those are still running in
+     * a turn of their own (see `awaitDependencies`).
+     */
+    private deferLateProvider;
+    /**
+     * The thread of the turn whose `onInit` the running thread is part of, if any: the `onInit`'s
+     * own thread, which `callInit` records the turn waiting on; one it resumed and has not got back
+     * from -- a thread it spawned, an `async` body before its first yield, a Promise's executor --
+     * which leaves the turn's thread `normal`; or, while the turn waits on the Promise an `onInit`
+     * returned, a thread doing Promise work (see `runsPromiseWork`): the `async` body once it has
+     * yielded, a deferred executor, an `andThen` callback, whose threads nothing records.
+     */
+    private findRunningTurn;
+    /**
+     * Whether a late provider's `onInit` can only run once the running thread is done with the turn
+     * it is part of: the turn that initialises the provider is that turn, and is running the provider's
+     * own `onInit` or one ahead of it. An `onInit` of that turn that ignites a module importing this
+     * one, whose eager provider takes the provider -- resolving it for the first time there, which
+     * has it join the turn -- holds up the very `onInit` the eager one would wait for.
+     *
+     * Only where the running thread is known to be part of the turn: the `onInit`'s own thread, or
+     * one it resumed and has not got back from. Not merely because the turn waits on a Promise and
+     * the running thread does Promise work, the guess `findRunningTurn` makes to join a turn: any
+     * Promise's thread passes it, and an ignition started from an unrelated Promise's work -- a
+     * profile load's `andThen`, an `async` handler -- then went ahead of the very `onInit` it takes.
+     * Nor for what that guess joined to the turn from the running thread: a lazy provider the
+     * ignition resolved for the first time while another's `async` `onInit` was loading joined that
+     * turn, and its dependent went ahead of its `onInit`. Where the guess is all there is, the wait
+     * goes on, and warns if it lasts (see `mayWaitForRunningThread`).
+     */
+    private initWaitsForRunningThread;
+    /**
+     * Whether a late provider's `onInit` may be waiting for the running thread after all, where
+     * `initWaitsForRunningThread` cannot tell: the turn that initialises it waits on the Promise an
+     * `onInit` returned, and the running thread does Promise work, which may be that Promise's -- an
+     * `async` `onInit` that ignites, after an `await`, a module taking what its turn initialises.
+     */
+    private mayWaitForRunningThread;
+    /**
+     * Waits until no provider a provider's constructor took has an `onInit` still to finish, as an
+     * eager provider's `onInit` comes after the eager providers' it takes. Run before the `onInit` of
+     * a late provider in its turn, and of an eager one during ignition -- or, for one without an
+     * `onInit`, before its `onStart` and per-frame events, which saw the same. A late provider resolved in a
+     * turn of its own, or a lazy provider of an import that an eager provider's constructor resolved
+     * for the first time -- which the import's plugin initialises on a turn of its own -- had the
+     * provider taking it initialised, and started, against a dependency not yet initialised.
+     * Resolved together, a dependency comes first in the same turn, so this finds nothing to wait for.
+     *
+     * Polled, since a dependency's `onInit` ends in several ways -- it finishes, it raises, its turn
+     * drops it as the module extinguishes -- and a wait nothing ended would hold this turn, or the
+     * ignition, for good. Does not wait for one whose `onInit` waits for the running thread (see
+     * `initWaitsForRunningThread`), which would never end; one that may, as far as can be told, is
+     * waited for, and warned about once the wait has lasted `SELF_WAIT_WARNING` seconds.
+     *
+     * Answers whether the provider's `onInit` may run: not once its own module has begun to
+     * extinguish, nor once the module of a dependency it waited for has, which dropped that
+     * dependency uninitialised or is releasing it. A late provider's module goes down then too, as
+     * an importer of that module; an igniting module is no importer yet, so its ignition fails.
+     */
+    private awaitDependencies;
+    private runLateProviders;
+    /**
+     * Records what a provider's constructor took, whose pending `onInit`s its own `onInit` waits
+     * for -- or its `onStart` and per-frame events, when it has no `onInit` -- in its turn, or
+     * during ignition (see `awaitDependencies`). Answers whether it took anything.
+     */
+    private recordDependencies;
     addInit(object: OnInit, context: InterfaceContext): void;
     removeInit(object: OnInit): void;
     addStart(object: OnStart, context: InterfaceContext): void;
     removeStart(object: OnStart): void;
     postIgnite(module: Module): void;
+    /**
+     * Starts the providers, then connects the per-frame events, once ignition has completed.
+     *
+     * Not at `postIgnite`, where `onStart` ran while the module was still igniting: `isIgnited()`
+     * answered false, `extinguish()` raised, a module importing this one could not ignite, the
+     * hooks of plugins after this one had not run, and ignition could still fail -- an import
+     * extinguished while an `onInit` yielded had the providers started against it first.
+     */
+    start(module: Module): void;
     extinguished(module: Module): void;
+    private tellExtinguished;
 }
 /**
  * Creates a lifecycle plugin with the specified options.