Skip to main content

WriterGuard

Struct WriterGuard 

Source
pub struct WriterGuard<'pool> { /* private fields */ }
Expand description

A writer connection checked out from the pool. The Mutex ensures only one writer at a time.

Checkout retains exclusion; each consuming operation samples capacity at its execution boundary. Raw connection access is not a public capability:

ⓘ
use khive_db::ConnectionPool;
fn raw(pool: &ConnectionPool) {
    let writer = pool.writer().unwrap();
    let _connection = writer.conn();
}
ⓘ
use khive_db::ConnectionPool;
fn raw_mut(pool: &ConnectionPool) {
    let mut writer = pool.writer().unwrap();
    let _connection = writer.conn_mut();
}
ⓘ
use khive_db::ConnectionPool;
fn raw_mut(pool: &ConnectionPool) {
    let mut writer = pool.writer().unwrap();
    let _connection: &mut rusqlite::Connection = &mut *writer;
}

§Terminal settlement

Dropping a retired writer settles its connection before the volume lease is released. If cleanup cannot restore autocommit and owned SQLite close also fails, the database path, volume, and errors are emitted to stderr and tracing, that write reports SqliteError::WriterSettlementUnknown, the pool is poisoned so every later write is refused with SqliteError::WriterPoisoned before it starts, and the lease is then released.

Implementations§

Source§

impl<'pool> WriterGuard<'pool>

Source

pub fn autocommit<R>( self, operation: impl FnOnce(&Connection) -> Result<R, SqliteError>, ) -> Result<R, SqliteError>

Own one autocommit operation or complete SQL script.

Capacity is checked immediately before the callback. A script must finish every transaction it starts; an unfinished one is rolled back and refused. The consumed guard retains its lease through settlement, including if the callback unwinds.

use khive_db::{ConnectionPool, SqliteError};
fn seed(pool: &ConnectionPool) -> Result<(), SqliteError> {
    pool.writer()?.autocommit(|conn| {
        conn.execute_batch("CREATE TABLE example(value INTEGER)")?;
        Ok(())
    })
}

The callback cannot return a connection borrow:

ⓘ
use khive_db::ConnectionPool;
fn escape(pool: &ConnectionPool) {
    let _connection = pool.writer().unwrap().autocommit(|conn| Ok(conn));
}
Source

pub fn transaction<F, R>(self, f: F) -> Result<R, SqliteError>
where F: FnOnce(&Connection) -> Result<R, SqliteError>,

Execute a write transaction. Consumes this guard through BEGIN IMMEDIATE, post-BEGIN admission and COMMIT/ROLLBACK. The callback must not settle the outer transaction itself.

§Panics

A callback panic propagates to the caller. During unwinding, this guard attempts rollback or retirement before releasing its volume lease and registered transaction evidence.

Trait Implementations§

Source§

impl Drop for WriterGuard<'_>

Source§

fn drop(&mut self)

Executes the destructor for this type. Read more
Source§

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)
Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned. Read more

Auto Trait Implementations§

§

impl<'pool> !RefUnwindSafe for WriterGuard<'pool>

§

impl<'pool> !Send for WriterGuard<'pool>

§

impl<'pool> !Sync for WriterGuard<'pool>

§

impl<'pool> !UnwindSafe for WriterGuard<'pool>

§

impl<'pool> Forget for WriterGuard<'pool>

§

impl<'pool> Freeze for WriterGuard<'pool>

§

impl<'pool> Unpin for WriterGuard<'pool>

§

impl<'pool> UnsafeUnpin for WriterGuard<'pool>

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T> Instrument for T

Source§

fn instrument(self, span: Span) -> Instrumented<Self> ⓘ

Instruments this type with the provided Span, returning an Instrumented wrapper. Read more
Source§

fn in_current_span(self) -> Instrumented<Self> ⓘ

Instruments this type with the current Span, returning an Instrumented wrapper. Read more
Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> Same for T

Source§

type Output = T

Should always be Self
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
Source§

impl<T> WithSubscriber for T

Source§

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self> ⓘ
where S: Into<Dispatch>,

Attaches the provided Subscriber to this type, returning a WithDispatch wrapper. Read more
Source§

fn with_current_subscriber(self) -> WithDispatch<Self> ⓘ

Attaches the current default Subscriber to this type, returning a WithDispatch wrapper. Read more