Struct throttle_client::Client
source · pub struct Client { /* private fields */ }
Expand description
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§
source§impl Client
impl Client
sourcepub async fn new_peer(&self, expires_in: Duration) -> Result<u64, Error>
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.
sourcepub async fn release(&self, peer_id: u64) -> Result<(), Error>
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.
sourcepub async fn acquire(
&self,
peer_id: u64,
semaphore: &str,
count: u32,
expires_in: Option<Duration>,
block_for: Option<Duration>
) -> Result<bool, Error>
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 toNone
, the request returns immediatly. Please note that this function is asynchronous and does not block. The blocking does refer to the actual request. As suchblock_for
represents an upper bound after which the returned futures poll method is going to returnReady
.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.
sourcepub async fn is_acquired(&self, peer_id: u64) -> Result<bool, Error>
pub async fn is_acquired(&self, peer_id: u64) -> Result<bool, Error>
Ask the server wether the peer has acquired all its locks.
sourcepub async fn remainder(&self, semaphore: &str) -> Result<i64, Error>
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).
sourcepub async fn restore(
&self,
peer_id: u64,
acquired: &HashMap<String, u32>,
expires_in: Duration
) -> Result<(), Error>
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.