Struct SessionRequest
Steers one session from inside a system: its profile, its observers, what it controls, its budget, and whether it stays.
public readonly ref struct SessionRequest- Inherited Members
Remarks
These are requests, not writes. Systems run in parallel over their own entities, and several of them may decide something about the same session in the same tick. Each call appends a record to the calling worker's own segment — no lock, no shared cursor, no false sharing — and the engine applies every segment single-threaded at the start of the session pass. Last writer wins per field, in a fixed order (worker index, then record order), so the result is deterministic rather than whichever thread happened to be quicker.
A ref struct on purpose. It borrows the worker's segment for the duration of one statement; it cannot be stored on a field, captured or passed to another thread, which is the compiler enforcing the per-worker discipline instead of documentation asking for it.
What Phase 1 applies. Profile(string), Control(EntityId), SetBudget(int) and Kick(ushort, string) take effect. Observe(ObserverDeclaration, int), Unobserve(int) and SetSources(params SourceDeclaration[]) throw here, at the call site, naming the phase that builds them — the shape is complete now so that an application written against it never has to be revisited when the verb it wanted starts working.
A refusal is thrown where the caller is, not a tick later. Recording an unsupported verb and refusing it when the session pass runs puts the exception on the engine's own stack, with nothing left naming the system that asked for it — and the system's own tick has already finished, so a debugger stopped on the throw cannot show what led to it. Kick(ushort, string) has always validated its close code at the call site for the same reason.
Properties
Session
The session these requests are about.
public SessionId Session { get; }Property Value
Methods
Control(EntityId)
Binds the session to an entity it controls: owner fields and the SELF block follow that entity, and a profile's bound sphere follows it too.
public SessionRequest Control(EntityId entity)Parameters
Returns
- SessionRequest
This request, so several may be chained.
Kick(ushort, string)
Ends the session.
public SessionRequest Kick(ushort code, string reason = null)Parameters
codeushortThe close code, in the application range
4100-4999.reasonstringWhy, at most KickReasonMaxBytes bytes once encoded; longer reasons are truncated on the wire.
Returns
- SessionRequest
This request, so several may be chained.
Exceptions
- ArgumentOutOfRangeException
codeis outside4100-4999. Every lower code already means something specific to every client — 1002 framing, 1013 overload, 4003 admission — so borrowing one makes an application's decision read as an engine fault and changes whether SDKs reconnect.
Observe(ObserverDeclaration, int)
Puts an observer in one of the session's observer slots, replacing whatever was there.
public SessionRequest Observe(ObserverDeclaration observer, int slot)Parameters
observerObserverDeclarationThe region of interest.
slotintWhich of the session's observer slots it occupies.
Returns
- SessionRequest
This request, so several may be chained.
Remarks
The shape is final; the verb arrives in Phase 2, with the observer shapes that need it.
Exceptions
- NotSupportedException
Always, until Phase 2 builds per-session observers.
Profile(string)
Binds the session to a declared interest profile.
public SessionRequest Profile(string name)Parameters
namestringThe profile's name, as
subs.Profile(name, ...)declared it.
Returns
- SessionRequest
This request, so several may be chained.
SetBudget(int)
Sets the session's outbound byte budget.
public SessionRequest SetBudget(int bytesPerSecond)Parameters
bytesPerSecondintThe budget. Zero removes it; the frame ceiling and the enter budget still apply.
Returns
- SessionRequest
This request, so several may be chained.
Remarks
Within a budget, records are deferred by priority and never dropped, so a small number slows a view down rather than corrupting it.
SetSources(params SourceDeclaration[])
Replaces the session's whole source subscription list: diffed against the current one, idempotent, atomic within a frame.
public SessionRequest SetSources(params SourceDeclaration[] sources)Parameters
sourcesSourceDeclaration[]The full list. An empty list unsubscribes from everything.
Returns
- SessionRequest
This request, so several may be chained.
Remarks
The shape is final; the verb arrives in Phase 4, with shared sources themselves.
Exceptions
- NotSupportedException
Always, until Phase 4 builds shared sources.
Unobserve(int)
Empties one of the session's observer slots.
public SessionRequest Unobserve(int slot)Parameters
slotintWhich slot.
Returns
- SessionRequest
This request, so several may be chained.
Remarks
The shape is final; the verb arrives in Phase 2, with Observe(ObserverDeclaration, int).
Exceptions
- NotSupportedException
Always, until Phase 2 builds per-session observers.