Struct BucketLease 

pub struct BucketLease { /* private fields */ }

A held lease on {prefix}/LEASE. See the module docs.

Implementations

impl BucketLease

pub async fn acquire( store: Arc<dyn ObjectStore>, prefix: &str, ttl_s: u64, ) -> Result<BucketLease, LeaseError>

Take the lease on prefix for ttl_s seconds (0 counts as 1), under a new random instance id. See acquire_as.

Errors

As acquire_as.

pub async fn acquire_as( store: Arc<dyn ObjectStore>, prefix: &str, ttl_s: u64, instance_id: &str, watch: &mut LeaseWatch, ) -> Result<BucketLease, LeaseError>

Take the lease on prefix for ttl_s seconds (0 counts as 1) as instance_id.

An instance passes the same id and watch to every attempt. A lease already naming the id — an earlier attempt whose write landed though its answer was lost — is taken back at once, and watch lets a suspect foreign lease be taken over once it has sat unchanged for a TTL.

Errors

LeaseError::ForeignActive when another instance holds a fresh lease — or won the race for it against this call; LeaseError::PreconditionsIgnored when the service ignores a conditional PUT’s precondition; LeaseError::Store when the service fails a request.

pub fn instance_id(&self) -> &str

This process’s instance id, as the LEASE object names it.

pub fn ttl_s(&self) -> u64

The TTL this lease was taken with, in seconds.

pub fn renew_interval(&self) -> Duration

How often to renew: a third of the TTL.

pub fn exclusion(&self) -> Exclusion

How strongly this lease excludes a second writer on this service.

pub fn is_lost(&self) -> bool

Whether the lease was found replaced or deleted. A lost lease never comes back; take a new one.

pub fn write_deadline(&self) -> Option<Instant>

The moment, on Tokio’s clock, after which this holder must not write: two thirds of a TTL after the last successful renewal. None once the lease is lost or that moment has passed on either clock.

pub fn may_write(&self) -> bool

Whether this holder may start a write now. See write_deadline.

pub async fn renew(&self) -> Result<(), LeaseError>

Extend the lease: rewrite it with a new renewed_at, provided it is still exactly ours.

Errors

LeaseError::Lost when the object was replaced or deleted since our last write — the lease is then lost for good; LeaseError::Store when the service fails a request (retry; the fence keeps the holder safe meanwhile).

pub async fn release(self) -> Result<(), LeaseError>

Give the lease up: DELETE {prefix}/LEASE if it still names us. A lost lease, or one another instance now holds, is left alone.

The check and the delete are two requests (object_store 0.11 has no conditional DELETE): a takeover landing between them would be deleted, and its holder would rewrite it at its next renewal.

Errors

LeaseError::Store when the service fails a request; the lease then expires by itself after its TTL.

Trait Implementations

impl Debug for BucketLease

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

Formats the value using the given formatter.