# Module actors

Actor support for Nimrod. An actor is implemented as a thread with a channel as its inbox. This module requires the `--threads:on` command line switch.

Example:

    var
      a: TActorPool[int, void]
    createActorPool(a)
    for i in 0 .. < 300:
      a.spawn(i, proc (x: int) {.thread.} = echo x)
    a.join()

# Imports

os

# Types

    TTask[TIn, TOut] = object  {.pure, final.}
      when not TOut is void: receiver
      action*: proc (x: TIn): TOut {.thread.} ## action to execute;
                                              ## sometimes useful
      shutDown*: bool             ## set to tell an actor to shut-down
      data*: TIn                  ## the data to process

  a task

    PActor[TIn, TOut] = ptr TActor[TIn, TOut]

  an actor

    TActorPool[TIn, TOut] = object  {.pure, final.}
      actors: seq[PActor[TIn, TOut]]
      when not TOut is void: outputs

  an actor pool

# Procs

    proc spawn[TIn, TOut](action: proc (self: PActor[TIn, TOut]) {.thread.}): PActor[
        TIn, TOut]

  creates an actor; that is a thread with an inbox. The caller MUST call `join` because that also frees the actor's associated resources.

    proc inbox[TIn, TOut](self: PActor[TIn, TOut]): ptr TChannel[TIn]

  gets a pointer to the associated inbox of the actor self.

    proc running[TIn, TOut](a: PActor[TIn, TOut]): bool

  returns true if the actor a is running.

    proc ready[TIn, TOut](a: PActor[TIn, TOut]): bool

  returns true if the actor a is ready to process new messages.

    proc join[TIn, TOut](a: PActor[TIn, TOut])

  joins an actor.

    proc recv[TIn, TOut](a: PActor[TIn, TOut]): TTask[TIn, TOut]

  receives a task from a's inbox.

    proc send[TIn, TOut, X, Y](receiver: PActor[TIn, TOut]; msg: TIn;
                               sender: PActor[X, Y])

  sends a message to a's inbox.

    proc send[TIn, TOut](receiver: PActor[TIn, TOut]; msg: TIn;
                         sender: ptr TChannel[TOut] = nil)

  sends a message to receiver's inbox.

    proc sendShutdown[TIn, TOut](receiver: PActor[TIn, TOut])

  send a shutdown message to receiver.

    proc reply[TIn, TOut](t: TTask[TIn, TOut]; m: TOut)

  sends a message to io's output message box.

    proc `^`[T](f: ptr TChannel[T]): T

  alias for 'recv'.

    proc createActorPool[TIn, TOut](a: var TActorPool[TIn, TOut]; poolSize = 4)

  creates an actor pool.

    proc sync[TIn, TOut](a: var TActorPool[TIn, TOut]; polling = 50)

  waits for every actor of a to finish with its work. Currently this is implemented as polling every polling ms and has a slight chance of failing since we check for every actor to be in ready state and not for messages still in ether. This will change in a later version, however.

    proc terminate[TIn, TOut](a: var TActorPool[TIn, TOut])

  terminates each actor in the actor pool a and frees the resources attached to a.

    proc join[TIn, TOut](a: var TActorPool[TIn, TOut])

  short-cut for sync and then terminate.

    proc spawn[TIn, TOut](p: var TActorPool[TIn, TOut]; input: TIn;
                          action: proc (input: TIn): TOut {.thread.}): ptr TChannel[
        TOut]

  uses the actor pool to run `action(input)` concurrently. spawn is guaranteed to not block.

    proc spawn[TIn](p: var TActorPool[TIn, void]; input: TIn;
                    action: proc (input: TIn) {.thread.})

  uses the actor pool to run `action(input)` concurrently. spawn is guaranteed to not block.

Generated: 2013-05-21 09:55:24 UTC