azure_iot_operations_services::leased_lock::lease

Struct Client

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

Expand description

Lease client struct.

Implementations§

Source §

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

Lease 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.

Source

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

Create a new Lease Client.

Notes:

lease_holder_name is expected to be the client ID used in the underlying MQTT connection settings.
There must be only one instance of lease::Client per lease.

§Errors

Error of kind InvalidArgument if the either lease_name or lease_holder_name is empty.

Source

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

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

Returns either None or an actual Fencing Token (HybridLogicalClock). None means that either a lease has not been acquired previously with this client, or a lease renewal has failed (if lease 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.

§Panics

If the lock on the current_fencing_token is poisoned, which should not be possible.

Source

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

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

lease_expiration is how long the lease 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. renewal_period is the frequency with which the lease will be auto-renewed by the lease client if acquired successfully. None (or zero) indicates the lease should not be auto-renewed.

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

Returns Ok with a fencing token (HybridLogicalClock) if completed successfully, or Error if lease 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 LeaseAlreadyHeld if the lease is already in use by another holder

Error of kind MissingFencingToken if the fencing token in the service response is empty.

Source

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

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

Note: request_timeout is rounded up to the nearest second.

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

Even if this method fails the current fencing token (obtained by calling current_lease_fencing_token()) is cleared and the auto-renewal task is terminated (if the lease 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

§Panics

If the lock on the current_fencing_token is poisoned, which should not be possible.

Source

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

Starts observation of any changes on a lease

Note: request_timeout is rounded up to the nearest second.

Returns OK(LeaseObservation) if the lease is now being observed. The LeaseObservation can be used to receive lease notifications for this lease

If a client disconnects, observe 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

Source

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

Stops observation of any changes on a lease.

Note: request_timeout is rounded up to the nearest second.

Returns true if the lease is no longer being observed or false if the lease 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

Source

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

Gets the name of the holder of a lease

Note: request_timeout is rounded up to the nearest second.

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