Struct throttle_client::Client

pub struct Client { /* fields omitted */ }

Send http requests to a throttle server. Only concerned with sending correct HTTP requests the Throttle server understands. Not a higher level locking library.

Implementations

impl Client

pub fn new(url: impl IntoUrl) -> Result<Self, Error>

A new throttle Client instance.

pub async fn new_peer<'_>(&'_ self, expires_in: Duration) -> Result<u64, Error>

Register a new peer with the server.

Parameters

• expires_in: Retention time of the peer on the server. A peer is used to acquire locks and keep the leases to them alive. A Peer owns the locks which it acquires and releasing it is going to release the owned locks as well.

Every call to new_peer should be matched by a call to release.

Creating a peer new_peer is separated from acquire in an extra Request mostly to make acquire idempotent. This prevents a call to acquire from acquiring more than one semaphore in case it is repeated due to a timeout.

pub async fn release<'_>(&'_ self, peer_id: u64) -> Result<(), Error>

Deletes the peer on the throttle server.

This is important to unblock other clients which may be waiting for the semaphore remainder to increase.

pub async fn acquire<'_, '_>(
    &'_ self,
    peer_id: u64,
    semaphore: &'_ str,
    count: u32,
    expires_in: Option<Duration>,
    block_for: Option<Duration>
) -> Result<bool, Error>

Acquire a lock from the server.

Every call to acquire should be matched by a call to release. Check out lock which as contextmanager does this for you.

Parameters

• semaphore: Name of the semaphore to be acquired.
• count: The count of the lock. A larger count represents a larger 'piece' of the resource under procection.
• block_for: The request returns as soon as the lock could be acquireod or after the duration has elapsed, even if the lock could not be acquired. If set to None, the request returns immediatly. Please note that this function is asynchronous and does not block. The blocking does refer to the actual request. As such block_for represents an upper bound after which the returned futures poll method is going to return Ready.
• expires_in: The amount of time the remains valid. Can be prolonged by calling heartbeat. After the time has passed the lock is considered released on the server side.

Return

true if the lock is active, false otherwise.

pub async fn is_acquired<'_>(&'_ self, peer_id: u64) -> Result<bool, Error>

Ask the server wether the peer has acquired all its locks.

pub async fn remove_expired<'_>(&'_ self) -> Result<usize, Error>

Request the throttle server to remove all expired peers.

Return

Number of expired peers.

pub async fn remainder<'_, '_>(
    &'_ self,
    semaphore: &'_ str
) -> Result<i64, Error>

The curent semaphore count. I.e. the number of available leases

This is equal to the full semaphore count minus the current count. This number could become negative, if the semaphores have been overcommitted (due to previously reoccuring leases previously considered dead).

pub async fn restore<'_, '_>(
    &'_ self,
    peer_id: u64,
    acquired: &'_ HashMap<String, u32>,
    expires_in: Duration
) -> Result<(), Error>

Sends a restore request to the server.

This request creates a peer with the specified peer id. The peer is also going to hold all the locks passed in acquired, even if this means exceeding the semaphore count.

pub async fn heartbeat<'_>(
    &'_ self,
    peer_id: u64,
    expires_in: Duration
) -> Result<(), Error>

Send a PUT request to the server updating the expiration timestamp

pub async fn release_lock<'_, '_>(
    &'_ self,
    peer_id: u64,
    semaphore: &'_ str
) -> Result<(), Error>

Release a lock to a semaphore for a specific peer

Trait Implementations

impl Clone for Client

fn clone(&self) -> Client

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Client

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

Formats the value using the given formatter.