Struct AsyncHandle 

pub struct AsyncHandle { /* private fields */ }

Async handle returned by db.run_async().

SQL and parameters are owned so submitted jobs satisfy the 'static bound.

Cancellation

Dropping a future returned by this handle before it is first polled means the job is never submitted. Dropping it after it has been polled does not cancel the operation: the work (including a transaction commit) still runs to completion on the worker and only the result is discarded.

Worker pool

Without the tokio feature — or with it, when the returned future is first polled outside a tokio runtime — jobs run on a self-managed blocking pool that is global to the process and shared by every Database instance. Long-running jobs on one database can therefore delay jobs for other databases. The pool size defaults to max(4, available parallelism) and can be overridden with the ROOMRS_ASYNC_WORKERS environment variable (invalid or zero values are ignored; values above 1024 are clamped to 1024). The variable is read once when the self-managed pool is first used; later environment changes do not resize the process-global pool. With tokio, this initialization may be deferred until the first fallback submission.

Connection-pool contention

Every operation exclusively checks out one read/write connection. When all connections for a database are busy, waiting jobs can occupy every worker in the self-managed pool and delay jobs for other databases. Configure DatabaseBuilder::queue_timeout to bound checkout waits, keep transactions short, and/or increase ROOMRS_ASYNC_WORKERS. SQLite lock contention is governed separately by the configured busy_timeout. The tokio spawn_blocking path is less susceptible to worker starvation because its blocking pool can grow independently.

Implementations

impl AsyncHandle

pub fn execute<S: Into<String>, P>( &self, sql: S, params: P, ) -> impl Future<Output = Result<u64>> + Send + use<S, P>

where P: Params + Send + 'static,

Executes a statement and returns the affected row count.

Dropping the returned future after it has been polled does not cancel the write; it still runs on the worker and only the result is discarded (see the AsyncHandle cancellation notes).

pub fn query_one<S: Into<String>, T, P>( &self, sql: S, params: P, ) -> impl Future<Output = Result<T>> + Send + use<S, T, P>

where T: FromRow + Send + 'static, P: Params + Send + 'static,

Queries exactly one row, returning Error::NotFound when no row exists.

pub fn query_optional<S: Into<String>, T, P>( &self, sql: S, params: P, ) -> impl Future<Output = Result<Option<T>>> + Send + use<S, T, P>

where T: FromRow + Send + 'static, P: Params + Send + 'static,

Queries zero or one row.

pub fn query_scalar<S: Into<String>, T, P>( &self, sql: S, params: P, ) -> impl Future<Output = Result<T>> + Send + use<S, T, P>

where T: FromSql + Send + 'static, P: Params + Send + 'static,

Queries one scalar value.

pub fn query_all<S: Into<String>, T, P>( &self, sql: S, params: P, ) -> impl Future<Output = Result<Vec<T>>> + Send + use<S, T, P>

where T: FromRow + Send + 'static, P: Params + Send + 'static,

Queries zero or more rows.

pub fn transaction<R, F>( &self, f: F, ) -> impl Future<Output = Result<R>> + Send + use<R, F>

where R: Send + 'static, F: FnOnce(&mut Tx<'_>) -> Result<R> + Send + 'static,

Runs a transaction with a synchronous closure on a worker.

The closure keeps the same checked-out connection from BEGIN IMMEDIATE through commit or rollback. The closure cannot await.

Cancellation

Dropping the returned future before it is first polled means the transaction is never started. Dropping it after it has been polled does not cancel the operation: the transaction still runs to completion on the worker — including the commit (or rollback) — and only the result is discarded. The transaction always terminates with a commit or rollback; it is never left open.

Trait Implementations

impl Clone for AsyncHandle

fn clone(&self) -> AsyncHandle

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Execute for &AsyncHandle

Provides boxed futures for generated async DAO code.

type Out<R: Send + 'static> = Pin<Box<dyn Future<Output = Result<R, Error>> + Send>>

실행 결과 컨테이너

fn run_all<T: FromRow + Send + 'static>( self, sql: String, params: Vec<Value>, ) -> Self::Out<Vec<T>>

fn run_optional<T: FromRow + Send + 'static>( self, sql: String, params: Vec<Value>, ) -> Self::Out<Option<T>>

fn run_one<T: FromRow + Send + 'static>( self, sql: String, params: Vec<Value>, ) -> Self::Out<T>

fn run_scalar(self, sql: String, params: Vec<Value>) -> Self::Out<i64>

fn fail<R: Send + 'static>(e: Error) -> Self::Out<R>

빌드 단계 에러를 결과 컨테이너로