further tutorial improvements

Author: hyperthunk

Diff for: documentation.md

@@ -287,71 +287,27 @@ a set of children, starting, stopping and restarting them as necessary.
 
 ### Stopping Processes
 
-Some processes, like the *outer* process in the previous example, will run until
-they've completed and then return their value. This is just as we find with IO action,
-and there is an instance of `MonadIO` for the `Process` monad, so you can `liftIO` if
-you need to evaluate IO actions.
-
 Because processes are implemented with `forkIO` we might be tempted to stop
 them by throwing an asynchronous exception to the process, but this is almost
-certainly the wrong thing to do. Instead we might send a kind of poison pill,
-which the process *ought* to handle by shutting down gracefully. Unfortunately
-because of the asynchronous nature of sending, this is no good because `send`
-will not fail under any circumstances. In fact, because `send` doesn't block,
-we therefore have no way to know if the recipient existed at the time we sent the
-poison pill. Even if the recipient did exist, we still have no guarantee that
-the message we sent actually arrived - the network connection between the nodes
-could have broken, for example. Making this *shutdown* protocol synchronous is
-no good either - how long would we wait for a reply? Indefinitely?
-
-Exit signals come in two flavours - those that can
-be caught and those that cannot. A call to
-`exit :: (Serializable a) => ProcessId -> a -> Process ()` will dispatch an
-exit signal to the specified process. These *signals* can be intercepted and
-handled by the destination process however, so if you need to terminate the
-process in a brutal way, you can use the `kill :: ProcessId -> String -> Process ()`
-function, which sends an exit signal that cannot be handled.
-
-------
-#### __An important note about exit signals__
-
-Exit signals in Cloud Haskell are unlike asynchronous exceptions in regular
-haskell code. Whilst a process *can* use asynchronous exceptions - there's
-nothing stoping this since the `Process` monad is an instance of `MonadIO` -
-exceptions thrown are not bound by the same ordering guarantees as messages
-delivered to a process. Link failures and exit signals *might* be implemented
-using asynchronous exceptions - that is the case in the current
-implementation - but these are implemented in such a fashion that if you
-send a message and *then* an exit signal, the message is guaranteed to arrive
-first.
-
-You should avoid throwing your own exceptions in code where possible. Instead,
-you should terminate yourself, or another process, using the built-in primitives
-`exit`, `kill` and `die`.
-
-{% highlight haskell %}
-exit pid reason  -- force `pid` to exit - reason can be any `Serializable` message
-kill pid reason  -- reason is a string - the *kill* signal cannot be caught
-die reason       -- as 'exit' but kills *us*
-{% endhighlight %}
-
-The `exit` and `kill` primitives do essentially the same thing, but catching
-the specific exception thrown by `kill` is impossible, making `kill` an
-*untrappable exit signal*. Of course you could trap **all** exceptions, but
-you already know that's a very bad idea right!?
-
-The `exit` primitive is a little different. This provides support for trapping
-exit signals in a generic way, so long as your *exit handler* is able to
-recognise the underlying type of the 'exit reason'. This (reason for exiting)
-is stored as a raw `Message`, so if your handler takes the appropriate type
-as an input (and therefore the `Message` can be decoded and passed to the
-handler) then the handler will run. This is pretty much the same approach as
-exception handling using `Typeable`, except that we decide whether or not the
-exception can be handled based on the type of `reason` instead of the type of
-the exception itself.
-
-Calling `die` will immediately raise an exit signal (i.e., `ProcessExitException`)
-in the calling process.
+certainly the wrong thing to do. Firstly, processes might reside on a remote
+node, in which case throwing an exception is impossible. Secondly, if we send
+some messages to a process' mailbox and then dispatch an exception to kill it,
+there is no guarantee that the subject will receive our message before being
+terminated by the asynchronous exception.
+
+To terminate a process unconditionally, we use the `kill` primitive, which
+dispatches an asynchronous exception (killing the subject) safely, respecting
+remote calls to processes on disparate nodes and observing message ordering
+guarantees such that `send pid "hello" >> kill pid "goodbye"` behaves quite
+unsurprisingly, delivering the message before the kill signal.
+
+Exit signals come in two flavours however - those that can be caught and those
+that cannot. Whilst a call to `kill` results in an _un-trappable_ exception,
+a call to `exit :: (Serializable a) => ProcessId -> a -> Process ()` will dispatch
+an exit signal to the specified process that can be caught. These *signals* are
+intercepted and handled by the destination process using `catchExit`, allowing
+the receiver to match on the `Serializable` datum tucked away in the *exit signal*
+and decide whether to oblige or not.
 
 ----
 
@@ -463,6 +419,12 @@ The API for `Async` is fairly rich, so reading the haddocks is suggested.
 
 #### Managed Processes
 
+The main idea behind a `ManagedProcess` is to separate the functional
+and non-functional aspects of an actor. By functional, we mean whatever
+application specific task the actor performs, and by non-functional
+we mean the *concurrency* or, more precisely, handling of the process'
+mailbox and its interaction with other actors (i.e., clients).
+
 Looking at *typed channels*, we noted that their insistence on a specific input
 domain was more *haskell-ish* than working with bare send and receive primitives.
 The `Async` sub-package also provides a type safe interface for receiving data,
@@ -471,12 +433,12 @@ although it is limited to running a computation and waiting for its result.
 The [Control.Distributed.Processes.Platform.ManagedProcess][21] API provides a
 number of different abstractions that can be used to achieve similar benefits
 in your code. It works by introducing a standard protocol between your process
-and the *world around*, which governs how to handle request/reply processing,
-exit signals, timeouts, sleep/hibernation with `threadDelay` and even provides
+and the *world outside*, which governs how to handle request/reply processing,
+exit signals, timeouts, sleeping/hibernation with `threadDelay` and even provides
 hooks that terminating processes can use to clean up residual state.
 
 The [API documentation][21] is quite extensive, so here we will simply point
-out the obvious differences. A implemented implemented with `ManagedProcess`
+out the obvious differences. A process implemented with `ManagedProcess`
 can present a type safe API to its callers (and the server side code too!),
 although that's not its primary benefit. For a very simplified example:
 
@@ -514,6 +476,18 @@ just provides callback functions which take some state and either return a
 new state and a reply, or just a new state. The process is *managed* in the
 sense that its mailbox is under someone else's control.
 
+A NOTE ABOUT THE CALL API AND THAT IT WILL FAIL (WITH UNHANDLED MESSAGE) IF
+THE CALLER IS EXPECTING A TYPE THAT DIFFERS FROM THE ONE THE SERVER PLANS
+TO RETURN, SINCE THE RETURN TYPE IS ENCODED IN THE CALL-MESSAGE TYPE ITSELF.
+
+TODO: WRITE A TEST TO PROVE THE ABOVE
+
+TODO: ADD AN API BASED ON SESSION TYPES AS A KIND OF MANAGED PROCESS.....
+
+In a forthcoming tutorial, we'll look at the `Control.Distributed.Process.Platform.Task`
+API, which looks a lot like `Async` but manages exit signals in a single thread and makes
+configurable task pools and task supervision strategy part of its API.
+
 More complex examples of the `ManagedProcess` API can be seen in the
 [Managed Processes tutorial][22]. API documentation for HEAD is available
 [here][21].

Diff for: tutorials/ch-tutorial1.md

@@ -1,7 +1,7 @@
 ---
 layout: tutorial
 categories: tutorial
-sections: ['Getting Started', 'Create a node', 'Sending messages', 'Spawning Remote Processes']
+sections: ['Getting Started', 'Installing from source', 'Creating a node', 'Sending messages', 'Spawning Remote Processes']
 title: Getting Started
 ---
 
@@ -27,7 +27,7 @@ run `make` to obtain the complete set of source repositories for building
 Cloud Haskell. The additional makefiles bundled with the umbrella assume
 that you have a recent version of cabal-dev installed.
 
-### Create a node
+### Creating a node
 
 Cloud Haskell's *lightweight processes* reside on a "node", which must
 be initialised with a network transport implementation and a remote table.
@@ -78,16 +78,16 @@ will send one to ourselves!
 {% endhighlight %}
 
 Lightweight processes are implemented as `forkIO` threads. In general we will
-try to forget about this implementation detail, but let us note that we
+try to forget about this implementation detail, but let's note that we
 haven't deadlocked our own thread by sending to and receiving from its mailbox
 in this fashion. Sending messages is a completely asynchronous operation - even
 if the recipient doesn't exist, no error will be raised and evaluating `send`
-will not block the caller, not even if the caller is sending messages to itself!
+will not block the caller, even if the caller is sending messages to itself!
 
-Receiving works quite the other way around, blocking the caller until a message
+Receiving works the opposite way, blocking the caller until a message
 matching the expected type arrives in our (conceptual) mailbox. If multiple
-messages of that type are in the queue, they will be returned in FIFO
-order, otherwise the caller will be blocked until a message arrives that can be
+messages of that type are present in the mailbox, they're be returned in FIFO
+order, if not, the caller is blocked until a message arrives that can be
 decoded to the correct type.
 
 Let's spawn two processes on the same node and have them talk to each other.
@@ -150,15 +150,14 @@ In the _echo server_ above, our first match prints out whatever string it
 receives. If first message in out mailbox is not a `String`, then our second
 match is evaluated. This, given a tuple `t :: (ProcessId, String)`, will send
 the `String` component back to the sender's `ProcessId`. If neither match
-succeeds, the echo server process blocks until another message arrives and
+succeeds, the echo server blocks until another message arrives and
 tries again.
 
 ### Serializable Data
 
 Processes may send any datum whose type implements the `Serializable` typeclass,
-which is done indirectly by implementing `Binary` and deriving `Typeable`.
-Implementations are already provided for off of Cloud Haskell's primitives
-and the most commonly used data structures.
+which is done indirectly by deriving `Binary` and `Typeable`. Implementations are 
+provided for most of Cloud Haskell's primitives and various common data types.
 
 ### Spawning Remote Processes
 
@@ -212,6 +211,11 @@ main = do
  -- etc
 {% endhighlight %}
 
+Note that we're not limited to sending `Closure`s - it is possible to send data
+without having static values, and assuming the receiving code is able to decode
+this data and operate on it, we can easily put together a simple AST that maps
+to operations we wish to execute remotely.
+
 ------
 
 [1]: /static/doc/distributed-process/Control-Distributed-Process.html#v:Message