Struct PoolClient 

pub struct PoolClient { /* private fields */ }

A thin UDS client for communicating with a pool worker process.

Each PoolClient instance owns a single Unix domain socket connection to one worker. Messages are JSON lines (\n-terminated).

Lifecycle

1. Call PoolClient::connect — opens the socket and runs the version handshake atomically. If the handshake fails the connection is dropped and an error is returned; no PoolClient instance is produced.
2. Call PoolClient::send_request for each message.
3. Drop the PoolClient when done; the underlying socket is closed.

Implementations

impl PoolClient

pub async fn connect(sock_path: &Path) -> Result<Self, PoolError>

Open a connection to a worker at sock_path and verify protocol version.

The handshake (PoolRequest::Handshake) is performed inside this call. If the worker reports a different version, Err(PoolError::VersionMismatch) is returned and no PoolClient is constructed.

Concurrency

Cancel safety: this function is not cancel safe. If dropped before recv_line completes, the internal BufReader may hold a partial line; the partial connection is dropped and must not be reused.

Timeout: the handshake recv is bounded by HANDSHAKE_RECV_TIMEOUT (10 s). If the worker does not respond within this window, the function returns Err(PoolError::Handshake("handshake recv timeout (10s)")) and the connection is dropped. This prevents RunningService::cancel from hanging when a worker fails to send the handshake.

Send + Sync: PoolClient is Send (all fields are Send). It is not Sync — callers sharing across tasks must wrap in Arc<tokio::sync::Mutex<PoolClient>>.

Errors

• PoolError::Connect — socket connect failed (wraps std::io::Error).
• PoolError::Handshake — response could not be parsed as valid JSON, or the handshake recv timed out after 10 s.
• PoolError::VersionMismatch — worker version differs from client version.

pub async fn send_request( &mut self, req: PoolRequest, ) -> Result<PoolResponse, PoolError>

Send a PoolRequest over the Unix domain socket and await the response.

Serialises the request to a JSON line (\n-terminated), writes it via tokio::io::AsyncWriteExt::write_all, then reads the response with tokio::io::AsyncBufReadExt::read_line.

Concurrency

Cancel safety: this function is not cancel safe. AsyncBufReadExt::read_line is not cancel safe per tokio documentation: if this future is dropped before read_line completes, the internal buffer may hold a partial line. After cancellation the connection is no longer usable; callers must drop this PoolClient and reconnect.

Mutex serialisation: the internal tokio::sync::Mutex<Inner> serialises concurrent callers. Cancelling a lock().await call loses queue position (tokio docs: “Cancelling a call to lock makes you lose your place in the queue”). Only one request can be in-flight per PoolClient instance at a time. Holding the guard across .await (write + flush + read_line) is intentional and correct with tokio::sync::Mutex.

Send + Sync: PoolClient is Send (all fields are Send). It is not Sync — callers sharing across tasks must wrap in Arc<tokio::sync::Mutex<PoolClient>>.

Panics

Does not panic.

Trait Implementations

impl Debug for PoolClient

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

Formats the value using the given formatter.