Injection in depth
Base and generic classes
A plain C# class is injected at the end of its most derived constructor. A subclass in an assembly that doesn't reference Selvage is injected at the end of the constructor of its nearest base class that does. The members an abstract base class declares are injected too.
A generic class is a context like any other: each closed type, such as Inventory<Sword>, has its
own members. A member whose type is a type parameter needs the where T : class constraint (refer to
SLV0107).
The Validation tab validates every closed type your code names. A type closed at runtime from a Type
value isn't validated.
When you exit Play mode
When you exit Play mode, Selvage releases what the contexts created in Play mode still hold, and ends the objects it created for them. The following contexts outlive Play mode, and are handled as follows:
- The static members of a class: they're released, except the
EditModeones, which keep their dependency. The others are injected again the next time you enter Play mode. - A ScriptableObject saved in the project and first injected in Play mode: its members are released, as for a context created in Play mode.
When scripts reload
Before scripts reload in the Editor, Selvage releases every context, and ends the objects it created for them. Each
member returns to its default, so after the reload no member holds a dependency Selvage no longer tracks. A component
or ScriptableObject that declares OnDisable is released when its OnDisable ends, so the
method can still use its members.
After the reload, Selvage injects every member again: a ScriptableObject at the end of its OnEnable,
and a component whose Awake had already run before its OnEnable, because Unity doesn't call
Awake again. In Edit mode, these are the components Unity runs there, such as the ones marked
[ExecuteAlways]. A static member is injected again when its class is first used.
What your code injected, such as a Manual member, stays at its default
until your code injects it again, like any other state a script reload ends. To have it injected after every reload,
inject it from OnEnable, which Unity calls again after the reload on every ScriptableObject and on the
components it runs.
Dependency cycles
A dependency cycle is a loop of members: A has a member of type B, and
B has a member of type A. Selvage closes the loop when it comes back to an object it's
still injecting, such as a Shared instance: that object is given as it is, and its members finish injecting
afterwards.
A cycle that never comes back to such an object, such as two classes that each create a new instance of the other
with the Separate lifetime, would never end. Selvage stops it with an error that names the cycle, such as
Dependency cycle: A.b › B.a › A, and the member fails. The Validation tab of the Dependencies
window reports such a cycle on each of its members, and on each member that leads into it, when the classes are
known before you enter Play mode. To fix the cycle, make one of the classes Shared, or make one of the members
Manual. Two Shared objects that hold each other keep each other
alive: to let them end, make one of the members Weak.
When required Async members wait for each other's contexts in a loop, the contexts become ready
together, once everything they wait for outside the loop is ready.
Types from precompiled DLLs
Selvage doesn't process precompiled DLLs, so an object whose class comes from one isn't injected or released on
its own. To inject it, call Manual.Inject(obj) after you create it. To return its members to their
defaults, call Manual.Release(obj). Under IL2CPP, these members need the [Preserve]
attribute or a link.xml entry.
A class you write that derives from a class of a precompiled DLL is processed, and the members of its base class are injected too.
Monitor dependencies
To log dependencies or find a leak, use the events that Injector and Context raise:
| Event | Raised when |
|---|---|
Injector.Created | A provider creates a dependency. |
Injector.FirstInjected | A dependency that no member held is injected. |
Injector.LastReleased | The last member that holds a dependency releases it. |
Injector.TornDown | Selvage ends a dependency it created. |
Context.Injected | A context's members are injected, automatically or with Manual.Inject. It passes an operation that completes when the context is ready. |
Context.Released | A context is released. |
A dependency a provider creates raises the four Injector events in the order of the table. A
dependency a provider finds, such as a scene component, raises only FirstInjected and
LastReleased. Every event is raised on the main thread. A handler that throws an exception is logged,
and the other handlers still run.