Struct Bkt

pub struct Bkt { /* private fields */ }

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

Example:

let bkt = bkt::Bkt::in_tmp()?;
let cmd = bkt::CommandDesc::new(["curl", "https://expensive.api/foo"]);
let (result, age) = bkt.retrieve(&cmd, Duration::from_secs(60*60))?;
println!("Retrieved: {:?}\nAge: {:?}", result, age);

Implementations

impl Bkt

pub fn in_tmp() -> Result<Self>

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.

Errors

If preparing the tmp cache directory fails.

pub fn create(root_dir: PathBuf) -> Result<Self>

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.

Errors

If preparing the cache directory under root_dir fails.

pub fn scoped(self, scope: String) -> Self

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.

pub fn cleanup_on_refresh(self, cleanup: bool) -> Self

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.

pub fn retrieve<T>( &self, command: T, ttl: Duration, ) -> Result<(Invocation, CacheStatus)>

where T: TryInto<CommandState>, Error: From<T::Error>,

Looks up the given command in Bkt’s cache. If found (and newer than the given TTL) returns the cached invocation. If stale or not found the command is executed and the result is cached and then returned.

The second element in the returned tuple reports whether or not the invocation was cached and includes information such as the cached data’s age or the executed subprocess’ runtime.

Errors

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

pub fn retrieve_streaming<T>( &self, command: T, ttl: Duration, stdout_sink: impl Write + Send, stderr_sink: impl Write + Send, ) -> Result<(Invocation, CacheStatus)>

where T: TryInto<CommandState>, Error: From<T::Error>,

Experimental This method is subject to change.

Looks up the given command in Bkt’s cache. If found (and newer than the given TTL) returns the cached invocation. If stale or not found the command is executed and the result is cached and then returned. Additionally, the invocation’s stdout and stderr are written to the given streams in real time.

The second element in the returned tuple reports whether or not the invocation was cached and includes information such as the cached data’s age or the executed subprocess’ runtime.

Errors

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

pub fn refresh<T>( &self, command: T, ttl: Duration, ) -> Result<(Invocation, Duration)>

where T: TryInto<CommandState>, Error: From<T::Error>,

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.

The second element in the returned tuple is the subprocess’ execution time.

Errors

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

pub fn refresh_streaming<T>( &self, command: T, ttl: Duration, stdout_sink: impl Write + Send, stderr_sink: impl Write + Send, ) -> Result<(Invocation, Duration)>

where T: TryInto<CommandState>, Error: From<T::Error>,

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. The invocation’s stdout and stderr are written to the given streams in real time in addition to being cached.

The second element in the returned tuple is the subprocess’ execution time.

Errors

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

pub fn cleanup_once(&self) -> JoinHandle<Result<()>>

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.

Errors

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

pub fn cleanup_thread(&self) -> JoinHandle<()>

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

impl Clone for Bkt

fn clone(&self) -> Bkt

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for Bkt

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.