Module threadpool

Implements Nim's 'spawn'.

Imports

cpuinfo, cpuload, locks

Types

foreign = object

a region that indicates the pointer comes from a foreign thread heap.

FlowVarBase = ref FlowVarBaseObj

untyped base class for 'FlowVar[T]'

FlowVar[T] = ref FlowVarObj[T]

a data flow variable

ThreadId = range[0 .. 32 - 1]

Consts

MaxThreadPoolSize = 256

maximal size of the thread pool. 256 threads should be good enough for anybody ;-)

MaxDistinguishedThread = 32

maximal number of "distinguished" threads.

Procs

proc await(fv: FlowVarBase) {.raises: [], tags: [].}

waits until the value for the flowVar arrives. Usually it is not necessary to call this explicitly.

proc awaitAndThen[T](fv: FlowVar[T]; action: proc (x: T) {.closure.})

blocks until the fv is available and then passes its value to action. Note that due to Nim's parameter passing semantics this means that T doesn't need to be copied and so awaitAndThen can sometimes be more efficient than ^.

proc unsafeRead[T](fv: FlowVar[ref T]): foreign ptr T

blocks until the value is available and then returns this value.

proc `^`[T](fv: FlowVar[ref T]): ref T

blocks until the value is available and then returns this value.

proc `^`[T](fv: FlowVar[T]): T

blocks until the value is available and then returns this value.

proc awaitAny(flowVars: openArray[FlowVarBase]): int {.raises: [], tags: [].}

awaits any of the given flowVars. Returns the index of one flowVar for which a value arrived. A flowVar only supports one call to 'awaitAny' at the same time. That means if you await([a,b]) and await([b,c]) the second call will only await 'c'. If there is no flowVar left to be able to wait on, -1 is returned. Note: This results in non-deterministic behaviour and so should be avoided.

proc isReady(fv: FlowVarBase): bool {.raises: [], tags: [].}

Determines whether the specified FlowVarBase's value is available.

If true awaiting fv will not block.

proc setMinPoolSize(size: range[1 .. MaxThreadPoolSize]) {.raises: [], tags: [].}

sets the minimal thread pool size. The default value of this is 4.

proc setMaxPoolSize(size: range[1 .. MaxThreadPoolSize]) {.raises: [], tags: [].}

sets the maximal thread pool size. The default value of this is MaxThreadPoolSize.

proc preferSpawn(): bool {.raises: [], tags: [].}

Use this proc to determine quickly if a 'spawn' or a direct call is preferable. If it returns 'true' a 'spawn' may make sense. In general it is not necessary to call this directly; use 'spawnX' instead.

proc spawn(call: typed): void {.magic: "Spawn".}

always spawns a new task, so that the 'call' is never executed on the calling thread. 'call' has to be proc call 'p(...)' where 'p' is gcsafe and has a return type that is either 'void' or compatible with FlowVar[T].

proc pinnedSpawn(id: ThreadId; call: typed): void {.magic: "Spawn".}

always spawns a new task on the worker thread with id, so that the 'call' is always executed on the thread. 'call' has to be proc call 'p(...)' where 'p' is gcsafe and has a return type that is either 'void' or compatible with FlowVar[T].

proc parallel(body: untyped) {.magic: "Parallel".}

a parallel section can be used to execute a block in parallel. body has to be in a DSL that is a particular subset of the language. Please refer to the manual for further information.

proc sync() {.raises: [], tags: [].}

a simple barrier to wait for all spawn'ed tasks. If you need more elaborate waiting, you have to use an explicit barrier.

Templates

template spawnX(call): void

spawns a new task if a CPU core is ready, otherwise executes the call in the calling thread. Usually it is advised to use 'spawn' in order to not block the producer for an unknown amount of time. 'call' has to be proc call 'p(...)' where 'p' is gcsafe and has a return type that is either 'void' or compatible with FlowVar[T].