Windows completion-port dispatcher object that multiplexes posted callbacks and overlapped completions. The object provides callback posting, blocking or polling dispatch, one wake helper, and one exported opaque completion-port handle.

Windows-only.

Dispatcher objects

dispatcherInternal and dispatcher refer to the same initialized Windows completion-port dispatcher object. dispatcherInternal is the mutable module-level object used for initialization and cleanup; dispatcher is the public alias that pushes an immutable view of it for callers.

dispatcherInternal

(-- dispatcherInternal) Provides the initialized dispatcher object.

Remarks

  • This is the mutable top-level object used for module initialization and cleanup. Callers normally use dispatcher.

dispatcher

(-- dispatcher) Provides the public alias of dispatcherInternal.

Fields

Queue entry forms at a glance

Entry form Completion key lpOverlapped Dispatched callback User payload source
Posted callback Callback Code address Pointer slot carrying the Natx context value OnCallback, called with that value as context The caller's Natx context value
Overlapped completion 0nx Address of Context.overlapped Context.onEvent Context.context, OVERLAPPED.Internal, and transferred bytes

Operations

init

(--) Initializes the dispatcher completion port and Winsock state.
  • The module invokes it once during program startup; it is an ordinary method named init, not an INIT hook.

Remarks

  • Use the already initialized global object. Do not reinitialize it or call its DIE cleanup manually; reinitialization replaces the stored handle without first closing it, and DIE does not clear that handle.

dispatch

(--) Waits for one completion-port entry and dispatches exactly one callback.

Known issue: processing dispatcher.dispatch fails at compile time because the dispatcher uses INFINITE without importing "kernel32.INFINITE", reporting «INFINITE», Name was not found.

  • Requests at most one entry with an infinite timeout. A posted callback and an overlapped completion use the two queue-entry forms above.
  • Checks that exactly one entry was returned.
  • A failed wait prints FATAL: GetQueuedCompletionStatusEx failed, result= followed by the Win32 error and exits with status 1.

tryDispatch

(-- handled) Polls the completion port once and reports whether one entry was dispatched.
  • Polls with zero timeout. A timeout returns FALSE; one dispatched entry returns TRUE.
  • A non-timeout wait failure prints FATAL: GetQueuedCompletionStatusEx failed, result= followed by the Win32 error and exits with status 1.
  • Successful processing uses the same callback and one-entry assertions as dispatch.

post

(context callback --) Posts one callback entry carrying a Natx context value.
  • context is an opaque Natx payload carried in the queued pointer slot and passed unchanged to OnCallback; it can be zero. The posted-entry dispatch branch does not dereference it as OVERLAPPED. If the callback treats the value as an address, keep the addressed object alive and valid until the callback finishes. Posting does not copy or take ownership of that object.
  • The callback address becomes the completion key; PostQueuedCompletionStatus receives the context value in its pointer slot and zero transferred bytes.
  • A failed post prints FATAL: PostQueuedCompletionStatus failed, result= followed by the Win32 error and exits with status 1.

Remarks

  • post checks only that the callback is non-NIL, reporting dispatcher.post: invalid callback when checked. It does not verify the callback signature. Supply a Code object with the OnCallback signature, consuming one Natx context and returning no objects.
  • OnCallback and OnEventRef produce NIL Code prototypes. Assign a compatible callable before use. Initialize Context.onEvent to a non-NIL OnEventRef callback before submitting overlapped work; the overlapped dispatch branch does not perform the post NIL check.

wakeOne

(--) Posts one internal no-op callback with context value 0nx.
  • Its intended use is to release one blocked dispatch wait without an application callback.

Known issue: calling wakeOne fails compilation with «drop», Name was not found.

Dispatch model

Initialization and cleanup

Examples

Windows polling example

"String"             use
"control"            use
"windows/dispatcher" use

{} Int32 {} [
  handled: dispatcher.tryDispatch;
  ("handled=" handled LF) printList
  0
] "main" exportFunction

Expected Output

handled=FALSE

See also