Control.Concurrent.PriorityChansConverger.PriorityChansConvergerSTM

Abbreviation for the PriorityChansConverger is PCC.

Based on STM.TChans, extended with capacity control (see Control.Concurrent.STM.TChan.TChanB).

When user reads from the PCC, the choice is made - from which channel to read. System selects a nonempty channel, whose /(CurrentPriority, StartPriority)/ tuple is max. The side effect of the channel selection is it's CurrentPriority decrease by one, if it's value becomes less than one, then the CurrentPriority is set to StartPriority.

PriorityChansConverger ADT and it's administration

decPriority :: (CurrentPriority, StartPriority) -> (CurrentPriority, StartPriority)

Decrease CurrentPriority by one, if it's value becomes less than one, then the CurrentPriority is set to StartPriority.

data Ord k => PriorityChansConvergerSTM k e

Constructors

PriorityChansConvergerSTM

Fields

pccStruct :: Map k (PriorityChan k e)

All channels. Convenient to use for input. Map keys == pcID of elements.

pccEmpties :: TVar (Map (CurrentPriority, StartPriority) [PriorityChan k e])

Empty channels. Map keys == pcPriorityTV of elements.

pccNonEmpties :: TVar (Map (CurrentPriority, StartPriority) [PriorityChan k e])

Nonempty channels. Map keys == pcPriorityTV of elements. Convenient for taking output.

pccConcurrentUISupport :: Maybe ConcurrentUISupport

For testing and debugging purposes.

data PriorityChan k e

PriorityChan = ID + TChanB + TVar (CurrentPriority, StartPriority)

Constructors

PriorityChan

Fields

pcID :: k

pcChanB :: TChanB e

pcPriorityTV :: TVar (CurrentPriority, StartPriority)

pcLoad :: PriorityChan k e -> STM ChanLoad

pcLoad = chanLoad . pcChanB

pcCapacity :: PriorityChan k e -> STM ChanCapacity

pcCapacity = chanCapacity . pcChanB

pcIsEmpty :: PriorityChan k e -> STM Bool

pcIsEmpty = isEmptyTChanB . pcChanB

pcPriority :: PriorityChan k e -> STM (CurrentPriority, StartPriority)

pcPriority = readTVar . pcPriorityTV

pcStartPriority :: PriorityChan k e -> STM StartPriority

pcStartPriority pc = snd liftM pcPriority pc

newPriorityChan :: k -> StartPriority -> ChanCapacity -> STM (PriorityChan k e)

Constructor.

newPriorityChansConvergerSTM_wCUIS :: Ord k => Maybe ConcurrentUISupport -> Map k (StartPriority, ChanCapacity) -> STM (PriorityChansConvergerSTM k e)

PCC constructor with an option to enable utility ConcurrentUISupport (which is useful for debugging).

newPriorityChansConvergerSTM :: Ord k => Map k (StartPriority, ChanCapacity) -> STM (PriorityChansConvergerSTM k e)

PCC constructor. ConcurrentUISupport is off.

newPriorityChansConvergerSTM = newPriorityChansConvergerSTM_wCUIS Nothing

PriorityChansConvergerSTM mutation

isOfStructPCC_STM :: Ord k => Map k (StartPriority, ChanCapacity) -> PriorityChansConvergerSTM k e -> STM (PCC_ContainsGivenSpecification, NothingElseIsInStruct)

Checks:

• If PCC contains all channels, constructable by given specification.
• If PCC contains nothing else, than mentioned in the given specification.

mutatePCC_STM :: Ord k => Map k (StartPriority, ChanCapacity) -> PriorityChansConvergerSTM k e -> STM (PriorityChansConvergerSTM k e)

Updates PCC with given specification. New channels may be added or existing alerted. But no operation for removing channels.

PriorityChansConvergerSTM I/O

writeInPCC_STM :: Ord k => PermitToBlock -> k -> e -> PriorityChansConvergerSTM k e -> STM (Maybe FailureReasonWPCC)

If blocking is on, then blocks, when trying to write to a full channel (where's no free space).

interruptableWriteInPCC_STM :: Ord k => STM InterruptShouldWe -> k -> e -> PriorityChansConvergerSTM k e -> STM (Either () (Maybe FailureReasonWPCC))

Wrapper around (writeInPCC_STM True) - blocking write. Uses interruptableSTM. If returns Left, then transaction ended with interrupting condition.

readFromPCC_STM :: Ord k => PermitToBlock -> PriorityChansConvergerSTM k e -> STM (Maybe (k, e))

If PermitToBlock is True, then never returns Nothing.

interruptableReadFromPCC_STM :: Ord k => STM InterruptShouldWe -> PriorityChansConvergerSTM k e -> STM (Either () (k, e))

Wrapper around (readFromPCC_STM True) - blocking read. Uses interruptableSTM. If returns Left, then transaction ended with interrupting condition.

flushPCC2List_STM :: Ord k => PriorityChansConvergerSTM k e -> STM [(k, e)]

Composition of readFromPCC_STMs. Lazy (doublecheck that).

flushPCC2List_STM' :: Ord k => PriorityChansConvergerSTM k e -> STM [(k, e)]

Strict. Should be a bit faster than flushPCC2List_STM.

fastFlushPCC2List_STM' :: Ord k => PriorityChansConvergerSTM k e -> STM [(k, e)]

Strict. This is a fast flush, it doesn't deal with priorities.

isEmptyPCC_STM :: Ord k => PriorityChansConvergerSTM k e -> STM Bool

freeSpaceInPCCInput_STM :: Ord k => PriorityChansConvergerSTM k e -> k -> STM (Maybe ChanContentAmountMeasure)

Free space in referenced channel = Capacity - Load.

filterOutPCCElements_STM' :: Ord k => PriorityChansConvergerSTM k e -> (e -> TakeElementOutShouldWe) -> STM [(k, e)]

Strict.

Take everything, applu filter, return what's left in the PCC, return what's taken out.

PriorityChansConvergerSTM representation

showPCC_STM :: (Ord k, Show k, Show e) => PriorityChansConvergerSTM k e -> STM String

Used wrapped in (unsafePerformIO . atomically) in the definition of show instance.

showPC_STM :: (Show e, Show k) => PriorityChan k e -> STM String

Used wrapped in (unsafePerformIO . atomically) in the definition of show instance.

Helpers

interruptableSTM :: STM InterruptShouldWe -> STM a -> STM (Maybe a)

For interruptableSTM interrupter subj, when interrupter returns True, the transaction returns Nothing. Else the result of subj is waited and returned wrapped into Just.