Expand description
qorb is a connection pooling crate.
qorb offers a flexible interface for managing connections.
It uses the following terminology:
- Services are named entities providing the same interface.
- Backends are specific instantiations of a program, providing a service. In the case of, e.g., a distributed database, a single service would be provided by multiple backends.
§Usage
- The main interface for this crate is pool::Pool.
- To construct a pool, you must supply a resolver::Resolver and a backend::Connector. These are interfaces which specify “how to find backends” and “how to create connections to a backend”, respectively.
§DTrace probes
qorb contains a number of DTrace USDT probes, which fire as the qorb pool manages its connections. These probes provide visibility into when qorb initiates connections; checks health; and vends out claims from a pool. The full list of probes is:
claim-start: Fires before attempting to make take a claim from the pool.claim-done: Fires before returning a successful claim to the client.claim-failed: Fires on failure to take a claim from the pool.connect-start: Fires before attempting a connection to a backend.connect-done: Fires after successfully connecting to a backend.connect-failed: Fires after failing to connect to a backend.handle-claimed: Fires after claiming a handle from the pool, before returning it to the client.handle-recycled: Fires when a handle is returned to the pool, after it is dropped.health-check-start: Fires when a health check for a backend starts.health-check-done: Fires when a health check for a backend completes successfully.health-check-failed: Fires when a health check for a backend fails.recycle-start: Fires before attempting to recycle a connection.recycle-done: Fires after successsfully recycling a connection.recycle-failed: Fires when failing to recycle a connection.
The existence of the probes is behind the "probes" feature, which is
enabled by default. Probes are zero-cost unless they are explicitly enabled,
by tracing the program with the dtrace(1) command-line tool.
On most systems, the USDT probes must be registered with the DTrace kernel
module. This process is technically fallible, although extremely unlikely to
fail in practice. To account for this, the pool::Pool::new constructor is
fallible, returning an Err if registration fails. However, it’s very
context-dependent what one wants to do with this failure – some
applications may choose to panic, while others would rather have a pool that
can’t be instrumented rather than no pool at all.
To support both of these cases, the Result returned from pool::Pool::new
gives access to the pool itself in both the Ok or Err variant. Some
applications may just unwrap() or propagate an error, while others may
choose to extract the pool in either case. (This is similar to the
std::sync::PoisonError.)
Modules§
- backend
- The interface for identifying and connecting to backend services.
- claim
- Connections which are borrowed from the connection pool.
- connectors
- Default implementations of crate::backend::Connector
- policy
- Configuration options which can alter the behavior of the pool.
- pool
- A pool which uses a resolver to find a backend, and vend out a claim
- resolver
- The interface for the resolver, which finds backends.
- resolvers
- Default implementations of crate::resolver::Resolver
- service
- Interface for services
- slot