Struct ConnectionDriver 

pub struct ConnectionDriver { /* private fields */ }

Drives owned endpoint work.

A driver owns the endpoint: successful completion means no further output is expected, and adapters must drain output already accepted before terminating. Errors may abort the connection without guaranteed output drain; an adapter may still preserve queued error replies before terminating.

Poll the driver concurrently with channel traffic. Endpoints without owned work return None from ConnectTo::into_channel_and_future, not a driver: their channel halves independently determine their lifetime.

Use new for opaque work or with_finish for a transport that can finish gracefully. Use map_future to decorate existing work without losing its finish capability.

Implementations

impl ConnectionDriver

pub fn new(future: impl Future<Output = Result<()>> + Send + 'static) -> Self

Create a driver that owns the endpoint’s lifetime.

This driver has no cooperative finish hook. A finite foreground may drop it after handing off accepted output, rather than wait for arbitrary work to finish. Reactive serving still awaits owned work after input EOF.

Custom transports that need to flush before a finite foreground returns should use with_finish instead.

pub fn with_finish( future: impl Future<Output = Result<()>> + Send + 'static, finish: impl FnOnce() + Send + 'static, ) -> Self

Create owned work that supports cooperative graceful completion.

The finish hook only requests completion; it must be nonblocking and should signal the future to stop accepting output, drain what it has already accepted, flush and close its write half, then return. It must not require independently open remote input to reach EOF. The future remains responsible for reporting I/O and flush errors.

SDK consumers invoke the hook after handing off their accepted output, then continue polling the driver until completion. There is no implicit timeout: if the adapter cannot finish, the enclosing connection remains pending and may be cancelled by its caller.

The hook is invoked at most once. Dropping the driver drops its owned future without requesting graceful completion. Dropping only the hook does not invoke it or necessarily stop the work.

Example

A custom adapter can use any signal understood by its future. For example, a one-shot channel separates the finish request from completion:

use agent_client_protocol::ConnectionDriver;
use futures::{channel::oneshot, FutureExt};

let (finish_tx, finish_rx) = oneshot::channel();
let mut driver = ConnectionDriver::with_finish(
    async move {
        if finish_rx.await.is_err() {
            // Losing the hook must not masquerade as a finish request.
            futures::future::pending::<()>().await;
        }
        // Seal the adapter's outgoing queue, drain it, and flush/close
        // the physical writer here before returning.
        Ok(())
    },
    move || { let _ = finish_tx.send(()); },
);

assert!((&mut driver).now_or_never().is_none());
assert!(driver.request_finish());
assert!(driver.request_finish()); // Supported, but the hook runs only once.
futures::executor::block_on(driver).unwrap();

pub fn map_future<F>( self, map: impl FnOnce(BoxFuture<'static, Result<()>>) -> F, ) -> Self

where F: Future<Output = Result<()>> + Send + 'static,

Decorate the owned future while preserving its finish capability.

This is useful for tracing, error annotation, or completion cleanup. Wrapping this driver in new instead would hide its finish control from the outer driver.

map is called immediately and receives the boxed future, not the driver. Its returned future must uphold the same completion contract: keep driving the original work and do not report success before accepted output is drained. An already-requested finish remains requested, and opaque work remains opaque.

use agent_client_protocol::ConnectionDriver;
use futures::FutureExt;

let driver = ConnectionDriver::new(async { Ok(()) });
let decorated = driver.map_future(|work| {
    work.inspect(|result| eprintln!("transport completed: {result:?}"))
});
futures::executor::block_on(decorated).unwrap();

pub fn request_finish(&mut self) -> bool

Request graceful completion, without waiting for it.

Returns true if this driver supports cooperative finish, including when finish was already requested. Repeated requests are idempotent: the hook runs at most once and the driver retains its graceful-finish contract across wrapping or ownership handoff.

Returns false for opaque work constructed with new; this method does not cancel that work. A true return does not prove flushing is complete: continue polling or await the driver to observe completion and any errors.

Trait Implementations

impl Debug for ConnectionDriver

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

Formats the value using the given formatter.

impl Future for ConnectionDriver

type Output = Result<(), Error>

The type of value produced on completion.

fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output>

Attempts to resolve the future to a final value, registering the current task for wakeup if the value is not yet available.