Types

ThreadProxyError = object of CatchableError
ThreadNotFoundError = object of ThreadProxyError threadName*: string: Raised when operation on thread with name threadName cannot be found
ThreadUncleanableError = object of ThreadProxyError threadName*: string: Raised when thread cannot be clean-up
ReceiverNotFoundError = object of ThreadProxyError sender*: string receiver*: string: Raised whenever sending a message to unknown receiver
MessageUndeliveredError = object of ThreadProxyError kind*: ThreadMessageKind action*: string sender*: string data*: JsonNode: Raised when message cannot be send to channel
ActionConflictError = object of ThreadProxyError threadName*: string action*: string: Raised when registering action is not unique
NameConflictError = object of ThreadProxyError threadName*: string: Raised when name of thread is not unique
PollConflictError = object of ThreadProxyError threadName*: string: Raised when poll() is called while ThreadProxy is running
HandlerIsNilError = object of ThreadProxyError: Raised when handler is nil
ResponseError = object of ThreadProxyError action*: string errorMessage*: string: Raised when the opposite failed to reply
ThreadActionHandler = proc (data: JsonNode): Future[JsonNode] {...}{.gcsafe.}: Signature for action handler
ThreadDefaultActionHandler = proc (action: string; data: JsonNode): Future[JsonNode] {...}{. gcsafe.}: Signature for default action handler
ThreadProxy = ref object of RootObj active: bool name: string mainFastChannel, fastChannel, channel: ThreadChannelPtr actions: Table[string, ThreadActionHandler] defaultAction: ThreadDefaultActionHandler callbackSeed: int jsonCallbacks: Table[int, Future[JsonNode]] channelCallbacks: Table[int, Future[ThreadChannelPtr]] ## local cache to resolve name to channel directory: Table[string, ThreadChannelPtr]
MainThreadProxy = ref object of ThreadProxy channels: Table[string, ThreadChannelPair] threads: Table[string, ThreadWrapper]
ThreadToken = object name: string mainFastChannel, fastChannel, channel: ThreadChannelPtr
ThreadMainProc = proc (proxy: ThreadProxy) {...}{.thread, nimcall.}: Signature for entry function of thread

Procs

proc newThreadProxy(token: ThreadToken): ThreadProxy {...}{.raises: [], tags: [].}

Create a new ThreadProxy

proc newMainThreadProxy(name: string; channelMaxItems: int = 0): MainThreadProxy {...}{. raises: [], tags: [].}

Create a new MainThreadProxy

proc name(proxy: ThreadProxy): string {...}{.inline, raises: [], tags: [].}

Get the name of thread

proc isNameAvailable(proxy: MainThreadProxy; name: string): bool {...}{.inline, raises: [], tags: [].}

Chekc if the name is available to use

proc isRunning(proxy: ThreadProxy): bool {...}{.inline, raises: [], tags: [].}

Check if proxy is running

proc on(proxy: ThreadProxy; action: string; handler: ThreadActionHandler) {...}{. raises: [ActionConflictError, HandlerIsNilError, Exception], tags: [RootEffect].}

Set handler for action

proc onDefault(proxy: ThreadProxy; handler: ThreadDefaultActionHandler) {...}{. raises: [HandlerIsNilError], tags: [].}

Set default handler for all unhandled action

proc send(proxy: ThreadProxy; target: string; action: string; data: JsonNode = nil): Future[ void] {...}{.raises: [Exception, FutureError], tags: [RootEffect].}

Send data to target channel.

The returned future complete once the message is successfully placed on target channel. otherwise fail with MessageUndeliveredError.

proc ask(proxy: ThreadProxy; target: string; action: string; data: JsonNode = nil): Future[ JsonNode] {...}{.raises: [Exception, ValueError, FutureError], tags: [RootEffect].}

Send data to target and wait for the return.

The returned future will complete with the result from target is received. It may fail with many kind of errors.

proc process(proxy: ThreadProxy): bool {...}{.gcsafe, raises: [ValueError, Exception, KeyError, DeadThreadError, FutureError, Defect], tags: [RootEffect].}

Process one message on channel. Return false if channel is empty, otherwise true.

proc stop(proxy: ThreadProxy) {...}{.inline, raises: [], tags: [].}

Stop processing messages. The future returned from poll() will complete.

proc poll(proxy: ThreadProxy; interval: int = 16): Future[void] {...}{.raises: [FutureError, Exception, ValueError, KeyError, DeadThreadError, Defect], tags: [RootEffect, TimeEffect].}

Start processing channel messages. Raise PollConflictError if proxy is already running

proc createToken(proxy: MainThreadProxy; name: string; channelMaxItems: int = 0): ThreadToken {...}{. raises: [NameConflictError], tags: [].}

Create token for new threadproxy

proc createThread(proxy: MainThreadProxy; name: string; main: ThreadMainProc; channelMaxItems: int = 0) {...}{. raises: [NameConflictError, Exception, ResourceExhaustedError], tags: [RootEffect].}

Create new thread managed by proxy with an unique name

proc pinToCpu(proxy: MainThreadProxy; name: string; cpu: Natural) {...}{. raises: [ThreadNotFoundError, KeyError], tags: [].}

Pin thread name to cpu. Raise ThreadNotFoundError if name not found.

proc isThreadRunning(proxy: MainThreadProxy; name: string): bool {...}{. raises: [ThreadNotFoundError, KeyError], tags: [].}

Check whether thread is running. Applicable only to threads created with createThread

proc cleanThreads(proxy: MainThreadProxy): Future[void] {...}{.raises: [ ThreadNotFoundError, KeyError, FutureError, Exception, ValueError, DeadThreadError], tags: [RootEffect].}

Clean up resource of non-running threads

Templates

template onData(proxy: ThreadProxy; action: string; body: untyped): void: Template version of on, saving you from typing proc(data: JsonNode): Future[JsonNode] {.gcsafe,async.} = ... every time. The argument data is injected and so the name onData.
template onDefaultData(proxy: ThreadProxy; body: untyped): Template version of onDefault