-- Communicating Haskell Processes.
-- Copyright (c) 2008, University of Kent.
-- All rights reserved.
-- 
-- Redistribution and use in source and binary forms, with or without
-- modification, are permitted provided that the following conditions are
-- met:
--
--  * Redistributions of source code must retain the above copyright
--    notice, this list of conditions and the following disclaimer.
--  * Redistributions in binary form must reproduce the above copyright
--    notice, this list of conditions and the following disclaimer in the
--    documentation and/or other materials provided with the distribution.
--  * Neither the name of the University of Kent nor the names of its
--    contributors may be used to endorse or promote products derived from
--    this software without specific prior written permission.
--
-- THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
-- IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
-- THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
-- PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
-- CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
-- EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
-- PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
-- PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
-- LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
-- NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
-- SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

-- | A module with support for things that are enrollable (barriers and broadcast
-- channels).

module Control.Concurrent.CHP.Enroll (Enrolled, Enrollable(..), furtherEnroll,
  enrollPair, enrollList) where

import Control.Concurrent.CHP.Base

class Enrollable b z where
  -- | Enrolls on the given barrier, then executes the given function (passing
  -- it in the enrolled barrier) and when that function body finishes, resigns
  -- from the barrier and returns the result.  If a poison or IO exception is thrown
  -- in the inside block, the barrier will be correctly resigned from, and
  -- the exception rethrown.
  --
  -- Do not attempt to return the
  -- enrolled barrier out of the inner function and use it afterwards.
  enroll :: b z -> (Enrolled b z -> CHP a) -> CHP a

  -- | Resigns from a barrier, then executes the given action, and when the
  -- action finishes, re-enrolls on the barrier and continues.  This function
  -- is designed for use from /inside/ the body of the 'enroll' function, to
  -- temporarily resign from a barrier, do some things, then re-enroll.  Do
  -- not use the enrolled barrier inside the resign block.  However, you may
  -- enroll on the barrier inside this, nesting enroll and resign blocks as
  -- much as you like
  resign :: Enrolled b z -> CHP a -> CHP a

-- | Just like enroll, but starts with an already enrolled item.  During the
-- body, you are enrolled twice -- once from the original enrolled item (which
-- is still valid in the body) and once from the new enrolled item passed to
-- the inner function.  Afterwards, you are enrolled once, on the original item
-- you had.
--
-- This function was added in version 1.3.2.
furtherEnroll :: Enrollable b z => Enrolled b z -> (Enrolled b z -> CHP a) -> CHP a
furtherEnroll (Enrolled x) = enroll x

-- | Like 'enroll' but enrolls on the given pair of barriers
enrollPair :: (Enrollable b p, Enrollable b' p') => (b p, b' p') -> ((Enrolled
  b p, Enrolled b' p') -> CHP a) -> CHP a
enrollPair (b0,b1) f = enroll b0 $ \eb0 -> enroll b1 $ \eb1 -> f (eb0, eb1)

-- | Like 'enroll' but enrolls on the given list of barriers
enrollList :: Enrollable b p => [b p] -> ([Enrolled b p] -> CHP a) -> CHP a
enrollList [] f = f []
enrollList (b:bs) f = enroll b $ \eb -> enrollList bs $ \ebs -> f (eb:ebs)