azure_iot_operations_services::leased_lock::lock

Struct Client

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

Expand description

Lock client struct.

Implementations§

Source §

impl<C> Client<C>
where C: ManagedClient + Clone + Send + Sync, C::PubReceiver: Send + Sync,

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. There must be only one instance of lock::Client per lock.

Source

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

Create a new 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 lock::Client per lock.

§Errors

Error of kind InvalidArgument if the either lock_name or lock_holder_name is empty.

Source

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

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

If a non-zero Duration is provided as renewal_period, the lock is automatically renewed after every consecutive elapse of renewal_period until the lock is released or a re-acquire failure occurs. If automatic lock renewal is used, current_lock_fencing_token() must be used to access the most up-to-date fencing token (see function documentation).

Notes: request_timeout is rounded up to the nearest second.

If lock auto-renewal is used, an auto-renewal task is spawned. To terminate this task and stop the lock auto-renewal, lock::Client::unlock() must be called. Simply dropping the lock::Client instance will not terminate the auto-renewal task. This logic is intended for a scenario where the lock::Client is cloned and a lock is acquired with auto-renewal by the original instance. If the original instance is dropped, its clone remains in control of the lock (through the auto-renewal task that remains active). Special attention must be used to avoid a memory leak if lock::Client::unlock() is never called in this scenario.

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

Source

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

Releases a lock.

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.

Even if this method fails the current fencing token (obtained by calling current_lock_fencing_token()) is cleared and the auto-renewal task is cancelled (if the lock was acquired using auto-renewal).

§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

Source

pub fn current_lock_fencing_token(&self) -> Option<HybridLogicalClock>

Gets the latest fencing token related to the most recent lock.

Returns either None or an actual Fencing Token (HybridLogicalClock). None means that either a lock has not been acquired previously with this client, or a lock renewal has failed (if lock auto-renewal is used). The presence of a HybridLogicalClock does not mean that it is the most recent (and thus valid) Fencing Token - this can happen in the scenario where auto-renewal has not been used and the lease has already expired.