Trait Connection 

pub trait Connection:
    Sized
    + Send
    + Sync {
    type Context: Send + Sync;
    type Error: Send + Sync;

    // Required methods
    fn create(
        ctx: &Self::Context,
    ) -> impl Future<Output = Result<Self, Self::Error>> + Send + Sync;
    fn needs_health_check(&mut self, ctx: &Self::Context) -> bool;
    fn health_check(
        &mut self,
        ctx: &Self::Context,
    ) -> impl Future<Output = Result<(), Self::Error>> + Send + Sync;
}

Connection Management

The Connection trait defines an asynchronous interface for managing connections in a concurrent environment. Implementors of this trait can represent any form of connection, such as to a database, network service, or any other resource that requires managing a persistent connection state.

Example

use swimming::Connection;

struct MyConn;

impl Connection for MyConn {
    type Context = ();
    type Error = ();

    async fn create(_ctx: &()) -> Result<Self, ()> {
        Ok(MyConn)
    }

    fn needs_health_check(&mut self, _ctx: &()) -> bool {
        // always perform a health check.
        // (in practice you would want to check if conn is stale)
        true
    }

    async fn health_check(&mut self, _ctx: &()) -> Result<(), ()> {
        // MyConn is always healthy. (In practice you'd do something like ping the server)
        Ok(())
    }
}

Required Associated Types

type Context: Send + Sync

The state of the pool, passed to the Connection methods. Generally useful for storing details pertinent to the connection.

type Error: Send + Sync

The error type that operations of this trait may return.

Required Methods

fn create( ctx: &Self::Context, ) -> impl Future<Output = Result<Self, Self::Error>> + Send + Sync

Create Connection

Creates a new instance of the connection asynchronously. This method should handle the necessary initialization for the connection, such as establishing a network connection, authenticating, or any other setup required before the connection can be used.

Returns

• Ok(Self): The connection was successfully created and setup.
• Err(Self::Error): There was an error creating / setting up the connection.

fn needs_health_check(&mut self, ctx: &Self::Context) -> bool

Needs Health Check

Performs a quick, lightweight check to determine whether a more comprehensive health check health_check needs to be run. This method is intended to be fast and should not perform any heavy computations or network operations.

Returns

• true: A full health_check is warranted.
• false: The connection is fine to use without any health check.

fn health_check( &mut self, ctx: &Self::Context, ) -> impl Future<Output = Result<(), Self::Error>> + Send + Sync

Health Check

Asynchronously checks the health of the connection, verifying that it is still viable for use. This method should be implemented to perform any necessary checks to ensure the connection’s integrity and operational status, such as sending a ping to a server or validating a session token.

If this fails, the pool will attempt to create a new connection. If this is not possible the pool will return the Error from the create implementation to threads requesting connections.

Implementors should ensure that needs_health_check is as efficient as possible to avoid degrading performance. The health_check method may involve asynchronous operations and should be prepared to handle timeouts and other common network-related issues gracefully.

Returns

• Ok(()): The connection is OK to continue using.
• Err(Self::Error): The connection needs to be restarted.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors