Struct CacheBuilder 

pub struct CacheBuilder<K, V, W = ItemCountWeighter, H = FastBuildHasher> { /* private fields */ }

Builder for creating a Cache.

Implementations

impl<K, V> CacheBuilder<K, V>

pub fn from_identifier<N: Into<String>>( identifier: N, ) -> Result<CacheBuilder<K, V>, GenericError>

Creates a new CacheBuilder with the given cache identifier.

The cache identifier should be unique, but it is not required to be. Metrics for the cache will be emitted using the given identifier, so in cases where the identifier is not unique, those metrics will be aggregated together and it will not be possible to distinguish between the different caches.

Errors

If the given cache identifier is empty, an error is returned.

pub fn for_tests() -> CacheBuilder<K, V>

Configures a CacheBuilder that is suitable for tests.

This configures the builder with the following defaults:

• cache identifier of “noop”
• unlimited cache size
• telemetry disabled

This is generally only useful for testing purposes, and is exposed publicly in order to be used in cross-crate testing scenarios.

impl<K, V, W, H> CacheBuilder<K, V, W, H>

pub fn with_capacity(self, capacity: NonZeroUsize) -> Self

Sets the capacity for the cache.

The capacity is used, in conjunction with the item weighter, to determine how many items can be held in the cache and when items should be evicted to make room for new items.

See with_item_weighter for more information on how the item weighter is used.

Defaults to unlimited capacity.

pub fn with_time_to_idle(self, idle_period: Option<Duration>) -> Self

Enables expiration of cached items based on how long since they were last accessed.

Items which have not been accessed within the configured duration will be marked for expiration, and be removed from the cache shortly thereafter. For the purposes of expiration, “accessed” is either when the item was first inserted or when it was last read.

If the given value is None, expiration is disabled.

Defaults to no expiration.

pub fn with_expiration_interval(self, expiration_interval: Duration) -> Self

Sets the interval at which the expiration process will run.

This controls how often the expiration process will run to check for expired items. While items become eligible for expiration after the configured duration, they are not guaranteed to be removed immediately: the expiration process must still run to actually find the expired items and remove them.

This means that the rough upper bound for how long an item may be kept alive is the sum of both the configured expiration duration and the expiration interval.

This value is only relevant if expiration is enabled.

Defaults to 1 second.

pub fn with_item_weighter<W2>(self, weighter: W2) -> CacheBuilder<K, V, W2, H>

Sets the item weighter for the cache.

The item weighter is used to determine the “weight” of each item in the cache, which is used during insertion/eviction to determine if an item can be held in the cache without first having to evict other items to stay within the configured capacity.

For example, if the configured capacity is set to 10,000, and the “item count” weighter is used, then the cache will operate in a way that aims to simply ensure that no more than 10,000 items are held in the cache at any given time. This allows defining custom weighters that can be used to track other aspects of the items in the cache, such as their size in bytes, or some other metric that is relevant to the intended caching behavior.

Defaults to “item count” weighter.

pub fn with_hasher<H2>(self) -> CacheBuilder<K, V, W, H2>

Sets the item hasher for the cache.

As cache keys are hashed before performing any reads or writes, the chosen hasher can potentially impact the performance of those operations. In some scenarios, it may be desirable to use a different hasher than the default one in order to optimize for specific key types or access patterns.

Defaults to a fast, non-cryptographic hasher: FastBuildHasher.

pub fn with_telemetry(self, enabled: bool) -> Self

Sets whether or not to enable telemetry for this cache.

Reporting the telemetry of the cache requires running an asynchronous task to override adding additional overhead in the hot path of reading or writing to the cache. In some cases, it may be cumbersome to always create the cache in an asynchronous context so that the telemetry task can be spawned. This method allows disabling telemetry reporting in those cases.

Defaults to telemetry enabled.

impl<K, V, W, H> CacheBuilder<K, V, W, H>

where K: Eq + Hash + Clone + Send + Sync + 'static, V: Clone + Send + Sync + 'static, W: Weighter<K, V> + Clone + Send + Sync + 'static, H: BuildHasher + Clone + Default + Send + Sync + 'static,

pub fn build(self) -> Cache<K, V, W, H>

Builds a Cache from the current configuration.