Struct HandlerCtx 

pub struct HandlerCtx { /* private fields */ }

A context for handler requests that allow the handler to send notifications and spawn long-running tasks (e.g. subscriptions).

The handler is used for two things:

• Spawning long-running tasks (e.g. subscriptions) via HandlerCtx::spawn or HandlerCtx::spawn_blocking.
• Sending notifications to pubsub clients via HandlerCtx::notify. Notifcations SHOULD be valid JSON-RPC objects, but this is not enforced by the type system.

Implementations

impl HandlerCtx

pub fn child_ctx<S: Clone + Send + Sync + 'static>( &self, router: &Router<S>, parent: Option<&Span>, ) -> Self

Create a child handler context for a new handler invocation.

This is used when handling batch requests, to give each handler its own context.

pub const fn tracing_info(&self) -> &TracingInfo

Get a reference to the tracing information for this handler context.

pub const fn service_name(&self) -> &'static str

Get the OpenTelemetry service name for this handler context.

pub fn span(&self) -> &Span

Get a reference to the tracing span for this handler context.

pub fn set_tracing_info(&mut self, tracing: TracingInfo)

Set the tracing information for this handler context.

pub fn notifications_enabled(&self) -> bool

Check if notifications can be sent to the client. This will be false when either the transport does not support notifications, or the notification channel has been closed (due the the client going away).

pub fn notification_capacity(&self) -> usize

Returns the maximum capacity of the notification channel, or 0 if notifications are not enabled.

pub fn init_request_span<S>( &self, router: &Router<S>, parent: Option<&Span>, ) -> &Span

where S: Clone + Send + Sync + 'static,

Create a request span for a handler invocation.

pub async fn notify<T: RpcSend>(&self, t: T) -> Result<(), NotifyError>

Notify a client of an event.

Takes t by value to support consuming RpcSend implementations. For Serialize types, pass a reference (&item) — references implement RpcSend via the blanket impl.

pub async fn notify_stream<S, T>(&self, stream: S) -> Result<(), NotifyError>

where S: Stream<Item = T> + Send, T: RpcSend,

Forward a Stream into the notification channel.

Each item produced by the stream is serialized and sent as a notification. This continues until the stream is exhausted or an error occurs.

If notifications are not enabled on this context, the stream is not consumed and this returns Ok(()) immediately.

pub async fn permit(&self) -> Option<NotifyPermit<'_>>

Reserve a permit to send a single notification.

Returns None if notifications are not enabled or the channel is closed. Awaits until a channel slot is available.

pub async fn permit_owned(&self) -> Option<OwnedNotifyPermit>

Reserve an owned permit to send a single notification.

Returns None if notifications are not enabled or the channel is closed. Awaits until a channel slot is available.

pub fn try_permit(&self) -> Option<NotifyPermit<'_>>

Try to reserve a permit to send a single notification.

Returns None if notifications are not enabled, the channel is closed, or the channel is full.

pub fn try_permit_owned(&self) -> Option<OwnedNotifyPermit>

Try to reserve an owned permit to send a single notification.

Returns None if notifications are not enabled, the channel is closed, or the channel is full.

pub async fn permit_many( &self, n: usize, ) -> Option<impl Iterator<Item = OwnedNotifyPermit>>

Reserve n owned permits to send notifications.

This is all-or-nothing: returns None if the channel closes during acquisition, dropping any already-acquired permits. Returns None if notifications are not enabled.

pub fn try_permit_many( &self, n: usize, ) -> Option<impl Iterator<Item = OwnedNotifyPermit>>

Try to reserve n owned permits to send notifications.

This is all-or-nothing: returns None if any permit cannot be acquired. Returns None if notifications are not enabled, the channel is closed, or the channel has fewer than n available slots.

pub fn spawn<F>(&self, f: F) -> JoinHandle<Option<F::Output>>

where F: Future + Send + 'static, F::Output: Send + 'static,

Spawn a task on the task set. This task will be cancelled if the client disconnects. This is useful for long-running server tasks.

The resulting JoinHandle will contain None if the task was cancelled, and Some otherwise.

pub fn spawn_with_ctx<F, Fut>(&self, f: F) -> JoinHandle<Option<Fut::Output>>

where F: FnOnce(HandlerCtx) -> Fut, Fut: Future + Send + 'static, Fut::Output: Send + 'static,

Spawn a task on the task set with access to this context. This task will be cancelled if the client disconnects. This is useful for long-running tasks like subscriptions.

The resulting JoinHandle will contain None if the task was cancelled, and Some otherwise.

pub fn spawn_notify_stream<S, T>( &self, stream: S, ) -> JoinHandle<Option<Result<(), NotifyError>>>

where S: Stream<Item = T> + Send + 'static, T: RpcSend + 'static,

Spawn a task that forwards a Stream into the notification channel. The task will be cancelled if the client disconnects.

The resulting JoinHandle will contain None if the task was cancelled, and Some otherwise.

pub fn spawn_blocking<F>(&self, f: F) -> JoinHandle<Option<F::Output>>

where F: Future + Send + 'static, F::Output: Send + 'static,

Spawn a task that may block on the task set. This task may block, and will be cancelled if the client disconnects. This is useful for running expensive tasks that require blocking IO (e.g. database queries).

The resulting JoinHandle will contain None if the task was cancelled, and Some otherwise.

pub fn spawn_blocking_with_ctx<F, Fut>( &self, f: F, ) -> JoinHandle<Option<Fut::Output>>

where F: FnOnce(HandlerCtx) -> Fut, Fut: Future + Send + 'static, Fut::Output: Send + 'static,

Spawn a task that may block on the task set, with access to this context. This task may block, and will be cancelled if the client disconnects. This is useful for running expensive tasks that require blocking IO (e.g. database queries).

The resulting JoinHandle will contain None if the task was cancelled, and Some otherwise.

pub fn spawn_graceful<F, Fut>(&self, f: F) -> JoinHandle<Fut::Output>

where F: FnOnce(WaitForCancellationFutureOwned) -> Fut + Send + 'static, Fut: Future + Send + 'static, Fut::Output: Send + 'static,

Spawn a task on this task set. Unlike Self::spawn, this task will NOT be cancelled if the client disconnects. Instead, it is given a future that resolves when client disconnects. This is useful for tasks that need to clean up resources before completing.

pub fn spawn_graceful_with_ctx<F, Fut>(&self, f: F) -> JoinHandle<Fut::Output>

where F: FnOnce(HandlerCtx, WaitForCancellationFutureOwned) -> Fut + Send + 'static, Fut: Future + Send + 'static, Fut::Output: Send + 'static,

Spawn a task on this task set with access to this context. Unlike Self::spawn, this task will NOT be cancelled if the client disconnects. Instead, it is given a future that resolves when client disconnects. This is useful for tasks that need to clean up resources before completing.

pub fn spawn_blocking_graceful<F, Fut>(&self, f: F) -> JoinHandle<Fut::Output>

where F: FnOnce(WaitForCancellationFutureOwned) -> Fut + Send + 'static, Fut: Future + Send + 'static, Fut::Output: Send + 'static,

Spawn a blocking task on this task set. Unlike Self::spawn_blocking, this task will NOT be cancelled if the client disconnects. Instead, it is given a future that resolves when client disconnects. This is useful for tasks that need to clean up resources before completing.

pub fn spawn_blocking_graceful_with_ctx<F, Fut>( &self, f: F, ) -> JoinHandle<Fut::Output>

where F: FnOnce(HandlerCtx, WaitForCancellationFutureOwned) -> Fut + Send + 'static, Fut: Future + Send + 'static, Fut::Output: Send + 'static,

Spawn a blocking task on this task set with access to this context. Unlike Self::spawn_blocking, this task will NOT be cancelled if the client disconnects. Instead, it is given a future that resolves when the client disconnects. This is useful for tasks that need to clean up resources before completing.

Trait Implementations

impl Clone for HandlerCtx

fn clone(&self) -> HandlerCtx

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for HandlerCtx

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

Formats the value using the given formatter.