Struct CallContext 

pub struct CallContext<P: Protocol> { /* private fields */ }

Request-scoped services supplied to a server handler.

A context is not cloneable and must be consumed to send a response.

Implementations

impl<P: Protocol> CallContext<P>

pub fn trailer(&mut self) -> Option<TrailerRecv>

Takes this request’s raw-byte trailer, if present.

The returned value implements AsyncRead. Dropping it stops local consumption and immediately tells the peer to stop sending, as does responding while the context still holds it.

Taken rather than borrowed, so a handler may keep reading after it has responded. Paired with respond_with_trailer that gives a duplex byte pipe over one call: each direction is an independent stream that ends when its own end says so, and the call itself is complete as soon as the response head goes out. Neither direction holds a call slot after that, so the pipes are bounded by trailer credit rather than by max_concurrent_calls — and, as with a socket, nothing ties the two halves together: closing one does not close the other, and a peer that vanishes is noticed through the transport.

pub fn trailer_manual_credit(&mut self) -> Option<TrailerRecv>

Returns this request’s raw-byte trailer in manual-credit mode.

The consumer then owes the peer an explicit TrailerRecv::release for every chunk it finishes with, instead of credit being returned on read. Use this when the bytes are being handed somewhere slower than this process, so that the peer’s send rate follows the real drain rate; read release first, since manual mode moves a deadlock rule into calling code.

The mode is fixed here rather than switchable afterwards, so a trailer cannot be half auto-credited and half not. Taken rather than borrowed, exactly as in trailer.

pub fn respond(self, response: P::Response)

Sends a response without a trailer and consumes this call context.

A request trailer this context still holds is discarded; one already taken by trailer is untouched and stays readable.

pub fn respond_with_trailer(self, response: P::Response) -> TrailerSend<()>

Sends a response head and returns a writer for its raw-byte trailer.

Call TrailerSend::finish, or asynchronously shut down the returned writer, to commit the trailer. Dropping it without finishing aborts the trailer. A request trailer this context still holds is discarded; one already taken by trailer is untouched, which is what makes the two directions a duplex pipe.

pub fn release_payload(&mut self)

Returns this request’s payload quota to the peer now, rather than when this context is dropped.

The quota is charged for the whole call, so a handler that pends for a long time throttles the connection for as long as it pends — which is fine for the small payloads a long-poll usually carries, and is not for a large one. This is the escape hatch: finish with the request, drop whatever you decoded from it, then release. Nothing checks that you did the first two, and releasing while still holding the request’s data merely makes the peer’s accounting optimistic.

Idempotent, and never required — dropping the context releases just the same.

pub fn shutdown(&mut self)

Requests graceful shutdown after this handler sends its response.

The server stops accepting requests once this context is consumed by respond or respond_with_trailer, then lets already-running handlers finish.

pub async fn cancel_guard<T, F>( &mut self, operation: F, ) -> Result<T, RequestCancelled>

where F: AsyncFnOnce(&mut CallContext<P>) -> T,

Runs an operation that can observe request cancellation without dropping the handler itself.

If the peer cancels while operation is running, its future is dropped and this method returns RequestCancelled. The handler regains the context and may perform cleanup or send an application-level response. Only one cancellation guard may be active at a time; nesting guards panics.

pub fn register<T: OpaqueResource>(&self, value: T) -> Gift<T::Marker>

Register an opqaue handle.

The underlying resource will be automatically dropped when both of the following hold:

• It is no longer referenced by the client, or the server has unregistered it
• All oustanding OpaqueGuards have been dropped

Panics

If a different concrete type has already been registered under T::Marker on this session.

pub fn acquire<T: OpaqueResource>( &self, value: Cite<T::Marker>, ) -> Result<OpaqueGuard<T>, InvalidOpaque>

Acquires a guard an opaque handle citation.

Returns InvalidOpaque if the resource was unregistered while the peer still held a reference to it.

Panics

If the handle was minted by a different session.

pub fn unregister<T: OpaqueResource>( &self, value: Cite<T::Marker>, ) -> Result<Option<T>, InvalidOpaque>

Unregisters an opaque handle

If no outstanding OpaqueGuards existed, the resource is returned directly; otherwise, None is returned and the resource will be dropped with the last OpaqueGuard. In either case, subsequent uses of Self::acquire will fail. If the handle has already been unregistered, returns InvalidOpaque.

Panics

If the handle was minted by a different session.

pub fn try_unregister<T: OpaqueResource>( &self, value: Cite<T::Marker>, ) -> Result<Option<T>, InvalidOpaque>

Unregisters an opaque handle if not busy

The recoverable counterpart of unregister: if outstanding OpaqueGuards exist, the handle is not unregistered, which is signaled by a None return value.

Panics

If the handle was minted by a different session, as with acquire.

Trait Implementations

impl<P: Protocol> Drop for CallContext<P>

fn drop(&mut self)

Executes the destructor for this type.

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.