Class RealmRegistry
The engine's realms: how many it can host and which are registered. Reached through Realms.
public sealed class RealmRegistry
- Inheritance
-
RealmRegistry
- Inherited Members
Remarks
Realms are registered before InitializeArchetypes, after ConfigureRealms(int) has sized the table: the spatial rebuild
at open needs every realm's grid. Registering at run time (instances, houses) lands with the realm lifecycle work.
Properties
Counts
How many registered realms are in each run state this tick, and how many run at a divisor (Realms D6). Before
InitializeArchetypes, all zero.
public RealmStateCounts Counts { get; }
Property Value
MaxRealms
The configured realm count: valid ids are [0, MaxRealms).
public int MaxRealms { get; }
Property Value
Methods
CanRegister(RealmId)
Whether Register(RealmId, RealmConfig) would accept id on the running engine now: in range, not realm 0, not registered nor closing, and —
for an id removed this session — its removal made durable by a checkpoint (RLM-06). Any thread; false before InitializeArchetypes.
public bool CanRegister(RealmId id)
Parameters
idRealmId
Returns
Remarks
A pool of instance ids (dungeons, houses) asks this to pick a free one. A removed id becomes free at the end of the first checkpoint that starts after its removal: within CheckpointIntervalMs, or sooner after ForceCheckpoint().
DestroyContents(RealmId, Transaction)
Destroys every entity in realm id through tx, on the ordinary destroy path. Returns how many. Commit the
transaction; the next fence frees the realm's clusters (and removes a Closing realm once nothing is left).
public int DestroyContents(RealmId id, Transaction tx)
Parameters
idRealmIdtxTransaction
Returns
GenerationOf(RealmId)
Which incarnation of id id this is: 0 for one registered for the first time, one more each time a retired id is registered again.
public int GenerationOf(RealmId id)
Parameters
idRealmIdA registered realm.
Returns
- int
The catalog generation, or 0 for a realm this database has no catalog row for (realm 0 of a single-world database).
Remarks
A realm's identity is the pair (id, generation), not the id (12-realms § 1.1): ids are reused once a realm is retired, so an application
that caches or compares by id alone can mistake a reused id for the realm it replaced. This is the second half, and it is the same number the
REALM block puts on the wire, so a server and its clients agree about which incarnation they are talking about.
It advances while the server runs: an id unregistered, emptied and removed is registrable again once a checkpoint has made the removal durable, at the next generation (RLM-06, see Generation). A cached id with an old generation names a realm that no longer exists.
IsRegistered(RealmId)
True when id is registered (pending registrations count before InitializeArchetypes).
public bool IsRegistered(RealmId id)
Parameters
idRealmId
Returns
Observe(RealmId)
Pins realm id active — observed, simulated at full rate — from the next tick on, until the returned handle is disposed. For an
application with no session in the realm (a headless server, a benchmark, a test); sessions observe through replication.
public RealmObserver Observe(RealmId id)
Parameters
idRealmId
Returns
Exceptions
- InvalidOperationException
Before
InitializeArchetypes, oridis not registered.
Register(RealmId, RealmConfig)
Registers realm id. Refused when the id is out of range or already registered, or the config is invalid.
public void Register(RealmId id, RealmConfig config)
Parameters
idRealmIdconfigRealmConfig
Exceptions
- InvalidOperationException
After
InitializeArchetypes(run-time registration is not supported yet), or a duplicate.
StateOf(RealmId)
What realm id is doing this tick, as its policy decided at tick start.
public RealmRunState StateOf(RealmId id)
Parameters
idRealmId
Returns
Remarks
A realm Unregister has closed reads Closing at once: entries are refused from the call on. Its policy state — what dispatch reads — follows at the next tick start (RLM-03).
Unregister(RealmId)
Unregisters realm id on a running engine (Realms D5): it is Closing from now on — no entity may
enter it — and is removed at the first fence that finds it empty. Empty it with DestroyContents(RealmId, Transaction). Its id may be registered again, at the
next generation, once a checkpoint that started after the removal has completed (CanRegister(RealmId), RLM-06). The primary realm cannot be
unregistered.
public void Unregister(RealmId id)
Parameters
idRealmId
Wake(RealmId)
Wakes realm id: simulated from the next tick on, and a Sleep realm holds for its
SleepAfterTicks again before it may go dormant. Any thread.
public void Wake(RealmId id)
Parameters
idRealmId