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>
impl<'pool> WriterGuard<'pool>
Sourcepub fn autocommit<R>(
self,
operation: impl FnOnce(&Connection) -> Result<R, SqliteError>,
) -> Result<R, SqliteError>
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));
}Sourcepub fn transaction<F, R>(self, f: F) -> Result<R, SqliteError>
pub fn transaction<F, R>(self, f: F) -> 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.