Async backend configuration module.

Provides unified async framework abstraction for both asyncdispatch and chronos. Select the backend at compile time with -d:asyncBackend=asyncdispatch|chronos. Default backend is asyncdispatch.

Types

AsyncTimeoutError = object of CatchableError: Raised when an async operation times out (chronos-compatible name).
CancelledError = object of CatchableError: Raised when an async operation is cancelled.
Duration = distinct int64: Time interval in nanoseconds. API-compatible with chronos.Duration.
Moment = object: Monotonic timestamp. API-compatible with chronos.Moment.

Consts

hasAsyncDispatch = true: true when the asyncdispatch backend is selected.
hasChronos = false: true when the chronos backend is selected.
ZeroDuration = 0'i64: A zero-length duration.

Procs

proc `$`(d: Duration): string {....raises: [], tags: [], forbids: [].}
proc `+`(a, b: Duration): Duration {.borrow, ...raises: [], tags: [], forbids: [].}
proc `+`(a: Moment; b: Duration): Moment {....raises: [], tags: [], forbids: [].}
proc `-`(a, b: Duration): Duration {.borrow, ...raises: [], tags: [], forbids: [].}
proc `-`(a, b: Moment): Duration {....raises: [], tags: [], forbids: [].}
proc `-`(a: Moment; b: Duration): Moment {....raises: [], tags: [], forbids: [].}
proc `<`(a, b: Duration): bool {.borrow, ...raises: [], tags: [], forbids: [].}
proc `<`(a, b: Moment): bool {....raises: [], tags: [], forbids: [].}
proc `<=`(a, b: Duration): bool {.borrow, ...raises: [], tags: [], forbids: [].}
proc `<=`(a, b: Moment): bool {....raises: [], tags: [], forbids: [].}
proc `==`(a, b: Duration): bool {.borrow, ...raises: [], tags: [], forbids: [].}
proc `>`(a, b: Duration): bool {....raises: [], tags: [], forbids: [].}
proc `>`(a, b: Moment): bool {....raises: [], tags: [], forbids: [].}
proc `>=`(a, b: Duration): bool {....raises: [], tags: [], forbids: [].}
proc `>=`(a, b: Moment): bool {....raises: [], tags: [], forbids: [].}
proc allFutures[T](futures: seq[Future[T]]): Future[void]: Wait for all futures to complete (success or failure).
proc asyncSpawn(fut: Future[void]) {....raises: [Exception], tags: [RootEffect], forbids: [].}: Fire-and-forget a future. If the future fails with an unhandled exception, a Defect is raised (matching chronos behaviour). The caller is responsible for error handling inside the async proc.
proc cancelAndWait(fut: Future[void]): Future[void] {....stackTrace: false, raises: [Exception], tags: [RootEffect], forbids: [].}: Cancel a future and wait for completion.
Warning: On asyncdispatch this is a no-op — the future is neither cancelled nor awaited. asyncdispatch has no cancellation primitive. Callers must not assume the future has stopped: any buffer it holds via addr remains live, and any socket write it scheduled will still complete. Do not reuse the affected resource (socket, buffer) after calling this under asyncdispatch. chronos cancels the future properly.
proc cancelTimer(fut: Future[void]) {....raises: [], tags: [], forbids: [].}: No-op under asyncdispatch: timers cannot be cancelled, but they complete harmlessly and are garbage-collected. Provided for API parity with chronos, which does cancel the timer via cancelSoon.
proc completed[T](fut: Future[T]): bool: Check if a future completed successfully (not failed). Chronos-compatible name for finished and not failed.
proc hours(h: int): Duration {....raises: [], tags: [], forbids: [].}: Create a Duration from hours.
proc milliseconds(ms: int): Duration {....raises: [], tags: [], forbids: [].}: Create a Duration from milliseconds.
proc minutes(m: int): Duration {....raises: [], tags: [], forbids: [].}: Create a Duration from minutes.
proc nanoseconds(ns: int): Duration {....raises: [], tags: [], forbids: [].}: Create a Duration from nanoseconds.
proc nanoseconds(ns: int64): Duration {....raises: [], tags: [], forbids: [].}: Create a Duration from nanoseconds.
proc now(T: typedesc[Moment]): Moment: Get the current monotonic timestamp.
proc registerFdReader(fd: cint; cb: proc () {....gcsafe, raises: [].}) {. ...raises: [OSError, CatchableError], tags: [], forbids: [].}: Register a file descriptor for read-readiness notifications on the event loop. cb is called whenever the fd becomes readable.
proc scheduleSoon(cb: proc () {....gcsafe, raises: [].}) {....raises: [], tags: [], forbids: [].}: Schedule cb to run on the next event loop tick.
proc seconds(s: int): Duration {....raises: [], tags: [], forbids: [].}: Create a Duration from seconds.
proc sleepAsync(d: Duration): Future[void] {....raises: [], tags: [TimeEffect], forbids: [].}: Sleep for the given Duration.
proc sleepMsAsync(ms: int): Future[void] {....raises: [], tags: [TimeEffect], forbids: [].}: Sleep for ms milliseconds.
proc toMilliseconds(d: Duration): int {....raises: [], tags: [], forbids: [].}: Convert Duration to milliseconds (for asyncdispatch APIs).
proc unregisterFdReader(fd: cint) {....raises: [], tags: [], forbids: [].}: Remove a previously registered read-readiness watcher from the event loop.
proc wait[T](fut: Future[T]; timeout: Duration): Future[T] {....stackTrace: false.}: Wait for a future with a timeout. Raises AsyncTimeoutError on timeout. API-compatible with chronos Future.wait().
Warning: asyncdispatch has no cancellation. When a timeout fires, the inner future keeps running in the background until its I/O completes. For this reason the underlying connection MUST NOT be reused after an AsyncTimeoutError — a late write from the suspended future would corrupt the protocol stream of whoever reuses it next. The pg_client layer forces csClosed on timeout under asyncdispatch; see invalidateOnTimeout in pg_client.nim. chronos is not affected because its futures are actually cancelled.

Note: we add a no-op callback to suppress unhandled exception warnings when the suspended inner future eventually fails.

async_postgres/async_backend

Types

Consts

Procs