Skip to main content

Session

Struct Session 

Source
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

Source

pub fn id(&self) -> SessionId

Returns this logical session’s stable identifier.

Source

pub fn client_id(&self) -> ClientId

Returns the identifier of the client that created this session.

Source

pub fn metadata(&self) -> &Metadata

Borrows the application metadata attached to this session.

Source

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.

Source

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.

Source

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.

Source

pub fn take_messages(&mut self) -> Option<MessageReceiver>

Takes the session’s one-time initial message receiver, if available.

Source

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.

Source

pub fn subscribe_messages( &self, options: ReceiveOptions, ) -> Result<MessageReceiver>

Subscribes to incoming messages using the supplied bounded receive policy.

Source

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.

Source

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.

Source

pub fn subscribe_events(&self) -> Result<ConnectionEvents>

Subscribes to connection lifecycle events.

Source

pub fn subscribe_tasks(&self, options: TaskEventOptions) -> Result<TaskEvents>

Subscribes to task events using the supplied bounded delivery options.

Source

pub fn watch_state(&self) -> Result<StateReceiver<ConnectionSnapshot>>

Creates a state receiver that observes the latest connection snapshot.

Source

pub fn on_message<F>(&mut self, callback: F) -> Result<Subscription>

Registers a callback for incoming messages on the initial message lane.

Source

pub fn on_event<F>(&self, callback: F) -> Result<Subscription>

Registers a callback for connection lifecycle events.

Source

pub fn on_task<F>( &self, options: TaskEventOptions, callback: F, ) -> Result<Subscription>

Registers a callback for task events with the supplied delivery options.

Source

pub fn on_state<F>(&self, callback: F) -> Result<Subscription>

Registers a callback for connection-state changes.

Source

pub fn state(&self) -> Result<ConnectionSnapshot>

Reads the current connection snapshot without waiting for a transition.

Source

pub async fn wait_connected(&self) -> Result<ConnectionInfo>

Waits until a physical connection is established and returns its info.

Source

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.

Source

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.

Source

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.

Source

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.

Source

pub async fn close(&self) -> Result<SessionEnd>

Gracefully closes the session using the protocol’s default close frame.

Source

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.

Trait Implementations§

Source§

impl Debug for Session

Source§

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter. Read more
Source§

impl Drop for Session

Source§

fn drop(&mut self)

Executes the destructor for this type. Read more
Source§

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)
Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned. Read more

Auto Trait Implementations§

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T> Instrument for T

Source§

fn instrument(self, span: Span) -> Instrumented<Self> ⓘ

Instruments this type with the provided Span, returning an Instrumented wrapper. Read more
Source§

fn in_current_span(self) -> Instrumented<Self> ⓘ

Instruments this type with the current Span, returning an Instrumented wrapper. Read more
Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> Same for T

Source§

type Output = T

Should always be Self
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
Source§

impl<T> WithSubscriber for T

Source§

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self> ⓘ
where S: Into<Dispatch>,

Attaches the provided Subscriber to this type, returning a WithDispatch wrapper. Read more
Source§

fn with_current_subscriber(self) -> WithDispatch<Self> ⓘ

Attaches the current default Subscriber to this type, returning a WithDispatch wrapper. Read more