lib/actors/README.md

   1 # Nit Actor Model
   2
   3 This group introduces the `actors` module which contains the abstraction of a Nit Actor Model,
   4 based on Celluloid (https://github.com/celluloid/celluloid).
   5
   6 ## What is an actor ?
   7
   8 An actor is an entity which receives messages and does some kind of computation based on it.
   9 An actor has a mailbox in which it receives its messages, and process them one at a time.
  10
  11
  12 ## `actor` annotation
  13
  14 The `actors` module introduces the annotation `actor` which is to be used on classes.
  15 This annotation transform a normal Nit class into an actor.
  16
  17 In practice, it adds a new property `async` to the annotated class.
  18 When using `async` on your annotated class, this means that you want your calls to be asynchronous,
  19 executed by the actor.
  20
  21 For instance, if you call `a.async.foo` and `foo` doesn't have a return value, it will send
  22 a message to the mailbox of the actor attached to `a` which will process it asynchronously.
  23
  24 On the other hand, if you call `a.async.bar` and `bar` returns an`Int`, it will still send
  25 a message to the actor, but you'll get a `Future[Int]` to be able to retrieve the value.
  26 When using `join` on the future, the calling thread will wait until the value of the future is set.
  27
  28 ## Managing actors
  29
  30 When you annotate a class with `actor` and create an instance of it with `new`, the actor is not
  31 automatically created (which means you can completely skip the use of the actors if you
  32 don't need them for a specific program).
  33
  34 The `async` added property is actually created lazily when you use it.
  35
  36 Actors are not automatically garbage collected, but you have solutions to terminate them
  37 if you need to. For this, you need to use the `async` property of your annotated class :
  38
  39 * `async.terminate` sends a shutdown message to the actor telling him to stop, so he'll finish
  40 processing every other messages in his mailbox before terminating properly. Every other messages sent
  41 to this actor after he received the shutdown message won't be processed.
  42 * `async.terminate_now` sends a shutdown message too, but this time it places it first, so
  43 if the actor is processing one message now, the next one will be the shutdown message, discarding
  44 every messages in its mailbox.
  45 * `async.wait_termination` wait for the actor to terminate properly. This call is synchronous.
  46 * `async.kill`. If you really need this actor to stop, without any regards of what he was doing
  47 or in which state he'll leave the memory, you can with this call. it's synchronous but not really
  48 blocking, since it's direcly canceling the native pthread associated to the actor.
  49
  50 For now, there isn't any mecanism to recreate and actor after it was terminated.
  51 Sending messages after terminating it results in unspecified behaviour.
  52
  53 ## Waiting for all actors to finish processing
  54
  55 Let's imagine you create a whole bunch of actors and make them do things asynchronously from the main thread.
  56 You don't want your program to exit right after giving work to your actors.
  57 To prevent that, we added a mecanism that waits before all your actors finished all their messages
  58 before quitting.
  59
  60 It's materialized by the `active_actors` property added to `Sys` which is a `ReverseBlockingQueue`.
  61 In short, the `is_empty` method on this list is blocking until the list is effectively empty.
  62 When every actors finished working, and we're sure they won't even send another message to another
  63 actor, `active_actors` is empty.
  64
  65 You can use this property as a mean of synchronisation in some specific cases (for example if you're
  66 using actors for fork/join parallelism instead of concurrency).
  67
  68
  69 ## Examples
  70
  71 You can find example of differents small programs implemented with Nit actors in the `examples`
  72 directory. For a really simple example, you can check `examples/simple`.