Technical Q&A
Threading
Can I inject from another thread?
No. Injection runs on the main thread, without locks. In the Editor and in development builds, an assertion reports a call from another thread.
What happens when a constructor runs on another thread?
The object waits, and Selvage injects it on the main thread, at the next callback of any of your scripts there.
Can a provider work in the background?
Yes, in ProvideAsync. Selvage resumes on the main thread when the work completes.
Performance
How long does an injection take?
About 2 µs for a plain C# object with one member, and 4 µs with three members, in an IL2CPP release build on a Windows desktop computer, against 3.6 µs and 6.4 µs for Zenject and 1 µs and 1.7 µs for VContainer in the same test. With Mono, Selvage and Zenject both take about 5.5 µs. VContainer records nothing about an object once it's built. Selvage records what each object holds, so a shared dependency ends at its last release, and one member can be reinjected or released on its own.
Injection is slower in the Editor than in a build. In both, Selvage assigns members with code that an IL post-processor adds when Unity compiles your scripts, so injection uses no reflection. For more information, refer to What does Selvage add to my code?
Does injection allocate memory?
A synchronous injection allocates nothing per member, and one record per context. The first injection of a member finds its providers and caches them.
Does a long provider list slow injection down?
No. Selvage caches the providers that serve each member, and asks only those.
Can I call Manual.Reinject every frame?
Yes, but each call asks the providers again. To follow changes, use Reactive instead, which
reinjects only when a provider announces a change.
Weaving
What does Selvage add to my code?
When Unity compiles your scripts, Selvage adds the following through an ILPostProcessor. This is
called weaving:
- A call at the end of
Awake,OnEnable, constructors and static constructors that injects the object. - A call at the start of
AwakeandOnEnablethat injects the objects created while Unity created this one, as described in When Selvage injects members. - A call that releases the object at the end of
OnDestroy,DisposeorDisposeAsync. - Direct assignments to its members, without reflection.
- In every coroutine and
asyncmethod, the code that carries local blocks acrossyieldandawait.
The Editor and builds run the same code.
Does Selvage weave generic classes?
Yes. Constrain the type parameter to a class. For more information, refer to SLV0107.
What happens if weaving fails?
The assembly, or the one class that failed, stays as compiled, and the Console window displays a warning that starts
with Selvage: automatic injection is off. Its members aren't injected automatically, but
Manual.Inject still injects them, through reflection.
IL2CPP and AOT
Is Selvage safe to use with IL2CPP?
Yes. The code Selvage adds needs no link.xml entry. A member Selvage reaches through reflection fails the IL2CPP
build until you add the [Preserve] attribute or a link.xml entry. These are the members of
classes from precompiled DLLs. A generic type closed at runtime from a Type value, such as one read from
data, can't be detected in advance, so make sure IL2CPP compiles it.
Domain reload
Does Selvage work with domain reload disabled?
Yes. Selvage resets its state when you enter Play mode, and reinjects static members and the objects Unity doesn't recreate. Dependencies injected in Edit mode persist. Other dependencies are released when you exit Play mode.
Platforms
Which platforms does Selvage support?
Every Unity 6 build target. Selvage starts no threads, so WebGL needs no special handling.
Testing
How is Selvage tested?
Selvage has over 1,800 NUnit tests in Edit mode and Play mode, including tests for allocations, weaving, cross-assembly injection, release and teardown.
How do I run Selvage's tests?
Add SELVAGE_TESTS to the scripting define symbols, then run the tests from the Test Runner window. To add it,
perform the following steps:
- Go to Edit > Project Settings > Player.
- Select the tab of the platform the Editor targets, then expand Other Settings.
- Under Script Compilation, add
SELVAGE_TESTSto Scripting Define Symbols, then select Apply.
Without the symbol, Selvage's tests don't compile and the Test Runner window doesn't list them. The tests also need the Test Framework package, and the Zenject and VContainer tests need their container in the project.