Struct Client

pub struct Client<C>
where
    C: ManagedClient + Clone + Send + Sync + 'static,
    C::PubReceiver: Send + Sync,
{ /* private fields */ }

Leased Lock client struct.

Implementations

impl<C> Client<C>

where C: ManagedClient + Clone + Send + Sync, C::PubReceiver: Send + Sync,

Leased Lock client implementation

Notes: Do not call any of the methods of this client after the state_store parameter is shutdown. Calling any of the methods in this implementation after the state_store is shutdown results in undefined behavior.

pub fn new( state_store: Arc<Client<C>>, lock_name: Vec<u8>, lock_holder_name: Vec<u8>, ) -> Result<Self, Error>

Create a new Leased Lock Client.

Notes:

• lock_holder_name is expected to be the client ID used in the underlying MQTT connection settings.
• There must be one instance of leased_lock::Client per lock.

Errors

Error of kind LockNameLengthZero if the lock_name is empty

Error of kind LockHolderNameLengthZero if the lock_holder_name is empty

pub async fn try_acquire_lock( &self, lock_expiration: Duration, request_timeout: Duration, ) -> Result<HybridLogicalClock, Error>

Attempts to acquire a lock, returning if it cannot be acquired after one attempt.

lock_expiration is how long the lock will remain held in the State Store after acquired, if not released before then. request_timeout is the maximum time the function will wait for receiving a response from the State Store service, it is rounded up to the nearest second.

Returns Ok with a fencing token (HybridLogicalClock) if completed successfully, or Error(LockAlreadyHeld) if lock is not acquired.

Errors

Error of kind InvalidArgument if the request_timeout is zero or > u32::max

Error of kind ServiceError if the State Store returns an Error response

Error of kind UnexpectedPayload if the State Store returns a response that isn’t valid for a Set request

Error of kind AIOProtocolError if there are any underlying errors from the command invoker

Error of kind LockAlreadyHeld if the lock is already in use by another holder

Panics

Possible panic if, for some error, the fencing token (a.k.a. version) of the acquired lock is None.

pub async fn acquire_lock( &self, lock_expiration: Duration, request_timeout: Duration, ) -> Result<HybridLogicalClock, Error>

Waits until a lock is available (if not already) and attempts to acquire it.

Note: request_timeout is rounded up to the nearest second.

Returns Ok with a fencing token (HybridLogicalClock) if completed successfully, or an Error if any failure occurs.

Errors

Error of kind InvalidArgument if the request_timeout is zero or > u32::max

Error of kind ServiceError if the State Store returns an Error response

Error of kind UnexpectedPayload if the State Store returns a response that isn’t valid for the request

Error of kind AIOProtocolError if there are any underlying errors from the command invoker

Panics

Possible panic if, for some error, the fencing token (a.k.a. version) of the acquired lock is None.

pub async fn acquire_lock_and_update_value( &self, lock_expiration: Duration, request_timeout: Duration, key: Vec<u8>, update_value_function: impl Fn(Option<Vec<u8>>) -> AcquireAndUpdateKeyOption, ) -> Result<Response<bool>, Error>

Waits until a lock is acquired, sets/updates/deletes a key in the State Store (depending on update_value_function result) and releases the lock.

lock_expiration should be long enough to last through underlying key operations, otherwise it’s possible for updating the value to fail if the lock is no longer held.

update_value_function is a function with signature: fn should_update_key(key_current_value: Vec<u8>) -> AcquireAndUpdateKeyOption Where key_current_value is the current value of key in the State Store (right after the lock is acquired). If the return is AcquireAndUpdateKeyOption::Update(key_new_value) it must contain the new value of the State Store key.

The same request_timeout is used for all the individual network calls within acquire_lock_and_update_value.

Note: request_timeout is rounded up to the nearest second.

Returns true if the key is successfully set or deleted, or false if it is not.

Errors

Error of kind InvalidArgument if the request_timeout is zero or > u32::max

Error of kind ServiceError if the State Store returns an Error response

Error of kind UnexpectedPayload if the State Store returns a response that isn’t valid for the request

Error of kind AIOProtocolError if there are any underlying errors from the command invoker

pub async fn release_lock(&self, request_timeout: Duration) -> Result<(), Error>

Releases a lock if and only if requested by the lock holder (same client id).

Note: request_timeout is rounded up to the nearest second.

Returns Ok() if lock is no longer held by this lock_holder, or Error otherwise.

Errors

Error of kind InvalidArgument if the request_timeout is zero or > u32::max

Error of kind ServiceError if the State Store returns an Error response

Error of kind UnexpectedPayload if the State Store returns a response that isn’t valid for a V Delete request

Error of kind AIOProtocolError if there are any underlying errors from the command invoker

pub async fn observe_lock( &self, request_timeout: Duration, ) -> Result<Response<LockObservation>, Error>

Starts observation of any changes on a lock

Note: request_timeout is rounded up to the nearest second.

Returns OK(Response<LockObservation>) if the lock is now being observed. The LockObservation can be used to receive lock notifications for this lock

If a client disconnects, observe_lock must be called again by the user.

Errors

Error of kind InvalidArgument if

• the request_timeout is zero or > u32::max

Error of kind ServiceError if

• the State Store returns an Error response
• the State Store returns a response that isn’t valid for an Observe request

Error of kind AIOProtocolError if

• there are any underlying errors from the command invoker

pub async fn unobserve_lock( &self, request_timeout: Duration, ) -> Result<Response<bool>, Error>

Stops observation of any changes on a lock.

Note: request_timeout is rounded up to the nearest second.

Returns true if the lock is no longer being observed or false if the lock wasn’t being observed

Errors

Error of kind InvalidArgument if

• the request_timeout is zero or > u32::max

Error of kind ServiceError if

• the State Store returns an Error response
• the State Store returns a response that isn’t valid for an Unobserve request

Error of kind AIOProtocolError if

• there are any underlying errors from the command invoker

pub async fn get_lock_holder( &self, request_timeout: Duration, ) -> Result<Response<Option<Vec<u8>>>, Error>

Gets the name of the holder of a lock

Note: request_timeout is rounded up to the nearest second.

Returns Some(<holder of the lock>) if the lock is found or None if the lock was not found (i.e., was not acquired by anyone, already released or expired).

Errors

Error of kind InvalidArgument if the request_timeout is zero or > u32::max

Error of kind ServiceError if the State Store returns an Error response

Error of kind UnexpectedPayload if the State Store returns a response that isn’t valid for a Get request

Error of kind AIOProtocolError if there are any underlying errors from the command invoker