Orleans runtime architecture

The implementation track explains how Orleans realizes the virtual actor model for runtime contributors, provider authors, and operators who reason about failure, consistency, scheduling, and extensibility. The conceptual and task-oriented sections provide application programming guidance.

The pages in this track use Orleans source and tests as the specification. Internal type names let readers follow an operation through the repository. Public APIs and explicitly identified extension points carry compatibility contracts.

A runtime map

An application call enters through generated proxy code, becomes a Message, and is routed by the grain directory and placement services. MessageCenter delivers it locally or through a Connection managed by ConnectionManager. The target Catalog resolves an activation, where ActivationData admits the request and WorkItemGroup executes one synchronous turn at a time. Responses travel back through the same messaging and callback pipeline.

The runtime is intentionally layered:

flowchart LR
    Proxy[Generated proxy and invokable] --> Factory[MessageFactory]
    Factory --> Center[MessageCenter]
    Center --> Directory[Grain directory and placement]
    Center --> Network[ConnectionManager and transport]
    Directory --> Activation[Catalog and ActivationData]
    Activation --> Admission[Request admission]
    Admission --> Scheduler[WorkItemGroup]
    Scheduler --> Grain[Grain turn]
    Grain --> Serialization[Generated codecs and wire format]
    Serialization --> Network

Use this runtime map and the following topic list to choose the required depth. The runtime architecture page follows the normal call path; the messaging, serialization, reminder, transaction, and version-skew pages explain the boundaries where failure, persistence, and rolling upgrades change the guarantees.

Runtime core

Runtime architecture follows a call through client, messaging, placement, directory, activation, and scheduling components.
Activation lifecycle and migration explains creation, activation, collection, deactivation, and state transfer.
Cluster membership describes the failure detector, membership table, ordered views, and death-vote protocol.
Grain directory distinguishes the default LocalGrainDirectory DHT from the experimental distributed directory.
Scheduling and turn execution explains WorkItemGroup, continuations, interleaving, and single-threaded execution.
Messaging and delivery semantics traces requests and explains why a timeout has an unknown outcome.
Transport and networking internals explains connection establishment, framing, backpressure, and shutdown behavior.
Placement and activation balancing covers the default resource-optimized policy and the opt-in movement protocols.

Runtime services and extensibility

Lifecycle implementation describes ordered startup and shutdown.
Serialization and code generation covers generated codecs, proxies, manifests, wire identity, and custom components.
Reminders explains ring ownership, durable reminder rows, refresh, and tick delivery.
Transactions explains transaction agents, managers, participant queues, and recovery decisions.
Rolling version skew connects interface version manifests, compatibility directors, selectors, and wire compatibility during mixed-version operation.
Persistent streams explains pulling agents, queue ownership, caches, cursors, pub-sub, and recovery.
Provider authoring describes named providers, configuration binding, lifecycle participation, and validation.
TestingHost architecture explains the in-process cluster harness and its substitutions for production services.

Defaults that shape the architecture

Concern	Default
Placement	ResourceOptimizedPlacement
Grain directory	`LocalGrainDirectory`, using the membership ring
Experimental directory	Opt-in with CoreHostingExtensions.AddDistributedGrainDirectory; warning `ORLEANSEXP003`
Experimental directory partitions	GrainDirectoryOptions.PartitionsPerSilo defaults to 1
Membership probe timeout	5 seconds
Death-vote expiry	2 minutes
MessagingOptions.ResponseTimeout	30 seconds, or 30 minutes while a debugger is attached
Automatic call retry after response timeout	None

Configuration values affect failure detection and resource use. This track explains their role in protocols, while the hosting configuration guide and deployment guidance own operational recommendations.

For the application mental model, start with Orleans overview. For task-oriented recipes that apply these components, use the how-to guide index; for public type contracts, use the C# API reference.