ErlangActor improvements

* Allow actors to accept initial arguments
* Separate Down into message and signal
* Rename Exit signal to Terminate
* Make sure monitor and link send after message
  which terminates the actor will never return anything
  other then NoActor
* cleanup messages and signals

Author: pitr-ch

docs-source/erlang_actor.in.md

@@ -4,24 +4,25 @@ The simplest example is to use the actor as an asynchronous execution.
 Although, `Promises.future { 1 + 1 }` is better suited for that purpose.
 
 ```ruby
-actor = Concurrent::ErlangActor.spawn(:on_thread, name: 'addition') { 1 + 1 }
+actor = Concurrent::ErlangActor.spawn(type: :on_thread, name: 'addition') { 1 + 1 }
 actor.terminated.value!
 ```
 
 Let's send some messages and maintain some internal state 
 which is what actors are good for.
 
 ```ruby
-actor = Concurrent::ErlangActor.spawn(:on_thread, name: 'sum') do
+actor = Concurrent::ErlangActor.spawn(type: :on_thread, name: 'sum') do
   sum = 0 # internal state
   # receive and sum the messages until the actor gets :done
   while true
     message = receive
     break if message == :done
     # if the message is asked and not only told, 
-    # reply with a current sum
+    # reply with the current sum (has no effect if actor was not asked)
     reply sum += message   
   end
+  # The final value of the actor
   sum
 end
 ```
@@ -36,15 +37,74 @@ actor.tell(1).tell(1)
 actor.ask 10
 # stop the actor
 actor.tell :done
+# The final value of the actor 
 actor.terminated.value!
 ```
 
-### Receiving
+### Actor types
+
+There are two types of actors. 
+The type is specified when calling spawn as a first argument, 
+`Concurrent::ErlangActor.spawn(type: :on_thread, ...` or 
+`Concurrent::ErlangActor.spawn(type: :on_pool, ...`.
+
+The main difference is in how receive method returns.
+ 
+-   `:on_thread` it blocks the thread until message is available, 
+    then it returns or calls the provided block first. 
+ 
+-   However, `:on_pool` it has to free up the thread on the receive 
+    call back to the pool. Therefore the call to receive ends the 
+    execution of current scope. The receive has to be given block
+    or blocks that act as a continuations and are called 
+    when there is message available.
+ 
+Let's have a look at how the bodies of actors differ between the types:
+
+```ruby
+ping = Concurrent::ErlangActor.spawn(type: :on_thread) { reply receive }
+ping.ask 42
+```
+
+It first calls receive, which blocks the thread of the actor. 
+When it returns the received message is passed an an argument to reply,
+which replies the same value back to the ask method. 
+Then the actor terminates normally, because there is nothing else to do.
+
+However when running on pool a block with code which should be evaluated 
+after the message is received has to be provided. 
+
+```ruby
+ping = Concurrent::ErlangActor.spawn(type: :on_pool) { receive { |m| reply m } }
+ping.ask 42
+```
+
+It starts by calling receive which will remember the given block for later
+execution when a message is available and stops executing the current scope.
+Later when a message becomes available the previously provided block is given
+the message and called. The result of the block is the final value of the 
+normally terminated actor.
+
+The direct blocking style of `:on_thread` is simpler to write and more straight
+forward however it has limitations. Each `:on_thread` actor creates a Thread 
+taking time and resources. 
+There is also a limited number of threads the Ruby process can create 
+so you may hit the limit and fail to create more threads and therefore actors.  
+
+Since the `:on_pool` actor runs on a poll of threads, its creations 
+is faster and cheaper and it does not create new threads. 
+Therefore there is no limit (only RAM) on how many actors can be created.
+
+To simplify, if you need only few actors `:on_thread` is fine. 
+However if you will be creating hundreds of actors or 
+they will be short-lived `:on_pool` should be used.      
+
+### Receiving messages
 
 Simplest message receive.
 
 ```ruby
-actor = Concurrent::ErlangActor.spawn(:on_thread) { receive }
+actor = Concurrent::ErlangActor.spawn(type: :on_thread) { receive }
 actor.tell :m
 actor.terminated.value!
 ```
@@ -53,9 +113,9 @@ which also works for actor on pool,
 because if no block is given it will use a default block `{ |v| v }` 
 
 ```ruby
-actor = Concurrent::ErlangActor.spawn(:on_pool) { receive { |v| v } }
+actor = Concurrent::ErlangActor.spawn(type: :on_pool) { receive { |v| v } }
 # can simply be following
-actor = Concurrent::ErlangActor.spawn(:on_pool) { receive }
+actor = Concurrent::ErlangActor.spawn(type: :on_pool) { receive }
 actor.tell :m
 actor.terminated.value!
 ```
@@ -64,7 +124,7 @@ The received message type can be limited.
 
 ```ruby
 Concurrent::ErlangActor.
-  spawn(:on_thread) { receive(Numeric).succ }.
+  spawn(type: :on_thread) { receive(Numeric).succ }.
   tell('junk'). # ignored message
   tell(42).
   terminated.value!
@@ -74,7 +134,7 @@ On pool it requires a block.
 
 ```ruby
 Concurrent::ErlangActor.
-  spawn(:on_pool) { receive(Numeric) { |v| v.succ } }.
+  spawn(type: :on_pool) { receive(Numeric) { |v| v.succ } }.
   tell('junk'). # ignored message
   tell(42).
   terminated.value!
@@ -85,7 +145,7 @@ as well.
 
 ```ruby
 Concurrent::ErlangActor.
-  spawn(:on_thread) { receive(Numeric) { |v| v.succ } }.
+  spawn(type: :on_thread) { receive(Numeric) { |v| v.succ } }.
   tell('junk'). # ignored message
   tell(42).
   terminated.value!
@@ -94,7 +154,7 @@ Concurrent::ErlangActor.
 The `receive` method can be also used to dispatch based on the received message.
 
 ```ruby
-actor = Concurrent::ErlangActor.spawn(:on_thread) do
+actor = Concurrent::ErlangActor.spawn(type: :on_thread) do
   while true
     receive(on(Symbol) { |s| reply s.to_s },
             on(And[Numeric, -> v { v >= 0 }]) { |v| reply v.succ },
@@ -137,7 +197,7 @@ module Behaviour
   end
 end
 
-actor = Concurrent::ErlangActor.spawn(:on_pool, environment: Behaviour) { body }
+actor = Concurrent::ErlangActor.spawn(type: :on_pool, environment: Behaviour) { body }
 actor.ask 1
 actor.ask 2
 actor.ask :value
@@ -153,7 +213,7 @@ that will keep the receive rules until another receive is called
 replacing the kept rules.
 
 ```ruby
-actor = Concurrent::ErlangActor.spawn(:on_pool) do
+actor = Concurrent::ErlangActor.spawn(type: :on_pool) do
   receive(on(Symbol) { |s| reply s.to_s },
           on(And[Numeric, -> v { v >= 0 }]) { |v| reply v.succ },
           # put last works as else
@@ -173,71 +233,13 @@ actor.ask "junk" rescue $!
 actor.terminated.result
 ```
 
-### Actor types
-
-There are two types of actors. 
-The type is specified when calling spawn as a first argument, 
-`Concurrent::ErlangActor.spawn(:on_thread, ...` or 
-`Concurrent::ErlangActor.spawn(:on_pool, ...`.
-
-The main difference is in how receive method returns.
- 
--   `:on_thread` it blocks the thread until message is available, 
-    then it returns or calls the provided block first. 
- 
--   However, `:on_pool` it has to free up the thread on the receive 
-    call back to the pool. Therefore the call to receive ends the 
-    execution of current scope. The receive has to be given block
-    or blocks that act as a continuations and are called 
-    when there is message available.
- 
-Let's have a look at how the bodies of actors differ between the types:
-
-```ruby
-ping = Concurrent::ErlangActor.spawn(:on_thread) { reply receive }
-ping.ask 42
-```
-
-It first calls receive, which blocks the thread of the actor. 
-When it returns the received message is passed an an argument to reply,
-which replies the same value back to the ask method. 
-Then the actor terminates normally, because there is nothing else to do.
-
-However when running on pool a block with code which should be evaluated 
-after the message is received has to be provided. 
-
-```ruby
-ping = Concurrent::ErlangActor.spawn(:on_pool) { receive { |m| reply m } }
-ping.ask 42
-```
-
-It starts by calling receive which will remember the given block for later
-execution when a message is available and stops executing the current scope.
-Later when a message becomes available the previously provided block is given
-the message and called. The result of the block is the final value of the 
-normally terminated actor.
-
-The direct blocking style of `:on_thread` is simpler to write and more straight
-forward however it has limitations. Each `:on_thread` actor creates a Thread 
-taking time and resources. 
-There is also a limited number of threads the Ruby process can create 
-so you may hit the limit and fail to create more threads and therefore actors.  
-
-Since the `:on_pool` actor runs on a poll of threads, its creations 
-is faster and cheaper and it does not create new threads. 
-Therefore there is no limit (only RAM) on how many actors can be created.
-
-To simplify, if you need only few actors `:on_thread` is fine. 
-However if you will be creating hundreds of actors or 
-they will be short-lived `:on_pool` should be used.      
-
 ### Erlang behaviour
 
 The actor matches Erlang processes in behaviour. 
 Therefore it supports the usual Erlang actor linking, monitoring, exit behaviour, etc.
 
 ```ruby
-actor = Concurrent::ErlangActor.spawn(:on_thread) do
+actor = Concurrent::ErlangActor.spawn(type: :on_thread) do
   spawn(link: true) do # equivalent of spawn_link in Erlang
     terminate :err # equivalent of exit in Erlang    
   end
@@ -247,13 +249,30 @@ end
 actor.terminated.value!
 ```
 
-### TODO
-
-*   receives
-*   More erlang behaviour examples
-*   Back pressure with bounded mailbox
-*   _op methods
-*   types of actors
-*   always use timeout
-*   drop and log unrecognized messages, or just terminate
-*   Functions module
+The methods have same or very similar name to be easily found. 
+The one exception from the original Erlang naming is exit.
+To avoid clashing with `Kernel#exit` it's called `terminate`. 
+
+Until there is more information available here, the chapters listed below from 
+a book [lern you some Erlang](https://learnyousomeerlang.com) 
+are excellent source of information. 
+The Ruby ErlangActor implementation has same behaviour. 
+
+-   [Links](https://learnyousomeerlang.com/errors-and-processes#links)
+-   [It's a trap](https://learnyousomeerlang.com/errors-and-processes#its-a-trap)
+-   [Monitors](https://learnyousomeerlang.com/errors-and-processes#monitors)
+
+If anything behaves differently than in Erlang, please file an issue.
+
+### Chapters or points to be added
+
+*   More erlang behaviour examples.
+*   The mailbox can be bounded in size, 
+    then the tell and ask will block until there is space available in the mailbox.
+    Useful for building systems with backpressure.
+*   `#tell_op` and `ask_op` method examples, integration with promises.
+*   Best practice: always use timeout, 
+    and do something if the message does not arrive, don't leave the actor stuck.
+*   Best practice: drop and log unrecognized messages, 
+    or be even more defensive and terminate.
+*   Environment definition for actors.