Trait ResourceSpecification 

pub trait ResourceSpecification:
    Clone
    + Debug
    + Send
    + Sync
    + 'static {
    type Resource: Send + 'static;

    const KIND: ResourceKind;

    // Required methods
    fn key(&self) -> MetaString;
    fn create<'life0, 'async_trait>(
        &'life0 self,
        subleases: Subleases,
    ) -> Pin<Box<dyn Future<Output = Result<Self::Resource, GenericError>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait;

    // Provided method
    fn reset(_resource: &mut Self::Resource) { ... }
}

A specification naming one resource, and the blueprint for creating it.

A specification describes what to create without creating it, so it can be built and compared long before the underlying resource exists. It also names exactly one resource type, which is what keeps two callers from acquiring the same resource as two different types: there is no way to express the mismatch.

Required Associated Constants

const KIND: ResourceKind

Kind of the resource this specification names.

Required Associated Types

type Resource: Send + 'static

Type of the resource this specification creates.

Required Methods

fn key(&self) -> MetaString

Returns the key for the resource this specification names.

Keys must be unique within their kind: two specifications of the same kind that yield the same key are understood to name the same underlying scarce thing and will conflict with each other. Keys of different kinds never collide, so a key only has to distinguish a resource from its siblings.

Only the parts of a specification that identify the underlying thing belong in the key. Settings that do not change which resource is named should be left out, so that two specifications differing only in their settings are correctly recognized as naming the same resource.

fn create<'life0, 'async_trait>( &'life0 self, subleases: Subleases, ) -> Pin<Box<dyn Future<Output = Result<Self::Resource, GenericError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Creates the resource.

A resource that is only meaningful as a set of underlying handles – several sockets bound to one address with SO_REUSEPORT, say – holds all of them itself. Creating them together in a single call is what makes them atomic: if any one fails, this returns an error and nothing is registered.

subleases issues subleases on the resource, for a resource that hands out subresources able to outlive the lease they came from – a connectionless listener lending the bound socket underneath it to every stream it yields, say. Keep it on the resource and issue one per subresource; outstanding subleases keep the resource from being handed to another acquirer. A resource that is never subdivided has no use for it.

Errors

If the resource can’t be created, an error is returned and nothing is registered.

Provided Methods

fn reset(_resource: &mut Self::Resource)

Prepares a returning resource for its next holder.

Called once a returned resource has no subleases outstanding, immediately before it is handed to its next holder – so it runs knowing the previous holder is genuinely finished, including with anything it lent out. Implement this only for a resource that accumulates state over the course of a single lease and must start clean for the next one – a listener tracking how many of its pre-bound sockets it has handed out, for example. Everything the resource is for, such as the sockets themselves, must survive: the point of the registry is that it outlives its holders.

Defaults to doing nothing, which is right for a resource that carries no per-lease state.

This is deliberately infallible. A resource that can’t be made fit for reuse should be discarded by its holder instead, so the next acquisition builds a fresh one.

Panics

Don’t. A panic here aborts the acquisition that triggered it, and the resource goes back to the registry intact but only partly reset, so the next acquisition gets the same resource and runs the same reset again.

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