# system/threads

Dark Mode

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

Search:
Source Edit

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.

# 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)

# Types

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

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

      when hasAllocStack:
          rawStack: pointer

  Source Edit

# Procs

    proc `=copy`*[TArg](x: var Thread[TArg]; y: Thread[TArg]) {.error.}

  Source Edit

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

  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 getThreadId*(): int

  Gets the ID of the currently running 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 onThreadDestruction*(handler: proc () {.closure, ...gcsafe, raises: [].})

  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.

  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