[MLton-commit] r5339

[Vesa Karvonen]

Renamed put to fill and Put to Full.  Added some documentation.  Trivial
simplification of the implementation of {each}.

----------------------------------------------------------------------

U   mltonlib/trunk/com/ssh/async/unstable/detail/async.sml
U   mltonlib/trunk/com/ssh/async/unstable/public/async.sig

----------------------------------------------------------------------

Modified: mltonlib/trunk/com/ssh/async/unstable/detail/async.sml
===================================================================
--- mltonlib/trunk/com/ssh/async/unstable/detail/async.sml	2007-02-26 20:54:42 UTC (rev 5338)
+++ mltonlib/trunk/com/ssh/async/unstable/detail/async.sml	2007-02-26 21:58:13 UTC (rev 5339)
@@ -5,7 +5,7 @@
  *)
 
 structure Async :> ASYNC = struct
-   exception Put
+   exception Full
 
    structure Queue = struct
       open Queue
@@ -49,8 +49,8 @@
                          INL ef => lp (es & ef::efs)
                        | result => result))
       fun once (T t) = Sum.app (fn ef => ef (Handler.new ()), pass ()) (t ())
-      fun each e = once (on (e, fn () => each e))
       fun when ? = once (on ?)
+      fun each e = when (e, fn () => each e)
       fun every ? = each (on ?)
       val any = once o choose
    end
@@ -85,9 +85,9 @@
                       case !st of
                          SOME v => INR (const v)
                        | NONE => INL (Queue.enque rs))
-      fun put (T {rs, st}) v =
+      fun fill (T {rs, st}) v =
           case !st of
-             SOME _ => raise Put
+             SOME _ => raise Full
            | NONE => (st := SOME v ; Queue.appClear (Handler.schedule v) rs)
    end
 
@@ -99,9 +99,9 @@
                       case !st of
                          SOME v => INR (fn () => (st := NONE ; v))
                        | NONE => INL (Queue.enque ts))
-      fun put (T {ts, st}) v =
+      fun fill (T {ts, st}) v =
           case !st of
-             SOME _ => raise Put
+             SOME _ => raise Full
            | NONE =>
              case Queue.find (not o Handler.scheduled) ts of
                 NONE => st := SOME v
@@ -127,7 +127,7 @@
          val ost = !st
          val nst = IVar.new ()
       in 
-         st := nst ; IVar.put ost (N (v, nst))
+         st := nst ; IVar.fill ost (N (v, nst))
       end
    end
 end

Modified: mltonlib/trunk/com/ssh/async/unstable/public/async.sig
===================================================================
--- mltonlib/trunk/com/ssh/async/unstable/public/async.sig	2007-02-26 20:54:42 UTC (rev 5338)
+++ mltonlib/trunk/com/ssh/async/unstable/public/async.sig	2007-02-26 21:58:13 UTC (rev 5339)
@@ -4,32 +4,64 @@
  * See the LICENSE file or http://mlton.org/License for details.
  *)
 
+(**
+ * Asynchronous programming interface.
+ *)
 signature ASYNC = sig
-   exception Put
+   exception Full
+   (**
+    * Raised by {IVar.fill} and {MVar.fill} when an attempt is made to
+    * fill a variable that already holds a value.
+    *)
 
-   (** == Handlers == *)
-
    structure Handler : sig
       val runAll : Unit.t Effect.t
+      (**
+       * Attempts to run all scheduled handlers.  This includes handlers
+       * that are scheduled while {runAll} is running.  {runAll} stops
+       * either when all handlers have been executed successfully or when
+       * a handler raises an exception in which case the exception is
+       * propagated to the caller of {runAll}.
+       *)
    end
 
-   (** == Events == *)
-
    structure Event : sig
       type 'a t
 
       (** == Combinators == *)
 
       val on : 'a t * ('a -> 'b) -> 'b t
+      (**
+       * Creates an event that acts like the given event and also executes
+       * the given function on the event value when the created event is
+       * committed.
+       *)
+
       val choose : 'a t List.t -> 'a t
+      (**
+       * Creates an event that chooses, in an unspecified manner, an
+       * occured event from the given list of events to commit.
+       *)
 
       (** == Handling Events == *)
 
       val once : Unit.t t Effect.t
-      val each : Unit.t t Effect.t
+      (**
+       * Commit to the given event once when it occurs.  The handlers
+       * attached to a committed event are executed when {Handler.runAll}
+       * is called.
+       *)
 
       (** == Utilities == *)
 
+      val each : Unit.t t Effect.t
+      (**
+       * Commit to the given event each time it occurs.  {each} can be
+       * implemented as
+       *
+       *> fun each e = when (e, fn () => each e)
+       *)
+
       val when : ('a t * 'a Effect.t) Effect.t
       (** {when (e, h) = once (on (e, h))} *)
 
@@ -40,7 +72,16 @@
       (** {any = once o choose} *)
    end
 
-   (** == Communication Mechanisms == *)
+   (** == Communication Mechanisms ==
+    *
+    * The names of operations have been chosen to communicate the semantics:
+    * - A rendezvous is needed to {give} a value to a handler.
+    * - One can't {fill} a variable twice without emptying it in between.
+    * - Many can {read} a value without taking it.
+    * - One can {send} a value to a handler without a rendezvous.
+    * - Only the handler that {take}s a value sees it.
+    * - Multiple {taker}s may observe the same sequence of values.
+    *)
 
    structure Ch : sig
       type 'a t
@@ -53,14 +94,14 @@
       type 'a t
       val new : 'a t Thunk.t
       val read : 'a t -> 'a Event.t
-      val put : 'a t -> 'a Effect.t
+      val fill : 'a t -> 'a Effect.t
    end
 
    structure MVar : sig
       type 'a t
       val new : 'a t Thunk.t
       val take : 'a t -> 'a Event.t
-      val put : 'a t -> 'a Effect.t
+      val fill : 'a t -> 'a Effect.t
    end
 
    structure Mailbox : sig