Trait SharedResource 

pub trait SharedResource:
    Send
    + Sync
    + 'static {
    // Required method
    fn resource_key(&self) -> &ResourceKey;

    // Provided methods
    fn can_share(&self) -> bool { ... }
    fn can_support_more_load(&self) -> bool { ... }
    fn init(&self) -> ResourceFuture<'_, Result<(), String>> { ... }
    fn close(self: Arc<Self>) -> ResourceFuture<'static, Result<(), String>> { ... }
    fn as_legacy_adapter(&self) -> Option<Arc<dyn DriverAdapter>> { ... }
    fn accessor_payload(&self) -> Option<Arc<dyn Any + Send + Sync>> { ... }
}

The trait every poolable resource implements.

Send + Sync + 'static is required so the pool can hold Arc<dyn SharedResource> and clone it across fibers.

Default implementations make the trivial case (always-shareable, never-saturated, no-op init/close) boilerplate-free — only resource_key() is required to override.

Required Methods

fn resource_key(&self) -> &ResourceKey

The structural identity of this resource.

Provided Methods

fn can_share(&self) -> bool

Capability — does this instance support being shared by multiple adapter shells concurrently? Default true. See SRD-35 §“Two trait methods on the live resource”.

fn can_support_more_load(&self) -> bool

Live capacity — can this instance accept another concurrent caller right now without substantial contention?

true (default) → “yes, route the next attach to me; I have capacity.” false → “no, I’m saturated; the pool should spawn a sibling for the new attach.” Parallel naming to can_share(): can_share() says whether sharing is structurally possible at all; can_support_more_load() says whether one more caller is OK at this moment.

Drivers that override MUST document their decision criterion in the type docstring (the operator reading a reason=capacity-declined lifecycle event needs to be able to interpret what triggered it). MUST be cheap (atomic read or short metric query); MUST NOT block. SRD-35 §“Validity rules” requires the body to reflect current in-flight load — never historical/peak/lifetime metrics. The pool’s guard in [needs_sibling_spawn] catches the historical-state failure mode (driver returns false at quiescence) and emits a Warn event so operators can spot the driver bug.

fn init(&self) -> ResourceFuture<'_, Result<(), String>>

Optional async init beyond what construction already did. Called by the pool on first attach for a key, exactly once per (key, generation).

fn close(self: Arc<Self>) -> ResourceFuture<'static, Result<(), String>>

Symmetric teardown. Called when the entry’s refcount hits zero. MUST block until network / kernel resources are actually released — no async-Drop races, no sockets in TIME_WAIT being counted as closed, no libuv worker thread races.

fn as_legacy_adapter(&self) -> Option<Arc<dyn DriverAdapter>>

Bridge for the Push A legacy-adapter shim. Default returns None; only LegacyAdapterResource overrides it to surface its wrapped DriverAdapter handle. Push B retires this entirely once each adapter has its own SharedResource impl with no hidden DriverAdapter inside.

Real SharedResource implementations should leave this at the default — the pool layer is the right place to surface domain-specific handles, not the trait surface.

fn accessor_payload(&self) -> Option<Arc<dyn Any + Send + Sync>>

SRD-104 — the resource’s accessor payload: a type-erased handle (Arc<dyn Any + Send + Sync>) a kernel node can obtain by fingerprint through its kernel tree’s resource scope. The pool stores it on the entry right after a successful init, and its polydat::ResourceAccessor impl hands out clones. Default None — a resource opts in only when it wants kernels to reach a live handle (the first consumer is a CQL session handle, SRD-103); no existing adapter is affected.

Dyn Compatibility

This trait is dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors

impl SharedResource for LegacyAdapterResource

impl SharedResource for SharedAdapterResource