☰

# std/typedthreads

Theme:

- Manual
- Standard library
- Index
- Compiler docs
- Fusion docs
- devel, stable

Search:
Source Edit

Thread support for Nim. Threads allow multiple functions to execute concurrently.

In Nim, threads are a low-level construct and using a library like `malebolgia`, `taskpools` or `weave` is recommended.

When creating a thread, you can pass arguments to it. As Nim's garbage collector does not use atomic references, sharing `ref` and other variables managed by the garbage collector between threads is not supported. Use global variables to do so, or pointers.

Memory allocated using `sharedAlloc` can be used and shared between threads.

To communicate between threads, consider using channels

# Examples

    import std/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)

    deinitLock(L)

When using a memory management strategy that supports shared heaps like `arc` or `boehm`, you can pass pointer to threads and share memory between them, but the memory must outlive the thread. The default memory management strategy, `orc`, supports this. The example below is not valid for memory management strategies that use local heaps like `refc`!

    import locks

    var l: Lock

    proc threadFunc(obj: ptr seq[int]) {.thread.} =
      withLock l:
        for i in 0..<100:
          obj[].add(obj[].len * obj[].len)

    proc threadHandler() =
      var thr: array[0..4, Thread[ptr seq[int]]]
      var s = newSeq[int]()

      for i in 0..high(thr):
        createThread(thr[i], threadFunc, s.addr)
      joinThreads(thr)
      echo s

    initLock(l)
    threadHandler()
    deinitLock(l)

# Imports

threadtypes, ansi_c, assertions

# Procs

    proc createThread(t: var Thread[void]; tp: proc () {.thread, nimcall.}) {.
        ...raises: [ResourceExhaustedError], tags: [], forbids: [].}

  Source Edit

    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.

  Source Edit

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

  Returns the thread handle of `t`. Source Edit

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

  Waits for the thread `t` to finish. Source Edit

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

  Waits for every thread in `t` to finish. Source Edit

    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.

  Source Edit

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

  Returns true if `t` is running. Source Edit

# Exports

Thread