Module resource_pool 

Generic resource lifecycle and sharing pool — SRD-35 Push A.

What this module provides

Trait surface and runtime structure for sharing long-lived resources (CQL sessions, HTTP clients, …) across phases of one session, decoupled from per-phase adapter shells. The contract is intentionally generic — nothing here is CQL-specific.

Core types

• SharedResource — the trait every poolable resource implements. Carries SharedResource::can_share (capability declaration: thread-safe + designed for sharing) and SharedResource::can_support_more_load (driver’s runtime judgement that another instance would relieve knowable, substantial contention) — see the SRD-35 load-bearing rules.
• ResourceKey — value-equality identity. Two keys compare equal iff their adapter name and fields match exactly. No derived hash function; the contract is structural.
• ShareCapability — strictest sharing the resource type tolerates. Read by the pool at planning time without an instance.
• ResourceSharePolicy — user-elevatable isolation policy. Must satisfy policy >= capability_floor.
• ResourcePool — owns the (ResourceKey, generation) → Entry map, tracks refcounts, emits lifecycle events.

Push A scope

Push A lays the trait foundation, the pool data structure, the lifecycle event emission, and a LegacyAdapterResource shim that wraps the existing Arc<dyn DriverAdapter> factories under PerPhase policy. Behaviour is byte-identical to today (a fresh resource per phase) but every phase boundary now emits the full resource.{attach,init,detach,close} event sequence.

Push B will migrate the CQL adapter to Shared policy by splitting CqlAdapter into a per-phase shell + a CassDriverInstance that implements SharedResource directly with real async close(). The pool’s multi-generation machinery is in place but exercised only by the synthetic mock resource in tests until then.

Structs

AttachGuard

Owns an attached resource for the duration of one phase activation. Drop emits resource.detach and, when the entry’s refcount has fully drained, schedules an async close() (and emits resource.close.* events around it).

LegacyAdapterResource

Wraps an Arc<dyn DriverAdapter> from the existing per-phase factory under PerPhase policy. Used until each adapter migrates to a real SharedResource impl (Push B for CQL, Push C for HTTP / OpenAPI / stdout).

ResourceFactory

Closure-shaped factory for building a resource the first time its key is attached. Boxed so the pool can hold it across .await points and so callers don’t have to type the future signature inline.

ResourceKey

Structural value identity for a shared resource.

ResourcePool

One (ResourceKey, generation) map for the lifetime of one session. Owns lazy init, refcount transitions, and the close trigger.

SharedAdapterResource

Push B sibling of LegacyAdapterResource — wraps an Arc<dyn DriverAdapter> but declares can_share()=true. Used when an adapter has registered a crate::adapter::SharedDriverRegistration opting it into pool-shared semantics. The pool caches the underlying Arc<dyn DriverAdapter> and hands the same clone to every phase whose params produce the same ResourceKey.

Enums

ResourceSharePolicy

User-selectable isolation. Must satisfy policy >= capability_floor.

ShareCapability

Strongest sharing the resource type can tolerate. Declared by the factory at registration time so the pool can plan the entry layout without configuring or instantiating any resource. The live instance’s SharedResource::can_share is a runtime safety net that aborts the session if it disagrees with this type-level declaration.

Traits

SharedResource

The trait every poolable resource implements.

Functions

attach

Public attach call. Builds (or reuses) the entry for key under policy, lazily realises the resource via factory if this is the first attach, emits resource.attach, and returns a guard that detaches on drop.

attach_legacy_adapter

Push A high-level helper for the executor: attach a legacy adapter through the pool under PerPhase policy and return both the unwrapped Arc<dyn DriverAdapter> and the corresponding AttachGuard.

attach_shared_adapter

Push B high-level helper: attach a shareable adapter through the pool under Shared policy. The first phase whose params produce key triggers factory; every subsequent matching phase reuses the same Arc<dyn DriverAdapter>. Each call returns a fresh guard; the pool’s refcount drops the entry only when every guard is released.

capability_floor

Minimum policy compatible with the given capability. Used by the pool to validate user-supplied policies at session start.

default_policy_for

Default sharing policy — the strongest sharing the capability allows. Used when the user gives no override.

install_accessor

SRD-104 — point the resource bridge at pool. Called once at session start where the ResourcePool is created.

pool_resources

A resource scope with the pool bridge installed: what every nmbrs kernel tree is compiled with at its root (crate::bindings::compile_scope_kernel). A kernel bound under the tree joins its scope, so a node anywhere in it that captured ctx.resources() resolves pool resources by key.

pre_map_pending_uses

Walk the freshly-pre-mapped scenario tree and seed the pool’s pending_uses counter for every phase that will attach a pool-shareable adapter. Called once at session bootstrap, after [crate::executor::pre_map_tree] returns and before the executor begins running any phase.

Type Aliases

ResourceFuture

One async-init-and-close return type used by the trait. Returns a Send future so the pool can hold it across .await points without runtime fuss.