more tests, rename Var to Queue

Author: jdegoes

MODULES.md

@@ -69,7 +69,7 @@ success callbacks.
 later :: forall e a. Aff e a -> Aff e a
 ```
 
-Runs the asynchronous computation later.
+Runs the asynchronous computation later (off the current execution context).
 
 #### `forkAff`
 
@@ -222,14 +222,14 @@ instance monadAffAff :: MonadAff e (Aff e)
 
 ``` purescript
 newtype Par e a
-  = Par (AffVar e a)
+  = Par (AffQueue e a)
 ```
 
 
 #### `runPar`
 
 ``` purescript
-runPar :: forall e a. Par e a -> AffVar e a
+runPar :: forall e a. Par e a -> AffQueue e a
 ```
 
 Extracts the `Aff` from the `Par`.
@@ -292,91 +292,90 @@ instance alternativePar :: Alternative (Par e)
 
 
 
-## Module Control.Monad.Aff.Unsafe
+## Module Control.Monad.Aff.Queue
 
-#### `unsafeTrace`
+#### `QueueFx`
 
 ``` purescript
-unsafeTrace :: forall e a. a -> Aff e Unit
+data QueueFx :: !
 ```
 
 
-#### `unsafeInterleaveAff`
+#### `Queue`
 
 ``` purescript
-unsafeInterleaveAff :: forall e1 e2 a. Aff e1 a -> Aff e2 a
+data Queue :: * -> *
 ```
 
 
-
-## Module Control.Monad.Aff.Var
-
-#### `VarFx`
+#### `AffQueue`
 
 ``` purescript
-data VarFx :: !
+type AffQueue e a = Aff (queue :: QueueFx | e) a
 ```
 
 
-#### `Var`
+#### `makeQueue`
 
 ``` purescript
-data Var :: * -> *
+makeQueue :: forall e a. AffQueue e (Queue a)
 ```
 
+Makes a new asynchronous queue.
 
-#### `AffVar`
+#### `makeQueue'`
 
 ``` purescript
-type AffVar e a = Aff (var :: VarFx | e) a
+makeQueue' :: forall e a. a -> AffQueue e (Queue a)
 ```
 
+Makes a queue and sets it to some value.
 
-#### `makeVar`
+#### `takeQueue`
 
 ``` purescript
-makeVar :: forall e a. AffVar e (Var a)
+takeQueue :: forall e a. Queue a -> AffQueue e a
 ```
 
-Makes a new asynchronous variable.
+Takes the next value from the asynchronous queue.
 
-#### `makeVar'`
+#### `putQueue`
 
 ``` purescript
-makeVar' :: forall e a. a -> AffVar e (Var a)
+putQueue :: forall e a. Queue a -> a -> AffQueue e Unit
 ```
 
-Makes a variable and sets it to some value.
+Puts a new value into the asynchronous queue. If the queue has
+been killed, this will result in an error.
 
-#### `takeVar`
+#### `modifyQueue`
 
 ``` purescript
-takeVar :: forall e a. Var a -> AffVar e a
+modifyQueue :: forall e a. (a -> a) -> Queue a -> AffQueue e Unit
 ```
 
-Takes the next value from the asynchronous variable.
+Modifies the value at the head of the queue (will suspend until one is available).
 
-#### `putVar`
+#### `killQueue`
 
 ``` purescript
-putVar :: forall e a. Var a -> a -> AffVar e Unit
+killQueue :: forall e a. Queue a -> Error -> AffQueue e Unit
 ```
 
-Puts a new value into the asynchronous variable. If the variable has
-been killed, this will result in an error.
+Kills an asynchronous queue.
 
-#### `modifyVar`
+
+## Module Control.Monad.Aff.Unsafe
+
+#### `unsafeTrace`
 
 ``` purescript
-modifyVar :: forall e a. (a -> a) -> Var a -> AffVar e Unit
+unsafeTrace :: forall e a. a -> Aff e Unit
 ```
 
-Modifies an asynchronous variable.
 
-#### `killVar`
+#### `unsafeInterleaveAff`
 
 ``` purescript
-killVar :: forall e a. Var a -> Error -> AffVar e Unit
-```
-
-Kills an asynchronous variable.
+unsafeInterleaveAff :: forall e1 e2 a. Aff e1 a -> Aff e2 a
+```

README.md

@@ -162,18 +162,21 @@ 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.
 
-## Variables
+## Queues
 
-The `Control.Monad.Aff.Var` module contains asynchronous variables. These can 
+The `Control.Monad.Aff.Queue` module contains asynchronous queues. These can 
 be used as low-level building blocks for asynchronous programs.
 
 ```purescript
-do v <- makeVar
-   forkAff (later $ putVar v 1.0)
-   a <- takeVar v 
+do v <- makeQueue
+   forkAff (later $ putQueue v 1.0)
+   a <- takeQueue v 
    liftEff $ trace ("Succeeded with " ++ show a)
 ```
 
+You can use these as queues which suspend (if necessary) on take operations, or 
+as asynchronous variables (similar to Haskell's `MVar` construct).
+
 ## Parallel Execution
 
 If you only need the power of `Applicative`, then instead of using the monadic `Aff`, you can use the `Par` newtype wrapper defined in `Control.Monad.Aff.Par`.

examples/src/Examples.purs

@@ -4,7 +4,7 @@ module Examples where
   import Data.Either(either)
 
   import Control.Monad.Aff
-  import Control.Monad.Aff.Var
+  import Control.Monad.Aff.Queue
   import Control.Monad.Aff.Par
   import Control.Apply((*>))
   import Control.Alt(Alt, (<|>))
@@ -33,14 +33,14 @@ module Examples where
   """ :: forall e. Number -> Aff (time :: Time | e) Unit
 
   type Test = forall e. Aff (trace :: Trace | e) Unit
-  type TestVar = forall e. Aff (trace :: Trace, var :: VarFx | e) Unit
-  type TestVarTime = forall e. Aff (trace :: Trace, var :: VarFx, time :: Time | 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 0 = liftEff $ trace "Done"
   test_sequencing n = do
-    timeout 1000
-    liftEff $ trace (show n ++ " seconds left")
+    timeout 100
+    liftEff $ trace (show (n / 10) ++ " seconds left")
     test_sequencing (n - 1)
 
   test_pure :: Test
@@ -60,26 +60,38 @@ module Examples where
     apathize $ throwError (error "Oh noes!")
     liftEff $ trace "Success: Exceptions don't stop the apathetic"
 
-  test_putTakeVar :: TestVar
-  test_putTakeVar = do
-    v <- makeVar
-    forkAff (later $ putVar v 1.0)
-    a <- takeVar v 
+  test_putTakeQueue :: TestQueue
+  test_putTakeQueue = do
+    v <- makeQueue
+    forkAff (later $ putQueue v 1.0)
+    a <- takeQueue v 
     liftEff $ trace ("Success: Value " ++ show a)
 
-  test_killVar :: TestVar
-  test_killVar = do
-    v <- makeVar
-    killVar v (error "DOA")
-    e <- attempt $ takeVar v
-    liftEff $ either (const $ trace "Success: Killed var dead") (const $ trace "Failure: Oh noes, Var survived!") e
+  test_killQueue :: TestQueue
+  test_killQueue = do
+    v <- makeQueue
+    killQueue v (error "DOA")
+    e <- attempt $ takeQueue v
+    liftEff $ either (const $ trace "Success: Killed queue dead") (const $ trace "Failure: Oh noes, queue survived!") e
 
-  test_parRace :: TestVarTime
+  test_parRace :: TestQueueTime
   test_parRace = do
-    s <- runPar $ (Par (timeout  100 *> pure "Success: Early bird got the worm") <|> 
-                   Par (timeout 1000 *> pure "Failure: Late bird got the worm"))
+    s <- runPar (Par (timeout 100 *> pure "Success: Early bird got the worm") <|> 
+                 Par (timeout 200 *> pure "Failure: Late bird got the worm"))
     liftEff $ trace s
 
+  test_parRaceKill1 :: TestQueueTime
+  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"))
+    liftEff $ trace s
+
+  test_parRaceKill2 :: TestQueueTime
+  test_parRaceKill2 = do
+    e <- attempt $ runPar (Par (timeout 100 *> throwError (error ("Oh noes!"))) <|> 
+                           Par (timeout 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
     liftEff $ trace "Testing sequencing"
     test_sequencing 3
@@ -96,11 +108,17 @@ module Examples where
     liftEff $ trace "Testing apathize"
     test_apathize
 
-    liftEff $ trace "Testing Var - putVar, takeVar"
-    test_putTakeVar
+    liftEff $ trace "Testing Queue - putQueue, takeQueue"
+    test_putTakeQueue
 
-    liftEff $ trace "Testing killVar"
-    test_killVar
+    liftEff $ trace "Testing killQueue"
+    test_killQueue
 
     liftEff $ trace "Testing Par (<|>)"
     test_parRace
+
+    liftEff $ trace "Testing Par (<|>) - kill one"
+    test_parRaceKill1
+
+    liftEff $ trace "Testing Par (<|>) - kill two"
+    test_parRaceKill2