# std/tasks

Dark Mode

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

Search:
Source Edit

This module provides basic primitives for creating parallel programs. A `Task` should be only owned by a single Thread, it cannot be shared by threads.

Example: cmd: --gc:orc

    import std/tasks
    block:
      var num = 0
      proc hello(a: int) = inc num, a

      let b = toTask hello(13)
      b.invoke()
      assert num == 13
      # A task can be invoked multiple times
      b.invoke()
      assert num == 26

    block:
      type
        Runnable = ref object
          data: int

      var data: int
      proc hello(a: Runnable) {.nimcall.} =
        a.data += 2
        data = a.data

      when false:
        # the parameters of call must be isolated.
        let x = Runnable(data: 12)
        let b = toTask hello(x) # error ----> expression cannot be isolated: x
        b.invoke()

      let b = toTask(hello(Runnable(data: 12)))
      b.invoke()
      assert data == 14
      b.invoke()
      assert data == 16

# Imports

macros, isolation, typetraits, ansi_c

# Types

    Task = object
      callback: proc (args: pointer) {.nimcall, ...gcsafe.}
      args: pointer
      destroy: proc (args: pointer) {.nimcall, ...gcsafe.}

  `Task` contains the callback and its arguments. Source Edit

# Procs

    proc `=copy`(x: var Task; y: Task) {.error.}

  Source Edit

    proc `=destroy`(t: var Task) {.inline, ...gcsafe, raises: [Exception],
                                   tags: [RootEffect].}

  Frees the resources allocated for a `Task`. Source Edit

    proc invoke(task: Task) {.inline, ...gcsafe, raises: [Exception],
                              tags: [RootEffect].}

  Invokes the `task`. Source Edit

# Macros

    macro toTask(e: typed{nkCall | nkInfix | nkPrefix | nkPostfix | nkCommand |
        nkCallStrLit}): Task

  Converts the call and its arguments to `Task`.

  Example: cmd: --gc:orc

      proc hello(a: int) = echo a

      let b = toTask hello(13)
      assert b is Task

  Source Edit

# Exports

unsafeIsolate, =copy, =sink, extract, =destroy, Isolated, isolate