pub struct Session { /* private fields */ }Expand description
Owner of a session’s lifecycle.
Dropping the owner requests cancellation and completes the session without blocking the dropping thread. A sender, request client, or subscription cloned from the session does not keep the session alive.
Dropping a receiver obtained from the session only removes that subscription; it does not close the session.
Implementations§
Source§impl Session
impl Session
Sourcepub fn client_id(&self) -> ClientId
pub fn client_id(&self) -> ClientId
Returns the identifier of the client that created this session.
Sourcepub fn sender(&self) -> Sender
pub fn sender(&self) -> Sender
Creates a sender bound to this session.
Clones remain usable across reconnects, but cannot prevent session cancellation after this owner is dropped.
Sourcepub fn requests(&self) -> Result<RequestClient>
pub fn requests(&self) -> Result<RequestClient>
Creates the request API when response routing is enabled for the session.
Returns ErrorKind::RoutingDisabled
when the session was configured for one-way messaging.
Sourcepub fn response_resolver(&self) -> Result<ResponseResolver>
pub fn response_resolver(&self) -> Result<ResponseResolver>
Creates a manual response resolver when manual routing is configured.
Automatic routing modes return a routing-mode mismatch error.
Sourcepub fn take_messages(&mut self) -> Option<MessageReceiver>
pub fn take_messages(&mut self) -> Option<MessageReceiver>
Takes the session’s one-time initial message receiver, if available.
Sourcepub fn take_journal(&mut self) -> Option<ConnectionJournal>
pub fn take_journal(&mut self) -> Option<ConnectionJournal>
Takes the optional connection journal receiver. A receiver can be taken
only once; subsequent calls return None.
Sourcepub fn subscribe_messages(
&self,
options: ReceiveOptions,
) -> Result<MessageReceiver>
pub fn subscribe_messages( &self, options: ReceiveOptions, ) -> Result<MessageReceiver>
Subscribes to incoming messages using the supplied bounded receive policy.
Sourcepub fn start_application_heartbeat(
&self,
config: ApplicationHeartbeatConfig,
) -> Result<ApplicationHeartbeatHandle>
pub fn start_application_heartbeat( &self, config: ApplicationHeartbeatConfig, ) -> Result<ApplicationHeartbeatHandle>
Starts a fixed-interval application-level heartbeat loop.
A response matcher uses a dedicated bounded message subscription. When
the session keeps the default initial inbox, take that inbox first or
configure InitialMessages::DiscardUnmatched
when creating the session. Write-only heartbeats do not allocate a
message subscription.
Sourcepub fn subscribe_events(&self) -> Result<ConnectionEvents>
pub fn subscribe_events(&self) -> Result<ConnectionEvents>
Subscribes to connection lifecycle events.
Sourcepub fn subscribe_tasks(&self, options: TaskEventOptions) -> Result<TaskEvents>
pub fn subscribe_tasks(&self, options: TaskEventOptions) -> Result<TaskEvents>
Subscribes to task events using the supplied bounded delivery options.
Sourcepub fn watch_state(&self) -> Result<StateReceiver<ConnectionSnapshot>>
pub fn watch_state(&self) -> Result<StateReceiver<ConnectionSnapshot>>
Creates a state receiver that observes the latest connection snapshot.
Sourcepub fn on_message<F>(&mut self, callback: F) -> Result<Subscription>
pub fn on_message<F>(&mut self, callback: F) -> Result<Subscription>
Registers a callback for incoming messages on the initial message lane.
Sourcepub fn on_event<F>(&self, callback: F) -> Result<Subscription>
pub fn on_event<F>(&self, callback: F) -> Result<Subscription>
Registers a callback for connection lifecycle events.
Sourcepub fn on_task<F>(
&self,
options: TaskEventOptions,
callback: F,
) -> Result<Subscription>
pub fn on_task<F>( &self, options: TaskEventOptions, callback: F, ) -> Result<Subscription>
Registers a callback for task events with the supplied delivery options.
Sourcepub fn on_state<F>(&self, callback: F) -> Result<Subscription>
pub fn on_state<F>(&self, callback: F) -> Result<Subscription>
Registers a callback for connection-state changes.
Sourcepub fn state(&self) -> Result<ConnectionSnapshot>
pub fn state(&self) -> Result<ConnectionSnapshot>
Reads the current connection snapshot without waiting for a transition.
Sourcepub async fn wait_connected(&self) -> Result<ConnectionInfo>
pub async fn wait_connected(&self) -> Result<ConnectionInfo>
Waits until a physical connection is established and returns its info.
Sourcepub async fn closed(&self) -> Result<SessionEnd>
pub async fn closed(&self) -> Result<SessionEnd>
Waits for lifecycle publication and cleanup to complete, then returns the immutable terminal result. A cancelled session may return an error and still permit a new session on a live client. Client shutdown is permanent.
Sourcepub fn notify_network_available(&self)
pub fn notify_network_available(&self)
Notifies the client that network access may have returned.
The notification is advisory; it does not create a connection or alter the configured reconnect policy.
Sourcepub fn cancel(&self) -> bool
pub fn cancel(&self) -> bool
Requests cancellation and returns whether this call won the request race.
Cancellation is cooperative. The session’s terminal result is reported by
Self::closed; existing send or request operations may complete with a
cancellation or delivery-unknown outcome.
Sourcepub async fn close(&self) -> Result<SessionEnd>
pub async fn close(&self) -> Result<SessionEnd>
Gracefully closes the session using the protocol’s default close frame.
Sourcepub async fn close_with(&self, frame: CloseFrame) -> Result<SessionEnd>
pub async fn close_with(&self, frame: CloseFrame) -> Result<SessionEnd>
Gracefully closes the session with an application-supplied close frame.
The returned value describes session termination; it does not guarantee that a peer has processed the close frame.