Fixes #7, fixes #6, fixes #3, fixes #1

Author: jdegoes

MODULES.md

@@ -2,44 +2,29 @@
 
 ## Module Control.Monad.Aff
 
-#### `Async`
-
-``` purescript
-data Async :: !
-```
-
-The effect of being asynchronous.
-
-#### `EffA`
-
-``` purescript
-type EffA e a = Eff (async :: Async | e) a
-```
-
-The `Eff` type for a computation which has asynchronous effects.
-
 #### `Aff`
 
 ``` purescript
-newtype Aff e a
+data Aff :: # ! -> * -> *
 ```
 
 A computation with effects `e`. The computation either errors or 
 produces a value of type `a`.
 
-This is moral equivalent of `ErrorT (ContT Unit (EffA e)) a`.
+This is moral equivalent of `ErrorT (ContT Unit (Eff e)) a`.
 
 #### `PureAff`
 
 ``` purescript
 type PureAff a = forall e. Aff e a
 ```
 
+A pure asynchronous computation, having no effects.
 
 #### `launchAff`
 
 ``` purescript
-launchAff :: forall e a. Aff e a -> EffA e Unit
+launchAff :: forall e a. Aff e a -> Eff e Unit
 ```
 
 Converts the asynchronous computation into a synchronous one. All values 
@@ -48,7 +33,7 @@ and errors are ignored.
 #### `runAff`
 
 ``` purescript
-runAff :: forall e a. (Error -> Eff e Unit) -> (a -> Eff e Unit) -> Aff e a -> EffA e Unit
+runAff :: forall e a. (Error -> Eff e Unit) -> (a -> Eff e Unit) -> Aff e a -> Eff e Unit
 ```
 
 Runs the asynchronous computation. You must supply an error callback and a 
@@ -57,7 +42,7 @@ success callback.
 #### `makeAff`
 
 ``` purescript
-makeAff :: forall e a. ((Error -> Eff e Unit) -> (a -> Eff e Unit) -> EffA e Unit) -> Aff e a
+makeAff :: forall e a. ((Error -> Eff e Unit) -> (a -> Eff e Unit) -> Eff e Unit) -> Aff e a
 ```
 
 Creates an asynchronous effect from a function that accepts error and 
@@ -69,6 +54,14 @@ success callbacks.
 later :: forall e a. Aff e a -> Aff e a
 ```
 
+Runs the asynchronous computation off the current execution context.
+
+#### `later'`
+
+``` purescript
+later' :: forall e a. Number -> Aff e a -> Aff e a
+```
+
 Runs the asynchronous computation later (off the current execution context).
 
 #### `forkAff`

README.md

@@ -35,18 +35,18 @@ deleteBlankLines path =
       saveFile path contents'
 ```
 
-This looks like ordinary, synchronous, imperative code, but actually operates asynchronously without any callbacks (error handling is baked in so you only deal with it when you want to).
+This looks like ordinary, synchronous, imperative code, but actually operates asynchronously without any callbacks. Error handling is baked in so you only deal with it when you want to.
 
-The library contains instances for `Semigroup`, `Monoid`, `Apply`, `Applicative`, `Bind`, `Monad`, `Alt`, `Plus`, `MonadPlus`, `MonadEff`, and `MonadError`. These instances allow you to compose `Aff`-ectful code as easily as `Eff`, as well as interop with existing `Eff` code.
+The library contains instances for `Semigroup`, `Monoid`, `Apply`, `Applicative`, `Bind`, `Monad`, `Alt`, `Plus`, `MonadPlus`, `MonadEff`, and `MonadError`. These instances allow you to compose asynchronous code as easily as `Eff`, as well as interop with existing `Eff` code.
 
 ## Escaping Callback Hell
 
 Hopefully, you're using libraries that already use the `Aff` type, so you don't even have to think about callbacks!
 
-If you're building your own library, or you have to interact with some native code that expects callbacks, then *purescript-aff* provides a `makeAff` function you can use:
+If you're building your own library, or you have to interact with some native code that expects callbacks, then *purescript-aff* provides a `makeAff` function:
 
 ```purescript
-makeAff :: forall e a. ((Error -> Eff e Unit) -> (a -> Eff e Unit) -> EffA e Unit) -> Aff e a
+makeAff :: forall e a. ((Error -> Eff e Unit) -> (a -> Eff e Unit) -> Eff e Unit) -> Aff e a
 ```
 
 This function expects you to provide a handler, which should call a user-supplied error callback or success callback with the result of the asynchronous computation.
@@ -64,7 +64,7 @@ function ajaxGet(callback) { // accepts a callback
     }
   }
 }
-""" :: forall e. (Response -> Eff e Unit) -> Request -> EffA e Unit
+""" :: forall e. (Response -> Eff e Unit) -> Request -> Eff e Unit
 ```
 
 We can wrap this into an asynchronous computation like so:
@@ -142,7 +142,7 @@ These are defined in [purescript-transformers](http://github.com/purescript/pure
 Here's an example of how you can use them:
 
 ```purescript
-do resp <- (Ajax.get "http://foo.com") `catchError` (\e -> pure defaultResponse)
+do resp <- (Ajax.get "http://foo.com") `catchError` (const $ pure defaultResponse)
    if resp.statusCode != 200 then throwError myErr 
    else pure resp.body
 ```
@@ -162,6 +162,15 @@ Because Javascript is single-threaded, forking does not actually cause the
 computation to be run in a separate thread. Forking just allows the subsequent 
 actions to execute without waiting for the forked computation to complete.
 
+If the asynchronous computation supports it, you can "kill" a forked computation
+using the returned canceler:
+
+```purescript
+canceler <- forkAff myAff
+canceled <- canceler
+_        <- liftEff $ if canceled then (trace "Canceled") else (trace "Not Canceled")
+```
+
 ## Queues
 
 The `Control.Monad.Aff.Queue` module contains asynchronous queues. These can 
@@ -175,7 +184,7 @@ do v <- makeQueue
 ```
 
 You can use these constructs as one-sided blocking queues, which suspend (if 
-necessary) on `take operations, or as asynchronous variables (similar to 
+necessary) on `take` operations, or as asynchronous variables (similar to 
 Haskell's `MVar` construct).
 
 ## Parallel Execution

examples/src/Examples.purs

@@ -12,35 +12,13 @@ module Examples where
   import Control.Monad.Eff.Exception(error)
   import Control.Monad.Error.Class(throwError)
 
-  foreign import data Time :: !
-
-  foreign import timeout """
-    function timeout(time) {
-      return function(error) {
-        return function(success) {
-          return function() {
-            setTimeout(function() {
-              try {
-                success({})();
-              } catch (e) {
-                error(e)();
-              }
-            }, time);
-          }
-        }
-      }
-    }
-  """ :: forall e. Number -> Aff (time :: Time | e) Unit
-
   type Test = forall e. Aff (trace :: Trace | e) Unit
   type TestQueue = forall e. Aff (trace :: Trace, queue :: QueueFx | e) Unit
-  type TestQueueTime = forall e. Aff (trace :: Trace, queue :: QueueFx, time :: Time | e) Unit
 
-  test_sequencing :: forall e. Number -> Aff (trace :: Trace, time :: Time | e) Unit
+  test_sequencing :: Number -> Test
   test_sequencing 0 = liftEff $ trace "Done"
   test_sequencing n = do
-    timeout 100
-    liftEff $ trace (show (n / 10) ++ " seconds left")
+    later' 100 (liftEff $ trace (show (n / 10) ++ " seconds left"))
     test_sequencing (n - 1)
 
   test_pure :: Test
@@ -74,22 +52,22 @@ module Examples where
     e <- attempt $ takeQueue v
     liftEff $ either (const $ trace "Success: Killed queue dead") (const $ trace "Failure: Oh noes, queue survived!") e
 
-  test_parRace :: TestQueueTime
+  test_parRace :: TestQueue
   test_parRace = do
-    s <- runPar (Par (timeout 100 *> pure "Success: Early bird got the worm") <|> 
-                 Par (timeout 200 *> pure "Failure: Late bird got the worm"))
+    s <- runPar (Par (later' 100 $ pure "Success: Early bird got the worm") <|> 
+                 Par (later' 200 $ pure "Failure: Late bird got the worm"))
     liftEff $ trace s
 
-  test_parRaceKill1 :: TestQueueTime
+  test_parRaceKill1 :: TestQueue
   test_parRaceKill1 = do
-    s <- runPar (Par (timeout 100 *> throwError (error ("Oh noes!"))) <|> 
-                 Par (timeout 200 *> pure "Success: Early error was ignored in favor of late success"))
+    s <- runPar (Par (later' 100 $ throwError (error ("Oh noes!"))) <|> 
+                 Par (later' 200 $ pure "Success: Early error was ignored in favor of late success"))
     liftEff $ trace s
 
-  test_parRaceKill2 :: TestQueueTime
+  test_parRaceKill2 :: TestQueue
   test_parRaceKill2 = do
-    e <- attempt $ runPar (Par (timeout 100 *> throwError (error ("Oh noes!"))) <|> 
-                           Par (timeout 200 *> throwError (error ("Oh noes!"))))
+    e <- attempt $ runPar (Par (later' 100 $ throwError (error ("Oh noes!"))) <|> 
+                           Par (later' 200 $ throwError (error ("Oh noes!"))))
     liftEff $ either (const $ trace "Success: Killing both kills it dead") (const $ trace "Failure: It's alive!!!") e
 
   main = launchAff $ do
@@ -122,3 +100,5 @@ module Examples where
 
     liftEff $ trace "Testing Par (<|>) - kill two"
     test_parRaceKill2
+
+    liftEff $ trace "Done testing"