Lifetimes
Lifetime types
Every object you provide has a lifetime. The lifetime decides how many objects members receive, and what happens to an object when its member releases it:
| Lifetime | Each member receives | When the member releases it |
|---|---|---|
| Permanent | The same object as every other member. | Nothing: the object stays until play stops, even when no member holds it. One made in Edit mode stays until scripts reload. |
| Shared (default) | The same object as every other member. | The object ends one frame after no member holds it, so a member of a newly loaded scene can still take it over. |
| Separate | Its own object. | The object ends. |
| Pooled | Its own object, borrowed from a pool. | The object returns to the pool, to be lent again. |
When an object ends, Selvage destroys it if it's a Unity object, and disposes it if it implements
IDisposable. Selvage only ends the objects it created, copies included. It never ends an original scene
component or asset, or an object you add to a registry.
A Shared object doesn't last for the whole application: after it ends, the next member that needs one receives a new one, and the state of the old one is lost. Use Permanent for an object that holds state for the whole session, such as a score or the player's settings. A Permanent object made from a registry factory also ends when you remove its entry. Selvage never ends a scene component, so Permanent gives a scene component the same as Shared.
Set a lifetime
Where you set the lifetime depends on what you provide:
| Provided object | Lifetime |
|---|---|
[Provide] class | [Provide(Lifetime.Pooled)] |
| Registry entry | Add(..., Lifetime.Pooled) |
| Asset | The Lifetime property of its Provide Definition. |
| Scene component | The Lifetime property of a Provide Tuning component on its GameObject. |
To make an object for each member, Selvage creates your class with new, calls the function you added
to a registry, copies a Unity object with Instantiate, or calls Clone() on an object that
implements ICloneable. A Separate object is made each time its member is injected or reinjected.
A member holds one Separate object at a time, and Manual.Reinject replaces it. To hold several, create several
instances of a small class whose only member is that one: each instance receives its own object, which ends when the
instance is released.
A copy made with Instantiate holds what Unity serializes, as with any Instantiate, and a
copy of a scene component duplicates its whole GameObject beside the original. A copy's own members are injected
again, never copied. A member of a script on the same GameObject as the component receives the component itself,
whatever its lifetime.
Members that receive the same Shared [Provide] class, registry entry, asset or scene component share
one object. To give some members their own Shared object of a [Provide] class, add a second
[Preference] that matches them: each preference on the class has its own object. For more information, refer to
Choose between several candidates.
Pools
A pool grows as needed, so a member never misses an object because of its pool. A pool of a scene component holds
copies of it, and never lends the original. A pooled GameObject is inactive while it waits in the pool, and active
again when it's lent, so its OnDisable and OnEnable methods run. Selvage injects a lent
object again before the member receives it.
To reset an object when it returns to the pool, implement IResettable. Selvage calls
TryReset when the member releases the object, while the object's own dependencies are still there. If
TryReset returns false or throws an exception, Selvage ends the object instead of reusing
it, and logs the exception:
[Provide(Lifetime.Pooled)]
public sealed class Projectile : IResettable
{
int hits;
public bool TryReset()
{
hits = 0;
return true; // return false to end the object instead of reusing it
}
}
A member borrows an object when it's injected, and gives it back when it's released or its context is destroyed.
With the Manual option, a script borrows an object only while it
needs one:
[Inject(Manual = true)] Projectile projectile;
void Fire() => Manual.Inject(this, nameof(projectile)); // borrows one from the pool
void OnHit() => Manual.Release(this, nameof(projectile)); // TryReset, then back to the pool
A pool belongs to one [Provide] class, registry entry, asset or scene object, and empties when that
source changes, such as when you edit its Provide Definition or remove its registry entry. Objects waiting in a pool
are destroyed when you enter or exit Play mode, and before scripts reload. Objects Selvage creates in Edit mode are never saved into your
scenes.