@@ -28,6 +28,7 @@ module Control.Distributed.Process.Internal.Primitives
2828 , matchAny
2929 , matchAnyIf
3030 , matchChan
31+ , matchSTM
3132 , matchMessage
3233 , matchMessageIf
3334 , isEncoded
@@ -360,9 +361,26 @@ receiveTimeout t ms = do
360361 Nothing -> return Nothing
361362 Just proc -> Just <$> proc
362363
364+-- | Match on a typed channel
363365matchChan :: ReceivePort a -> (a -> Process b) -> Match b
364366matchChan p fn = Match $ MatchChan (fmap fn (receiveSTM p))
365367
368+-- | Match on an arbitrary STM action.
369+--
370+-- This rather unusaul /match primitive/ allows us to compose arbitrary STM
371+-- actions with checks against our process' mailbox and/or any typed channel
372+-- @ReceivePort@s we may hold.
373+--
374+-- This allows us to process multiple input streams /along with our mailbox/,
375+-- in just the same way that 'matchChan' supports checking both the mailbox
376+-- /and/ an arbitrary set of typed channels in one atomic transaction.
377+--
378+-- Note there are no ordering guarnatees with respect to these disparate input
379+-- sources.
380+--
381+matchSTM :: STM a -> (a -> Process b) -> Match b
382+matchSTM stm fn = Match $ MatchChan (fmap fn stm)
383+
366384-- | Match against any message of the right type
367385match :: forall a b. Serializable a => (a -> Process b) -> Match b
368386match = matchIf (const True)