Merge pull request #2 from cgay/dev

Minor mods to concurrency

documentation/source/index.rst

@@ -87,6 +87,8 @@ Executors
 
 .. generic-function:: executor-request
 
+   Request that this executor do some work.
+
    :signature: executor-request (executor work) => ()
 
    :parameter executor: An instance of :class:`<executor>`.
@@ -95,6 +97,10 @@ Executors
 .. method:: executor-request
    :specializer: <function>
 
+   A convenience method that converts the given function into a
+   :class:`<work>` object.  The function must not have any required
+   arguments.
+
    :signature: executor-request (executor function) => ()
 
    :parameter executor: An instance of :class:`<executor>`.
@@ -299,7 +305,7 @@ Work
 
    :superclasses: :drm:`<object>`
 
-   :keyword function:
+   :keyword function: A function to perform some work.  The function must not have any required arguments.
 
    :operations:
 
@@ -347,8 +353,30 @@ Work
 
 .. generic-function:: work-wait
 
+   Wait for a work item to reach the given state.  Valid states are
+   :const:`$work-started` and :const:`$work-finished`.
+
+
    :signature: work-wait (work state) => ()
 
    :parameter work: An instance of :class:`<locked-work>`.
-   :parameter state: An instance of :drm:`<symbol>`. One of ``started:`` or ``finished:``.
+   :parameter state: An instance of :class:`<work-state>`. One of
+      :const:`$work-started` or :const:`$work-finished`.
+
+.. constant:: $work-started
+
+   Used with :func:`work-wait` to indicate that you want to wait until
+   work has started executing.
+
+   :type: :class:`<work-state>`
+
+   See also: :const:`$work-finished`
+
+.. constant:: $work-finished
+
+   Used with :func:`work-wait` to indicate that you want to wait until
+   work has finished executing.
+
+   :type: :class:`<work-state>`
 
+   See also: :const:`$work-finished`

executor.dylan

@@ -8,9 +8,12 @@ define abstract class <executor> (<object>)
     init-keyword: name:;
 end class;
 
+// Request that this executor do some work.
 define generic executor-request (executor :: <executor>, work :: <object>)
  => ();
 
+// Convenience method that converts a <function> into a <work> object.
+// The function must not have any required arguments.
 define method executor-request (executor :: <executor>, work :: <function>)
  => ();
   executor-request(executor, make(<work>, function: work));

library.dylan

@@ -43,6 +43,8 @@ define module concurrency
     work-started?,
     work-finished?,
     <locked-work>,
-    work-wait;
+    work-wait,
+    $work-started,
+    $work-finished;
 
 end module;

locked-work.dylan

@@ -15,15 +15,21 @@ define method initialize (work :: <locked-work>, #rest keys, #key, #all-keys)
   work-notification(work) := make(<notification>, lock: work-lock(work));
 end method;
 
-define method work-wait (work :: <locked-work>, state :: <symbol>)
+define constant $work-started = #"started";
+define constant $work-finished = #"finished";
+define constant <work-state> = one-of($work-started, $work-finished);
+
+// Wait for a work item to reach the given state.  Valid states are
+// $work-started and $work-finished.
+define method work-wait (work :: <locked-work>, state :: <work-state>)
   => ();
   with-lock (work-lock(work))
     iterate again ()
       synchronize-side-effects();
       case
-        state == started: & work-started?(work) =>
+        state == $work-started & work-started?(work) =>
           #t;
-        state == finished: & work-finished?(work) =>
+        state == $work-finished & work-finished?(work) =>
           #t;
         otherwise =>
           wait-for(work-notification(work));

work.dylan

@@ -4,7 +4,7 @@ author: Ingo Albrecht <[email protected]>
 copyright: See accompanying file LICENSE
 
 define class <work> (<object>)
-  // function performing the work
+  // function performing the work, must not have any required arguments
   constant slot work-function :: <function>,
     required-init-keyword: function:;