Expose NodeId’s constructor and introduce matchSTM

hyperthunk · hyperthunk · commit 484b2cd8d22c · 2014-01-18T22:20:42.000Z
Various clients need to construct NodeId’s, notably all the various
CH backends, so it needs to be public. Also provide a match primitive
that can be used to compose STM actions with the receive family of
functions.
diff --git a/src/Control/Distributed/Process.hs b/src/Control/Distributed/Process.hs
@@ -16,7 +16,7 @@ please see the distributed-process wiki page on github:
 module Control.Distributed.Process
   ( -- * Basic types
     ProcessId
-  , NodeId
+  , NodeId(..)
   , Process
   , SendPortId
   , processNodeId
@@ -51,6 +51,7 @@ module Control.Distributed.Process
   , matchAny
   , matchAnyIf
   , matchChan
+  , matchSTM
   , Message
   , matchMessage
   , matchMessageIf
@@ -209,6 +210,7 @@ import Control.Distributed.Process.Internal.Primitives
   , matchAny
   , matchAnyIf
   , matchChan
+  , matchSTM
   , matchMessage
   , matchMessageIf
   , isEncoded
diff --git a/src/Control/Distributed/Process/Internal/Primitives.hs b/src/Control/Distributed/Process/Internal/Primitives.hs
@@ -28,6 +28,7 @@ module Control.Distributed.Process.Internal.Primitives
   , matchAny
   , matchAnyIf
   , matchChan
+  , matchSTM
   , matchMessage
   , matchMessageIf
   , isEncoded
@@ -360,9 +361,26 @@ receiveTimeout t ms = do
     Nothing   -> return Nothing
     Just proc -> Just <$> proc
 
+-- | Match on a typed channel
 matchChan :: ReceivePort a -> (a -> Process b) -> Match b
 matchChan p fn = Match $ MatchChan (fmap fn (receiveSTM p))
 
+-- | Match on an arbitrary STM action.
+--
+-- This rather unusaul /match primitive/ allows us to compose arbitrary STM
+-- actions with checks against our process' mailbox and/or any typed channel
+-- @ReceivePort@s we may hold.
+--
+-- This allows us to process multiple input streams /along with our mailbox/,
+-- in just the same way that 'matchChan' supports checking both the mailbox
+-- /and/ an arbitrary set of typed channels in one atomic transaction.
+--
+-- Note there are no ordering guarnatees with respect to these disparate input
+-- sources.
+--
+matchSTM :: STM a -> (a -> Process b) -> Match b
+matchSTM stm fn = Match $ MatchChan (fmap fn stm)
+
 -- | Match against any message of the right type
 match :: forall a b. Serializable a => (a -> Process b) -> Match b
 match = matchIf (const True)
