Trait Expiry

pub trait Expiry<K, V> {
    // Provided methods
    fn expire_after_create(
        &self,
        key: &K,
        value: &V,
        created_at: Instant,
    ) -> Option<Duration> { ... }
    fn expire_after_read(
        &self,
        key: &K,
        value: &V,
        read_at: Instant,
        duration_until_expiry: Option<Duration>,
        last_modified_at: Instant,
    ) -> Option<Duration> { ... }
    fn expire_after_update(
        &self,
        key: &K,
        value: &V,
        updated_at: Instant,
        duration_until_expiry: Option<Duration>,
    ) -> Option<Duration> { ... }
}

Calculates when cache entries expire. A single expiration time is retained on each entry so that the lifetime of an entry may be extended or reduced by subsequent evaluations.

Expiry trait provides three methods. They specify the expiration time of an entry by returning a Some(duration) until the entry expires:

• expire_after_create — Returns the duration (or none) after the entry’s creation.
• expire_after_read — Returns the duration (or none) after its last read.
• expire_after_update — Returns the duration (or none) after its last update.

The default implementations are provided that return None (no expiration) or current_duration: Option<Instant> (not modify the current expiration time). Override some of them as you need.

Provided Methods

fn expire_after_create( &self, key: &K, value: &V, created_at: Instant, ) -> Option<Duration>

Specifies that the entry should be automatically removed from the cache once the duration has elapsed after the entry’s creation. This method is called for cache write methods such as insert and get_with but only when the key was not present in the cache.

Parameters

• key — A reference to the key of the entry.
• value — A reference to the value of the entry.
• created_at — The time when this entry was inserted.

Return value

The returned Option<Duration> is used to set the expiration time of the entry.

• Returning Some(duration) — The expiration time is set to created_at + duration.
• Returning None — The expiration time is cleared (no expiration).
  • This is the value that the default implementation returns.

Notes on time_to_live and time_to_idle policies

When the cache is configured with time_to_live and/or time_to_idle policies, the entry will be evicted after the earliest of the expiration time returned by this expiry, the time_to_live and time_to_idle policies.

fn expire_after_read( &self, key: &K, value: &V, read_at: Instant, duration_until_expiry: Option<Duration>, last_modified_at: Instant, ) -> Option<Duration>

Specifies that the entry should be automatically removed from the cache once the duration has elapsed after its last read. This method is called for cache read methods such as get and get_with but only when the key is present in the cache.

Parameters

• key — A reference to the key of the entry.
• value — A reference to the value of the entry.
• read_at — The time when this entry was read.
• duration_until_expiry — The remaining duration until the entry expires. (Calculated by expiration_time - read_at)
• last_modified_at — The time when this entry was created or updated.

Return value

The returned Option<Duration> is used to set the expiration time of the entry.

• Returning Some(duration) — The expiration time is set to read_at + duration.
• Returning None — The expiration time is cleared (no expiration).
• Returning duration_until_expiry will not modify the expiration time.
  • This is the value that the default implementation returns.

Notes on time_to_live and time_to_idle policies

When the cache is configured with time_to_live and/or time_to_idle policies, then:

• The entry will be evicted after the earliest of the expiration time returned by this expiry, the time_to_live and time_to_idle policies.
• The duration_until_expiry takes in account the time_to_live and time_to_idle policies.

fn expire_after_update( &self, key: &K, value: &V, updated_at: Instant, duration_until_expiry: Option<Duration>, ) -> Option<Duration>

Specifies that the entry should be automatically removed from the cache once the duration has elapsed after the replacement of its value. This method is called for cache write methods such as insert but only when the key is already present in the cache.

Parameters

• key — A reference to the key of the entry.
• value — A reference to the value of the entry.
• updated_at — The time when this entry was updated.
• duration_until_expiry — The remaining duration until the entry expires. (Calculated by expiration_time - updated_at)

Return value

The returned Option<Duration> is used to set the expiration time of the entry.

• Returning Some(duration) — The expiration time is set to updated_at + duration.
• Returning None — The expiration time is cleared (no expiration).
• Returning duration_until_expiry will not modify the expiration time.
  • This is the value that the default implementation returns.

Notes on time_to_live and time_to_idle policies

When the cache is configured with time_to_live and/or time_to_idle policies, then:

• The entry will be evicted after the earliest of the expiration time returned by this expiry, the time_to_live and time_to_idle policies.
• The duration_until_expiry takes in account the time_to_live and time_to_idle policies.

Implementors