# std/tasks

Theme:

- 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:

    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, effecttraits

# Types

    Task = object

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

# Procs

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

  Source Edit

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

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

    proc invoke(task: Task; res: pointer = nil) {.inline, ...gcsafe,
        raises: [Exception], tags: [RootEffect], forbids: [].}

  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:

      proc hello(a: int) = echo a

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

  Source Edit

# Exports

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