Lease

d_engine_core::storage

Trait Lease 

Source 
pub trait Lease:
    Send
    + Sync
    + 'static {
    // Required methods
    fn register(&self, key: Bytes, ttl_secs: u64);
    fn unregister(&self, key: &[u8]);
    fn is_expired(&self, key: &[u8]) -> bool;
    fn get_expired_keys(&self, now: SystemTime) -> Vec<Bytes>;
    fn on_apply(&self) -> Vec<Bytes>;
    fn has_lease_keys(&self) -> bool;
    fn may_have_expired_keys(&self, now: SystemTime) -> bool;
    fn len(&self) -> usize;
    fn to_snapshot(&self) -> Vec<u8> ⓘ;
    fn reload(&self, data: &[u8]) -> Result<()>;

    // Provided method
    fn is_empty(&self) -> bool { ... }
}
Expand description

Lease management interface for key expiration.

Manages key lifecycles through time-based leases. d-engine provides a default implementation (DefaultLease in d-engine-server), but developers can implement custom lease management strategies.

§Thread Safety

All methods must be thread-safe as they will be called concurrently from:

  • Read path: Multiple concurrent client reads
  • Write path: Single-threaded apply operations

§Performance Requirements

  • is_expired(): Must be O(1) and lock-free (hot path, called on every read)
  • register() / unregister(): Should be O(log N) or better
  • get_expired_keys(): Should be O(K log N) where K = expired keys

§Example Implementation

ⓘ
use d_engine_core::storage::Lease;
use bytes::Bytes;
use std::time::SystemTime;

struct MyCustomLease {
    // Your data structures
}

impl Lease for MyCustomLease {
    fn register(&self, key: Bytes, ttl_secs: u64) {
        // Your implementation
    }

    fn is_expired(&self, key: &[u8]) -> bool {
        // Your implementation
    }

    // ... other methods
}

Required Methods§

Source

fn register(&self, key: Bytes, ttl_secs: u64)

Register a lease for a key.

If the key already has a lease, updates to the new expiration time.

§Arguments
  • key - Key to set expiration for
  • ttl_secs - Time-to-live in seconds from now
§Performance

Should be O(log N) or better. Called on every insert with TTL.

Source

fn unregister(&self, key: &[u8])

Remove lease for a key (on update/delete).

Called when a key is updated without TTL or explicitly deleted.

§Performance

Should be O(log N) or better.

Source

fn is_expired(&self, key: &[u8]) -> bool

Check if a key’s lease has expired.

§Returns
  • true - Key has expired and should be treated as non-existent
  • false - Key has not expired or has no lease
§Performance

CRITICAL: Must be O(1) and lock-free. This is the hot path, called on every read operation.

Source

fn get_expired_keys(&self, now: SystemTime) -> Vec<Bytes>

Get all keys with expired leases.

Removes returned keys from internal lease indexes.

§Arguments
  • now - Current time to check expiration against
§Returns

List of expired keys (keys are removed from lease tracking)

§Performance

Should be O(K log N) where K = number of expired keys.

Source

fn on_apply(&self) -> Vec<Bytes>

Called on every apply operation (piggyback cleanup).

The lease implementation decides internally whether to perform cleanup based on its configuration (e.g., piggyback strategy with frequency control).

§Returns

List of expired keys that were cleaned up (may be empty)

§Performance

Should be O(1) most of the time (fast path when not cleaning).

Source

fn has_lease_keys(&self) -> bool

Check if any key has ever been registered with a lease.

Used for fast-path optimization to skip lease logic entirely when leases are not used.

§Returns
  • true - At least one key has been registered (even if expired)
  • false - No keys have ever been registered
§Performance

Must be O(1) - simple flag check.

Source

fn may_have_expired_keys(&self, now: SystemTime) -> bool

Fast check: returns true if there might be expired keys.

This is an O(1) optimization to avoid full expired key scan.

§Returns
  • false - Definitely no expired keys (fast path)
  • true - Maybe has expired keys (need full check)
§Performance

Should be O(1) or O(log N) at most.

Source

fn len(&self) -> usize

Get number of keys with active leases.

§Performance

Should be O(1).

Source

fn to_snapshot(&self) -> Vec<u8> ⓘ

Serialize lease state for snapshot.

Used by Raft snapshot mechanism to persist lease metadata.

§Returns

Serialized bytes (format is implementation-defined)

Source

fn reload(&self, data: &[u8]) -> Result<()>

Reload lease state from snapshot data.

Used during snapshot restoration. Should filter out already-expired leases.

§Arguments
  • data - Serialized snapshot data
§Errors

Returns error if deserialization fails.

Provided Methods§

Source

fn is_empty(&self) -> bool

Check if no keys have active leases.

Implementors§