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 start_application_heartbeat_with_reconnect(
&self,
config: ApplicationHeartbeatConfig,
) -> Result<ApplicationHeartbeatHandle>
pub fn start_application_heartbeat_with_reconnect( &self, config: ApplicationHeartbeatConfig, ) -> Result<ApplicationHeartbeatHandle>
Starts a heartbeat that requests session recovery after consecutive response timeouts on the same physical connection. A successful local write starts each response wait. A matched reply or another kind of failure resets the streak.
At the configured threshold the task waits for a different connection, then continues using the same handle. Other failures (such as a write or matcher error) retain the configured failure action. A response matcher, response timeout and an enabled session reconnect policy are required.
The matcher uses the same dedicated subscription as
Self::start_application_heartbeat.
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 async fn reconnect_if_current(&self, expected: ConnectionId) -> Result<bool>
pub async fn reconnect_if_current(&self, expected: ConnectionId) -> Result<bool>
Requests recovery if expected is still this session’s active connection.
Pass the ID observed on this session when the problem occurred. Returns
true when the worker accepts the request, or false if the physical
connection has already changed or recovery is in progress. The same
senders and subscriptions continue across recovery. Observe a new
Established event for success.
With ReconnectPolicy::Disabled, a
matching active connection is preserved and the result is
ErrorKind::InvalidPolicy. Closing or cancelled sessions return an error.
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.