Skip to main content

Module session

Module session 

Source
Expand description

Sans-I/O session engines for both roles.

A session is driven by four calls in and three out:

session.handle_text(&text, now)      session.poll_transmit()
session.handle_message(message, now) session.poll_event()
session.handle_timeout(now)          session.poll_timeout()
session.transport_closed(now)

No sockets, no clock, no tasks. now is a parameter, which is what makes a five-second acknowledgement timeout, a description that becomes valid at midnight and a timer that blocks a transition into ordinary unit tests rather than things you wait for.

§What the engine does that an application would otherwise have to

  • Acknowledges everything, synchronously. S2J requires a ReceptionStatus for every message except a ReceptionStatus, and the engine chooses it inside handle_text — INVALID_DATA or INVALID_MESSAGE from the codec, INVALID_CONTENT from the state table or the validator (with the failing rule’s identifier in the diagnostic_label), otherwise OK. Nothing is held across an await, so the deadlock [s2-json #22] describes cannot happen.
  • Tracks what is outstanding. Every message sent enters a ledger with a deadline; the matching acknowledgement resolves it, and a deadline that passes produces an event rather than a stall.
  • Enforces the state table. S2C §State of communication says what may be sent when; the engine refuses outbound messages at the call site and answers inbound ones with INVALID_CONTENT.
  • Resolves instructions. An Instructed event carries the actuator, the operation mode, the factor, the power it implies and any timer in the way — so a Resource Manager never looks an identifier up by hand.
  • Remembers. Descriptions, constraints, profiles, instruction statuses, timers and the active operation mode of every actuator, in a bounded Registry.

§Both roles, one core

RmSession and CemSession are built on the same SessionCore, so a CEM and an RM from this crate can be wired back to back in memory — which is how the standard’s own documented conversations are tested.

Re-exports§

pub use core::AckLedger;
pub use core::AckOutcome;
pub use core::Backoff;
pub use core::CloseReason;
pub use core::MessageHandle;
pub use core::Negotiation;
pub use core::OutOfOrderPolicy;
pub use core::Outgoing;
pub use core::Registry;
pub use core::SendError;
pub use core::SessionCore;
pub use core::SessionState;
pub use core::Stats;

Modules§

core
What both session engines are built on: the outbox, the acknowledgement ledger, and the registry of everything either side has published.

Structs§

Analyzer
A stateful observer of a conversation it is not part of.
CemConfig
How a CemSession behaves.
CemSession
A Customer Energy Manager’s side of one S2 session.
Inbound
What an engine did with one inbound message.
Instructed
An instruction the Customer Energy Manager sent, already acknowledged and already resolved against the description this session published.
Observed
What an Analyzer made of one frame.
RmConfig
How a RmSession behaves.
RmSession
A Resource Manager’s side of one S2 session.
SessionSet
A keyed collection of sessions driven as one.

Enums§

CemEvent
Something a Customer Energy Manager’s application needs to know about.
RmEvent
Something a Resource Manager’s application needs to know about.

Traits§

InboundPolicy
A hook consulted before an inbound message is acknowledged.
Session
What both engines have in common: four calls in, three out, and a clock that is always a parameter.