chronos/internal/asyncengine

    Dark Mode
Search:
Group by:
  Source   Edit

This module implements the core asynchronous engine / dispatcher.

For more information, see the Concepts chapter of the guide.

Types

AsyncFD = distinct cint
  Source   Edit 
PDispatcher = ref object of PDispatcherBase
  Source   Edit 
TimerCallback = ref object
  finishAt*: Moment
  function*: AsyncCallback
  Source   Edit 
TrackerBase {....deprecated: "Use `TracerCounter` instead".} = ref object of RootRef
  id*: string
  dump*: proc (): string {....gcsafe, raises: [].}
  isLeaked*: proc (): bool {....gcsafe, raises: [].}
Deprecated: Use `TracerCounter` instead
  Source   Edit 
TrackerCounter = object
  opened*: uint64
  closed*: uint64
  Source   Edit 
TrackerCounters = Table[string, TrackerCounter]
  Source   Edit

Procs

proc `==`(x: AsyncFD; y: AsyncFD): bool {.borrow, ...gcsafe, raises: [], gcsafe,
    tags: [].}
  Source   Edit 
proc addReader2(fd: AsyncFD; cb: CallbackFunc; udata: pointer = nil): Result[
    void, OSErrorCode] {....raises: [], gcsafe, tags: [].}
  Source   Edit 
proc addTimer(at: int64; cb: CallbackFunc; udata: pointer = nil) {.inline,
    ...deprecated: "Use addTimer(Duration, cb, udata)", raises: [], gcsafe,
    tags: [RootEffect].}
Deprecated: Use addTimer(Duration, cb, udata)
  Source   Edit 
proc addTimer(at: Moment; cb: CallbackFunc; udata: pointer = nil) {.inline,
    ...deprecated: "Use setTimer/clearTimer instead", raises: [], gcsafe,
    tags: [RootEffect].}
Deprecated: Use setTimer/clearTimer instead
Arrange for the callback cb to be called at the given absolute timestamp at. You can also pass udata to callback.   Source   Edit 
proc addTimer(at: uint64; cb: CallbackFunc; udata: pointer = nil) {.inline,
    ...deprecated: "Use addTimer(Duration, cb, udata)", raises: [], gcsafe,
    tags: [RootEffect].}
Deprecated: Use addTimer(Duration, cb, udata)
  Source   Edit 
proc addWriter2(fd: AsyncFD; cb: CallbackFunc; udata: pointer = nil): Result[
    void, OSErrorCode] {....raises: [], gcsafe, tags: [].}
  Source   Edit 
proc callIdle(acb: AsyncCallback) {....raises: [], gcsafe, tags: [].}

Schedule cbproc to be called when there no pending network events available.

WARNING! Despite the name, "idle" callbacks called on every loop iteration if there no network events available, not when the loop is actually "idle".

  Source   Edit 
proc callIdle(cbproc: CallbackFunc) {....raises: [], gcsafe, tags: [RootEffect].}
  Source   Edit 
proc callIdle(cbproc: CallbackFunc; data: pointer) {....raises: [], gcsafe,
    tags: [].}

Schedule cbproc to be called when there no pending network events available.

WARNING! Despite the name, "idle" callbacks called on every loop iteration if there no network events available, not when the loop is actually "idle".

  Source   Edit 
proc callSoon(acb: AsyncCallback) {....raises: [], gcsafe, tags: [].}
Schedule cbproc to be called as soon as possible. The callback is called when control returns to the event loop.   Source   Edit 
proc callSoon(cbproc: CallbackFunc; udata: pointer = nil) {....raises: [], gcsafe,
    tags: [].}
Schedule cbproc to be called as soon as possible. The callback is called when control returns to the event loop.   Source   Edit 
proc clearTimer(timer: TimerCallback) {.inline, ...raises: [], gcsafe, tags: [].}
  Source   Edit 
proc closeDispatcher(loop: PDispatcher): Opt[string] {....raises: [], gcsafe,
    tags: [].}
  Source   Edit 
proc closeHandle(fd: AsyncFD; aftercb: CallbackFunc = nil) {....raises: [], gcsafe,
    tags: [].}
  Source   Edit 
proc closeSocket(fd: AsyncFD; aftercb: CallbackFunc = nil) {....raises: [], gcsafe,
    tags: [].}
  Source   Edit 
proc closeThreadDispatcher(): Opt[string] {....raises: [], gcsafe, tags: [].}

Close the current thread's dispatcher, releasing its resources and leaving the thread without one - a new dispatcher is created on next use. Closing a thread that never had one does nothing.

Like close(2), the resources are released unconditionally: the return value is a diagnostic, not something to retry.

Closing while futures are pending or handles are open is undefined behaviour - a Defect is raised for the work the dispatcher knows about, but operations the OS queue has not reported yet go undetected.

  Source   Edit 
proc contains(disp: PDispatcher; fd: AsyncFD): bool {....raises: [], gcsafe,
    tags: [].}
  Source   Edit 
proc getThreadDispatcher(): PDispatcher {....raises: [], gcsafe, tags: [].}
Returns current thread's dispatcher instance.   Source   Edit 
proc getTrackerCounter(name: string): TrackerCounter {....raises: [], gcsafe,
    tags: [].}
Return value of counter with name name.   Source   Edit 
proc getTrackerCounters(): TrackerCounters {....raises: [], gcsafe, tags: [].}
Take a snapshot of the current tracker counter state, so it can be compared with a later state.   Source   Edit 
proc internalCallTick(acb: AsyncCallback) {....raises: [], gcsafe, tags: [].}
Schedule cbproc to be called after all scheduled callbacks, but only when OS system queue finished processing events.   Source   Edit 
proc internalCallTick(cbproc: CallbackFunc) {....raises: [], gcsafe, tags: [].}
  Source   Edit 
proc internalCallTick(cbproc: CallbackFunc; data: pointer) {....raises: [], gcsafe,
    tags: [].}
Schedule cbproc to be called after all scheduled callbacks when OS system queue processing is done.   Source   Edit 
proc isCounterLeaked(name: string): bool {....raises: [], gcsafe, tags: [].}
Returns true if leak is detected, number of opened not equal to number of closed requests.   Source   Edit 
proc newDispatcher(): PDispatcher {....raises: [], gcsafe, tags: [].}
  Source   Edit 
proc poll() {....raises: [], gcsafe, tags: [].}

Perform single asynchronous step, processing timers and completing tasks. Blocks until at least one event has completed.

Exceptions raised during async task exception are stored as outcome in the corresponding Future - poll itself does not raise.

  Source   Edit 
proc raiseAsDefect(exc: ref Exception; msg: string) {.noreturn, noinline,
    ...raises: [], gcsafe, tags: [].}
  Source   Edit 
proc raiseOsDefect(error: OSErrorCode; msg = "") {.noreturn, noinline,
    ...raises: [], gcsafe, tags: [].}
  Source   Edit 
proc register2(fd: AsyncFD): Result[void, OSErrorCode] {....raises: [], gcsafe,
    tags: [].}
  Source   Edit 
proc removeReader2(fd: AsyncFD): Result[void, OSErrorCode] {....raises: [], gcsafe,
    tags: [].}
  Source   Edit 
proc removeTimer(at: int64; cb: CallbackFunc; udata: pointer = nil) {.inline,
    ...deprecated: "Use removeTimer(Duration, cb, udata)", raises: [], gcsafe,
    tags: [RootEffect].}
Deprecated: Use removeTimer(Duration, cb, udata)
  Source   Edit 
proc removeTimer(at: Moment; cb: CallbackFunc; udata: pointer = nil) {.
    ...raises: [], gcsafe, tags: [].}
Remove timer callback cb with absolute timestamp at from waiting queue.   Source   Edit 
proc removeTimer(at: uint64; cb: CallbackFunc; udata: pointer = nil) {.inline,
    ...deprecated: "Use removeTimer(Duration, cb, udata)", raises: [], gcsafe,
    tags: [RootEffect].}
Deprecated: Use removeTimer(Duration, cb, udata)
  Source   Edit 
proc removeWriter2(fd: AsyncFD): Result[void, OSErrorCode] {....raises: [], gcsafe,
    tags: [].}
  Source   Edit 
proc runForever() {....raises: [], gcsafe, tags: [].}
Begins a never ending global dispatcher poll loop. Raises different exceptions depending on the platform.   Source   Edit 
proc setThreadDispatcher(disp: PDispatcher) {....raises: [], gcsafe, tags: [].}
Set current thread's dispatcher instance to disp.   Source   Edit 
proc setTimer(at: Moment; cb: CallbackFunc; udata: pointer = nil): TimerCallback {.
    ...raises: [], gcsafe, tags: [].}
Arrange for the callback cb to be called at the given absolute timestamp at. You can also pass udata to callback.   Source   Edit 
func toException(v: OSErrorCode): ref OSError {....raises: [], gcsafe, tags: [].}
  Source   Edit 
proc trackCounter(name: string) {....raises: [], gcsafe, tags: [].}
Increase tracker counter with name name by 1.   Source   Edit 
proc unregister2(fd: AsyncFD): Result[void, OSErrorCode] {....raises: [], gcsafe,
    tags: [].}
  Source   Edit 
proc unregisterAndCloseFd(fd: AsyncFD): Result[void, OSErrorCode] {....raises: [],
    gcsafe, tags: [].}
  Source   Edit 
proc untrackCounter(name: string) {....raises: [], gcsafe, tags: [].}
Decrease tracker counter with name name by 1.   Source   Edit

Iterators

iterator trackerCounterKeys(loop: PDispatcher): string {....raises: [], gcsafe,
    tags: [].}
  Source   Edit 
iterator trackerCounters(loop: PDispatcher): tuple[name: string,
    value: TrackerCounter] {....raises: [], gcsafe, tags: [].}
Iterates over loop thread dispatcher tracker counter table, returns all the tracker counter's names and values.   Source   Edit

Exports

NestedPoll, AsyncExceptionError, AsyncError, AsyncTimeoutError, state, LocationKind, CallbackFunc, error, id, CancelledError, completed, value, FutureFlags, failed, Future, failed, $, InternalFutureBase, completed, cancelled, init, InternalAsyncCallback, internalInitFutureBase, FutureBase, value, finished, getSrcLocation, FutureError, FutureState, init, location, flags, FutureFlag, SrcLoc, FutureDefect, completed, Hour, fromNow, milliseconds, <, <=, Minute, secs, microseconds, micros, ==, nanoseconds, +, fseconds, nanos, minutes, asyncTimer, low, fseconds, milliseconds, millis, $, micros, InfiniteDuration, +=, Nanosecond, -, -, Second, high, epochNanoSeconds, Microsecond, weeks, microseconds, init, secs, -=, +, minutes, +=, Day, $, hours, toString, hours, Duration, now, <, weeks, Millisecond, <=, millis, ==, seconds, isZero, ZeroDuration, isInfinite, SomeIntegerI64, div, +, *, epochSeconds, high, nanoseconds, nanos, low, -, days, -=, Week, days, seconds, *, Moment, async, async, await, await, awaitne, EPERM, ENOBUFS, EFAULT, EKEYREJECTED, EHWPOISON, EHOSTDOWN, EDQUOT, EREMCHG, EISDIR, ESTRPIPE, EMLINK, ENXIO, ETOOMANYREFS, ENOMEDIUM, EOVERFLOW, EAFNOSUPPORT, ENOTCONN, ECHILD, ESOCKTNOSUPPORT, EBFONT, ESRMNT, ENOTEMPTY, ESTALE, EPROTO, EADDRNOTAVAIL, EXDEV, EBADF, EKEYREVOKED, ENOTDIR, EDEADLK, EALREADY, ESPIPE, ENOEXEC, ENETDOWN, EACCES, ELNRNG, ELOOP, ENODEV, ENFILE, ENOPKG, ENOCSI, ECHRNG, EL3HLT, EINVAL, EADDRINUSE, EUNATCH, EBADFD, EMEDIUMTYPE, ERESTART, ESRCH, ETXTBSY, ENETUNREACH, EPROTONOSUPPORT, ECANCELED, EBADMSG, EMFILE, ENOSYS, ERANGE, EDEADLOCK, ENOKEY, EILSEQ, EBUSY, EROFS, ENOTSOCK, ECONNREFUSED, ELIBMAX, EBADRQC, ECOMM, EL2HLT, EIDRM, ENOTBLK, ENOTTY, EOPNOTSUPP, EISNAM, ENOSR, EXFULL, EPROTOTYPE, EUCLEAN, ENOSTR, ENOTRECOVERABLE, ENOANO, ERFKILL, ENOENT, EISCONN, ELIBEXEC, EMULTIHOP, ELIBACC, ENOLCK, EHOSTUNREACH, ENETRESET, ECONNRESET, EINPROGRESS, E2BIG, EIO, ENODATA, ESHUTDOWN, EFBIG, ELIBBAD, EOWNERDEAD, ETIMEDOUT, ECONNABORTED, ENOSPC, EBADSLT, ETIME, EINTR, EEXIST, ENONET, EREMOTEIO, EPFNOSUPPORT, ENOLINK, ENOMSG, EDOM, EMSGSIZE, EPIPE, EBADE, ENOMEM, ELIBSCN, ENOPROTOOPT, EDESTADDRREQ, ENAVAIL, ENOTNAM, EADV, EDOTDOT, EUSERS, EKEYEXPIRED, EBADR, EL3RST, EAGAIN, ENOTUNIQ, EWOULDBLOCK, ENAMETOOLONG, EREMOTE, EL2NSYNC

Made with Nim. Generated: 2026-09-18 10:16:34 UTC