Struct ResourceRegistry 

pub struct ResourceRegistry { /* private fields */ }

A registry for scarce, externally backed resources.

In many cases, data planes will have to interact with the outside world by way of exposing network endpoints, or exposing files, and so on… referred to here as “resources.” These resources are unique, or are conceptually meant to be unique: there should be no other OS processes trying to take ownership of them, and only one part of the code in the data plane should own them.

A ResourceRegistry owns those resources on behalf of the entire data plane and lends them out. A child process never owns a resource, but instead holds a ResourceLease. When the lease drops – including when the child process holding it dies – the resource returns to the registry intact and still live, ready for the next acquirer. Since the registry outlives the components that use its resources, a component can be torn down and rebuilt without the underlying resource being automatically released back to the operating system due to typical Rust drop semantics.

Groups

Resources are named by a ResourceSpecification, which provides the blueprint for how to create a particular resource, such as a network socket, when a caller attempts to acquire it. Resource specifications are generally tied one-to-one with a particular type.

The specification provides both the information necessary to properly determine one unique resource from another, as well as a mechanism for consistent creation of potentially complex resources, including asynchronous initialization.

Keys and conflicts

Entries are keyed by kind and key together, deliberately not by resource type. Two different Rust types can easily describe the same scarce thing – a connection-oriented listener and a general one over the same address – and keying by type would let each of them claim it. Kind is coarse enough that such representations still collide, while keeping unrelated resource families from colliding on a coincidentally equal key. A key therefore only has to be unique within its own kind.

Implementations

impl ResourceRegistry

pub fn new() -> Self

Creates an empty registry.

pub async fn acquire<S: ResourceSpecification>( &self, owner: &SubsystemIdentifier, spec: S, ) -> Result<ResourceLease<S::Resource>, AcquireError>

Acquires the resource named by spec, creating it if it isn’t registered yet.

owner identifies the subsystem taking the lease and is recorded, alongside the current process identifier, for accounting.

If the resource is already registered, the existing one is handed back rather than a new one being created. This is the mechanism by which a resource outlives the components that use it.

Errors

If the resource is already leased, if the key is registered to a different type of resource, or if creation fails, an error is returned.

pub fn snapshot(&self) -> Vec<ResourceStatus>

Returns a snapshot of every registered resource, ordered by key.

pub fn api_handler(&self) -> ResourceRegistryAPIHandler

Creates an API handler for reporting the state of all registered resources.

pub fn worker(&self) -> ResourceRegistryWorker

Creates a ResourceRegistryWorker that publishes the registry over the control plane.

Trait Implementations

impl Clone for ResourceRegistry

fn clone(&self) -> ResourceRegistry

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Default for ResourceRegistry

fn default() -> ResourceRegistry

Returns the “default value” for a type.