Grain directory architecture
The grain directory maps a grain identity to an activation address. It is on the critical path when a caller has no usable cached address and when the runtime creates, moves, or removes an activation. Placement chooses a silo; the directory coordinates which activation address is authoritative.
Orleans uses DistributedGrainDirectory by default, with versioned range ownership and coordinated membership-view transitions. Select LegacyGrainDirectory with UseLegacyGrainDirectory.
LegacyGrainDirectory
Section titled “LegacyGrainDirectory ”LegacyGrainDirectory partitions registrations over the membership ring. Hashing a grain identity selects the silo whose legacy directory partition is authoritative for that key. This follows the broad consistent-hashing distributed-hash-table model described by Chord, adapted to Orleans membership and activation semantics. Each silo also keeps non-authoritative cache entries to avoid repeated remote lookups.
The legacy directory preserves these invariants:
- a directory key is derived from the grain identity, not its current location;
- the membership view determines the authoritative owner;
- local cache entries are hints and can be invalidated;
- registration detects competing single-activation addresses;
- a failed or deactivated silo’s addresses are removed or rejected; and
- partition ownership transfers as the membership ring changes.
Message forwarding and invalidation repair stale caches. Forwarding is bounded and is not an application-level retry policy.
Source: Legacy directory implementation and legacy partition implementation.
Directory selection
Section titled “Directory selection”The runtime resolves a directory per grain type. The unnamed default resolves to DistributedGrainDirectory unless the silo has explicitly replaced it. A named implementation of IGrainDirectory can be registered and selected using grain-type metadata.
Custom directories own their consistency, availability, and cleanup behavior. They should define what concurrent registration means, how failed silos are removed, and whether stale reads are possible. The surrounding message router cannot turn an eventually consistent custom directory into a strongly consistent one.
Default: DistributedGrainDirectory
Section titled “Default: DistributedGrainDirectory ”The default directory is view-synchronous, with versioned range ownership and coordinated membership-view transitions. CoreHostingExtensions.AddDistributedGrainDirectory selects it explicitly or registers a named alias. Aliases share one directory instance and one lifecycle participant per silo.
The implementation divides the hash ring into configurable ranges, analogous to the virtual-node partitioning described by Dynamo. GrainDirectoryOptions.PartitionsPerSilo defaults to 1. A partition normally serves requests locally. During a membership view change, old and new owners coordinate range locks, snapshots, and ownership transfer. The design applies the virtually synchronous methodology for dynamic service replication and has similarities to Vertical Paxos and primary-backup replication.
Requests and responses carry view information. A range cannot serve a request under an incompatible ownership view. If an orderly transfer is impossible, the new owner recovers registrations by querying active silos rather than assuming the failed owner’s state.
API: CoreHostingExtensions.AddDistributedGrainDirectory and GrainDirectoryOptions. Implementation: hosting registration and DistributedGrainDirectory.
Tradeoffs
Section titled “Tradeoffs”| Property | LegacyGrainDirectory | Default DistributedGrainDirectory |
|---|---|---|
| Selection | CoreHostingExtensions.UseLegacyGrainDirectory | Runtime default |
| Ownership | Membership consistent-hash ring | Versioned ranges over membership views |
| Normal lookup | Owner partition plus per-silo cache | Owner partition plus view coordination |
| View change | Partition split/merge and cache repair | Sealed ranges and snapshot transfer |
| Recovery emphasis | Duplicate detection and invalidation | Explicit range recovery |
| Configuration | Explicit directory selection | GrainDirectoryOptions.PartitionsPerSilo, default 1 |
More partitions can improve ownership granularity but increase transfer and coordination work. Production rollouts should include compatibility, failure, and load testing.
For directory changes during a version upgrade, follow Grain directory migration.