Module threads

Thread support for Nim. Note: This is part of the system module. Do not import it directly. To activate thread support you need to compile with the --threads:on command line switch.

Nim's memory model for threads is quite different from other common programming languages (C, Pascal): Each thread has its own (garbage collected) heap and sharing of memory is restricted. This helps to prevent race conditions and improves efficiency. See the manual for details of this memory model.

Example:

import locks

var
  thr: array[0..4, Thread[tuple[a,b: int]]]
  L: Lock

proc threadFunc(interval: tuple[a,b: int]) {.thread.} =
  for i in interval.a..interval.b:
    acquire(L) # lock stdout
    echo i
    release(L)

initLock(L)

for i in 0..high(thr):
  createThread(thr[i], threadFunc, (i*10, i*10+5))
joinThreads(thr)

we need to cache current threadId to not perform syscall all the time

Types

SysThread* = Handle

Thread* {.pure, final.}[TArg] = object
  core: PGcThread
  sys: SysThread
  when TArg is void:
      dataFn: proc () {.nimcall, gcsafe.}

  else:
      dataFn: proc (m: TArg) {.nimcall, gcsafe.}
      data: TArg

Procs

proc onThreadDestruction*(handler: proc () {.closure, gcsafe.})

Registers a thread local handler that is called at the thread's destruction. A thread is destructed when the .thread proc returns normally or when it raises an exception. Note that unhandled exceptions in a thread nevertheless cause the whole process to die.

proc running*[TArg](t: Thread[TArg]): bool {.inline.}

returns true if t is running.

proc handle*[TArg](t: Thread[TArg]): SysThread {.inline.}

returns the thread handle of t.

proc joinThread*[TArg](t: Thread[TArg]) {.inline.}

waits for the thread t to finish.

proc joinThreads*[TArg](t: varargs[Thread[TArg]])

waits for every thread in t to finish.

proc createThread*[TArg](t: var Thread[TArg];
                        tp: proc (arg: TArg) {.thread, nimcall.}; param: TArg)

creates a new thread t and starts its execution. Entry point is the proc tp. param is passed to tp. TArg can be void if you don't need to pass any data to the thread.

proc pinToCpu*[Arg](t: var Thread[Arg]; cpu: Natural)

pins a thread to a CPU. In other words sets a thread's affinity. If you don't know what this means, you shouldn't use this proc.

proc createThread*(t: var Thread[void]; tp: proc () {.thread, nimcall.})

proc getThreadId*(): int

get the ID of the currently running thread.