Struct please::PleaseHandle

pub struct PleaseHandle<P: ConnectionProvider> { /* private fields */ }

This handle identifies a long-running operation using a unique integer.

Implementations

impl<P: ConnectionProvider> PleaseHandle<P>

pub fn new(provider: P, title: &str) -> PleaseResult<Self, P::Error>

Construct a new handle using the specified connection provider.

The connection provider is typically a connection pool of some kind, or it may be implemented by establishing a new connection each time.

The title is used as a human-readable name to identify this handle. This is useful if you are inspecting the database, or for logging expired handles.

pub fn new_with_cleanup(provider: P, title: &str) -> PleaseResult<Self, P::Error>

Convenience constructor.

Equivalent to calling perform_cleanup followed by new. If you wish to handle expired handles (eg. record them to a log) then call the methods individually.

pub fn new_with_connection<C>(
    provider: P,
    title: &str,
    conn: &C
) -> QueryResult<Self>where
    C: Connection<Backend = Pg> + ?Sized,

Constructor to use from within an existing transaction.

Allows conditionally creating a handle without losing the atomicity of a single transaction.

pub fn perform_cleanup(provider: &P) -> PleaseResult<Vec<ExpiredId>, P::Error>

Explicitly clean up old handles. It is recommended to call this before creating a new handle.

This function returns the expired handles (if any) so that you can log them or use them for debugging.

pub fn transaction<R, E, F>(&mut self, f: F) -> Result<R, E>where
    E: From<PleaseError<P::Error>>,
    F: FnOnce(&P::Connection, i32) -> Result<R, E>,

Run a transaction as part of the operation this handle represents.

After beginning the transaction, this method validates that the handle has not expired, whilst also refreshing the expiry and taking a lock on the row, to prevent it being expired by another thread whilst this transaction is in progress.

The callback is passed two arguments: a reference to the connection, and the integer ID of this handle. Currently this is the only way to access the handle’s ID as it is not recommended to use this ID outside of a transaction.

pub fn refresh(&mut self) -> PleaseResult<(), P::Error>

Refreshes the handle, resetting the time before it will be automatically closed.

This is equivalent to running an empty transaction.

pub fn expire(&mut self) -> PleaseResult<ExpiredId, P::Error>

Expire the handle. Future operations on this handle will fail with the error Expired.

Useful for testing.

pub fn close(self) -> PleaseResult<(), P::Error>

Close the handle, allowing any errors to be handled.

This is automatically called when a handle is dropped, but in that case errors are silently ignored.

pub fn id(&self) -> i32

Get the ID of this handle.

A good rule of thumb is to never use this outside of a transaction, as in that case it may not have been recently validated.

Trait Implementations

impl<P: Debug + ConnectionProvider> Debug for PleaseHandle<P>

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

Formats the value using the given formatter.

impl<P: ConnectionProvider> Drop for PleaseHandle<P>

fn drop(&mut self)

Closes the handle, ignoring any errors that might have occurred.