pub trait Session: Debug {
// Required methods
fn status(&self) -> SessionStatus;
fn close(&mut self);
fn drive(&mut self) -> Result<DriveOutcome, Error>;
}Expand description
An instance of a connection or logical session, which may also support Receive, Publish, or dispatching received events to a Callback/CallbackRef.
§Connecting
Some implementations may not default to an established state, in which case immediate calls to publish() and receive() will fail.
The Session::status function provides the current status, which will not return Established until all required handshakes are complete.
When Session::status returns SessionStatus::Establishing, you may drive the connection process via the Session::drive function.
§Retrying
The Ok result of publish(..) and receive(..) operations may return ReceiveOutcome::Idle, ReceiveOutcome::Buffered, or PublishOutcome::Incomplete.
These outcomes indicate that an operation may need to be retried. See ReceiveOutcome and PublishOutcome for more details.
§Duty Cycles
The Session::drive operation is used to finish connecting and to service reading/writing buffered data and to dispatch callbacks.
Most, but not all, Session implementations will require periodic calls to Session::drive in order to function.
Implementations that do not require calls to Session::drive will no-op when it is called.
§Publishing
Session impls that can publish data will implement Publish.
§Receiving
Session impls that can receive data via polling implement Receive.
Impls that receive data via callbacks will accept a Callback or CallbackRef as input.
For cross-compatibilty between Receive and Callback/CallbackRef paradiagms, see the [callback] module.
- [
callback::CallbackQueue] implsCallback
Required Methods§
sourcefn status(&self) -> SessionStatus
fn status(&self) -> SessionStatus
Check the current session status.
If this returns SessionStatus::Establishing, use Session::drive to progress the connection process.
sourcefn close(&mut self)
fn close(&mut self)
Force the session to move to a SessionStatus::Terminated state immediately, performing any necessary immediately graceful close actions as appropriate.
All subsequent calls to status will return SessionStatus::Terminated immediately after this function is called.
sourcefn drive(&mut self) -> Result<DriveOutcome, Error>
fn drive(&mut self) -> Result<DriveOutcome, Error>
Some implementations will internally buffer payloads or require a duty cycle to drive callbacks.
Those implementations will require drive(..) to be called continuously to completely publish and/or receive data.
This function will return DriveOutcome::Active if work was done, indicating to any scheduler that more work may be pending.
When this function returns DriveOutcome::Idle, only then should it indicate to a scheduler that yielding or idling is appropriate.