Struct bkt::Bkt

source · []
pub struct Bkt { /* private fields */ }
Expand description

This struct is the main API entry point for the bkt library, allowing callers to invoke and cache subprocesses for later reuse.


Creates a new Bkt instance using the std::env::temp_dir as the cache location. If a BKT_TMPDIR environment variable is set that value will be preferred.


If preparing the tmp cache directory fails.

Creates a new Bkt instance.

The given root_dir will be used as the parent directory of the cache. It’s recommended this directory be in a tmpfs partition, on an SSD, or similar, so operations are fast.


If preparing the cache directory under root_dir fails.

Associates a scope with this Bkt instance, causing it to namespace its cache keys so that they do not collide with other instances using the same cache directory. This is useful when separate applications could potentially invoke the same commands but should not share a cache. Consider using the application’s name, PID, and/or a timestamp in order to create a sufficiently unique namespace.

By default a background cleanup thread runs on cache misses and calls to Bkt::refresh() to remove stale data. You may prefer to manage cleanup yourself if you expect frequent cache misses and want to minimize the number of threads being created. See Bkt::cleanup_once() and Bkt::cleanup_thread() if you set this to false.

Configures this instance to not cache invocations that return non-zero exit codes. This only affects writing to the cache; if a failed invocation has already been cached (e.g. by a different instance) that data will still be used until it expires.

WARNING: use this function with caution. Discarding invocations that fail can overload downstream resources that were protected by the caching layer limiting QPS. For example, if a website is rejecting a fraction of requests to shed load and then clients start sending more requests when their attempts fail the website could be taken down outright by the added load. In other words, using this function can lead to accidental DDoSes.

Looks up the given command in Bkt’s cache, returning it, and its age, if found and newer than the given TTL.

If stale or not found the command is executed and the result is cached and then returned. A zero-duration age will be returned if this invocation refreshed the cache.


If looking up, deserializing, executing, or serializing the command fails. This generally reflects a user error such as an invalid command.

Unconditionally executes the given command and caches the invocation for the given TTL. This can be used to “warm” the cache so that subsequent calls to execute are fast.


If executing or serializing the command fails. This generally reflects a user error such as an invalid command.

Initiates a single cleanup cycle of the cache, removing stale data in the background. This should be invoked by short-lived applications early in their lifecycle and then joined before exiting. execute_and_cleanup can be used instead to only trigger a cleanup on a cache miss, avoiding the extra work on cache hits. Long-running applications should typically prefer cleanup_thread which triggers periodic cleanups.


The Result returned by joining indicates whether there were any unexpected errors while cleaning up. It should be Ok in all normal circumstances.

Initiates an infinite-loop thread that triggers periodic cleanups of the cache, removing stale data in the background. It is not necessary to join() this thread, it will be terminated when the main thread exits.

Trait Implementations

Returns a copy of the value. Read more

Performs copy-assignment from source. Read more

Formats the value using the given formatter. Read more

Auto Trait Implementations

Blanket Implementations

Gets the TypeId of self. Read more

Immutably borrows from an owned value. Read more

Mutably borrows from an owned value. Read more

Returns the argument unchanged.

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

The resulting type after obtaining ownership.

Creates owned data from borrowed data, usually by cloning. Read more

🔬 This is a nightly-only experimental API. (toowned_clone_into)

Uses borrowed data to replace owned data, usually by cloning. Read more

The type returned in the event of a conversion error.

Performs the conversion.

The type returned in the event of a conversion error.

Performs the conversion.