Table of Contents

Class SubscriptionsRegistry

Namespace
Typhon.Engine
Assembly
Typhon.Engine.dll

The declaration surface for engine-owned replication: the projections clients may see, the profiles that decide what each session watches, the commands clients may send, the events they hear and the metrics they are told about.

public sealed class SubscriptionsRegistry
Inheritance
SubscriptionsRegistry
Inherited Members

Remarks

Reached through Subscriptions, and configured before Start(). Replication rides the tick, so it belongs to the runtime rather than to DatabaseEngine; and everything here is compiled once at Start, which is why the registry freezes there and refuses a late declaration instead of quietly not applying it.

Declaring costs nothing at run time. The registry holds names, codecs and policy; it has no per-tick presence at all. What the tick sees is the compiled plan the projection compiler builds from it, in which every name has already become an offset.

Malformed declarations are refused where they are written. A duplicate wire name, a ninth change group, a 256th archetype, a 64-bit source with no explicit narrowing and a metric under the reserved typhon. prefix all throw from the call that declared them. What cannot be judged from one declaration — an observer shape or a source that a later phase builds — is refused at Start, with the phase named.

Constructors

SubscriptionsRegistry(SubscriptionsOptions)

Creates a registry over the given options.

public SubscriptionsRegistry(SubscriptionsOptions options = null)

Parameters

options SubscriptionsOptions

The operator's replication options. null takes the defaults.

Remarks

The runtime builds its own from Subscriptions and exposes it as Subscriptions; that is the one the engine reads. Constructing one directly is for a test, or for an application that assembles its declarations somewhere other than beside its host.

Properties

Archetypes

The archetype projections, in declaration order.

public IReadOnlyList<ArchetypeProjection> Archetypes { get; }

Property Value

IReadOnlyList<ArchetypeProjection>

Commands

The command types, in declaration order.

public IReadOnlyList<CommandDeclaration> Commands { get; }

Property Value

IReadOnlyList<CommandDeclaration>

DeclaredRealmKinds

The realm kinds declared with RealmKinds(params string[]); the default kind "" is implicit.

public IReadOnlyList<string> DeclaredRealmKinds { get; }

Property Value

IReadOnlyList<string>

Events

The replicated events, in declaration order.

public IReadOnlyList<EventDeclaration> Events { get; }

Property Value

IReadOnlyList<EventDeclaration>

GroupSets

The group sets declared with Groups(string, Action<GroupSetBuilder>), in ordinal name order — the catalog's: a set's index is its number on the wire.

public IReadOnlyList<GroupSetDeclaration> GroupSets { get; }

Property Value

IReadOnlyList<GroupSetDeclaration>

IsFrozen

Whether Start has compiled these declarations. A frozen registry refuses every further declaration.

public bool IsFrozen { get; }

Property Value

bool

Metrics

The application's metrics, in declaration order. The built-ins are not listed here: the engine owns them.

public IReadOnlyList<MetricDeclaration> Metrics { get; }

Property Value

IReadOnlyList<MetricDeclaration>

Options

The operator's replication options.

public SubscriptionsOptions Options { get; }

Property Value

SubscriptionsOptions

Profiles

The interest profiles, in declaration order.

public IReadOnlyList<ProfileDeclaration> Profiles { get; }

Property Value

IReadOnlyList<ProfileDeclaration>

Sessions

Session kinds, admission and the tick-visible session lifecycle.

public SubscriptionsSessions Sessions { get; }

Property Value

SubscriptionsSessions

Methods

Archetype<TArchetype>()

Declares an archetype from its replication attributes (design/Subscriptions/11 § 5): [Replicated] on the archetype, [Motion] or [Position] on a Comp<T> field, [Replicate], [OnEnter], [Owner], [Fraction], [Heading] on its components' fields. The source generator compiles them into the builder calls Archetype<TArchetype>(Action<ArchetypeProjectionBuilder>) would take; calling that overload instead replaces the attributes entirely, which is how a deployment overrides them.

public SubscriptionsRegistry Archetype<TArchetype>() where TArchetype : Archetype<TArchetype>, IReplicatedArchetype

Returns

SubscriptionsRegistry

This registry.

Type Parameters

TArchetype

A [Replicated] archetype: the generator implements IReplicatedArchetype on it, so an archetype without the attribute — or an assembly the generator does not run in — does not compile here.

Archetype<TArchetype>(Action<ArchetypeProjectionBuilder>)

Declares what clients may see of an archetype.

public SubscriptionsRegistry Archetype<TArchetype>(Action<ArchetypeProjectionBuilder> configure) where TArchetype : Archetype<TArchetype>

Parameters

configure Action<ArchetypeProjectionBuilder>

Declares its position, fields and owner section.

Returns

SubscriptionsRegistry

This registry.

Type Parameters

TArchetype

The archetype.

Command<T>(Action<CommandBuilder<T>>)

Declares a command type clients may send.

public SubscriptionsRegistry Command<T>(Action<CommandBuilder<T>> configure) where T : unmanaged

Parameters

configure Action<CommandBuilder<T>>

Declares delivery, rate, roles and pre-check.

Returns

SubscriptionsRegistry

This registry.

Type Parameters

T

The command type: an unmanaged struct.

Event<T>(Action<EventBuilder<T>>)

Declares an event type clients receive, and how it is routed. Systems send one with Emit<T>(in T).

public SubscriptionsRegistry Event<T>(Action<EventBuilder<T>> configure) where T : unmanaged

Parameters

configure Action<EventBuilder<T>>

Declares routing and fields.

Returns

SubscriptionsRegistry

This registry.

Type Parameters

T

The event type: an unmanaged, blittable struct.

Remarks

Emitted, not drained (09 § 11, Q3). An event a client sees is emitted explicitly, as state is pushed (ADR-067): an application that also applies its events keeps its own EventQueue<T> for the simulation and emits what clients should see.

Groups(string, Action<GroupSetBuilder>)

Declares a group set (14 § 3): a family of groups, each a key its members carry in an indexed field, held by a session while its selector names the key — for a region set, while the session's observer meets the region's extent (Groups(string, double)).

public SubscriptionsRegistry Groups(string name, Action<GroupSetBuilder> configure)

Parameters

name string

The set's name, as profiles and the catalog name it.

configure Action<GroupSetBuilder>

Declares the selector and the members.

Returns

SubscriptionsRegistry

This registry.

Metric(string, string, Codec, Func<double>, MetricKind, string[])

Declares an application metric, carried to sessions that asked for statistics.

public SubscriptionsRegistry Metric(string name, string unit, Codec codec, Func<double> source, MetricKind kind = MetricKind.Gauge, string[] labels = null)

Parameters

name string

The metric's name. The typhon. prefix is reserved for the engine's own.

unit string

Its unit, as a client displays it — ms, count, B/s.

codec Codec

How the value travels. Encoders saturate: no NaN and no infinity reach the wire.

source Func<double>

Reads the current value, once per emission — not once per session.

kind MetricKind

Gauge or counter.

labels string[]

The label set, for a metric that contributes one value per label rather than one value.

Returns

SubscriptionsRegistry

This registry.

Metric(string, string, Codec, string[], MetricValuesSource, MetricKind)

Declares a labelled application metric (09 § 15, D5): one value per label, all read by one call per emission — not one per label, not one per session.

public SubscriptionsRegistry Metric(string name, string unit, Codec codec, string[] labels, MetricValuesSource source, MetricKind kind = MetricKind.Gauge)

Parameters

name string

The metric's name. The typhon. prefix is reserved for the engine's own.

unit string

Its unit.

codec Codec

How each value travels.

labels string[]

The labels, at least one, distinct: the order the values are written in.

source MetricValuesSource

Fills the values, one per label in labels' order; a value it leaves unwritten is zero.

kind MetricKind

Gauge or counter.

Returns

SubscriptionsRegistry

This registry.

Profile(string, Action<ProfileBuilder>)

Declares a named set of observers a session can be bound to.

public SubscriptionsRegistry Profile(string name, Action<ProfileBuilder> configure)

Parameters

name string

The profile's name.

configure Action<ProfileBuilder>

Declares its observers.

Returns

SubscriptionsRegistry

This registry.

RealmKinds(params string[])

Declares the kinds a realm may carry (12-realms § 1.4) — planet, interior, space — which a profile's variants are chosen by (In(string, Action<ProfileBuilder>)). The default kind "" always exists; the catalog lists them in canonical order.

public SubscriptionsRegistry RealmKinds(params string[] kinds)

Parameters

kinds string[]

Distinct, non-empty names.

Returns

SubscriptionsRegistry

This registry.

SessionMetric(string, string, Codec, Func<SessionId, double>, MetricKind)

Declares a per-session application metric (09 § 15, D5): a value for each session that asked for statistics, read once per such session per emission — a second, on the tick every block is sent.

public SubscriptionsRegistry SessionMetric(string name, string unit, Codec codec, Func<SessionId, double> source, MetricKind kind = MetricKind.Gauge)

Parameters

name string

The metric's name. The typhon. prefix is reserved for the engine's own.

unit string

Its unit.

codec Codec

How the value travels.

source Func<SessionId, double>

Reads the session's value. It runs on a frame worker, concurrently for different sessions: it must not write shared state.

kind MetricKind

Gauge or counter.

Returns

SubscriptionsRegistry

This registry.

Static<TArchetype>(Action<ArchetypeProjectionBuilder>)

Declares an archetype whose replicated state never changes: its record is sent once, on enter, and never updated.

public SubscriptionsRegistry Static<TArchetype>(Action<ArchetypeProjectionBuilder> configure) where TArchetype : Archetype<TArchetype>

Parameters

configure Action<ArchetypeProjectionBuilder>

Declares its position and fields.

Returns

SubscriptionsRegistry

This registry.

Type Parameters

TArchetype

The archetype.

Remarks

This is not an optimization hint the engine may ignore. A static archetype has no change groups and no per-entity comparison at all, so a world of scenery costs the projection pass nothing per tick — which is the difference between replicating a landscape and replicating a simulation.