aivika-transformers-2.1: Transformers for the Aivika simulation library

CopyrightCopyright (c) 2009-2014, David Sorokin <david.sorokin@gmail.com>
LicenseBSD3
MaintainerDavid Sorokin <david.sorokin@gmail.com>
Stabilityexperimental
Safe HaskellNone
LanguageHaskell2010

Simulation.Aivika.Trans.Queue

Contents

Description

Tested with: GHC 7.8.3

This module defines a queue that can use the specified strategies. So, having only the FCFS, LCFS, SIRO and StaticPriorities strategies, you can build 4 x 4 x 4 = 64 different types of the queue, each of them will have its own behaviour.

Synopsis

Queue Types

type FCFSQueue m a = Queue m FCFS FCFS FCFS a Source

A type synonym for the ordinary FIFO queue also known as the FCFS (First Come - First Serviced) queue.

type LCFSQueue m a = Queue m FCFS LCFS FCFS a Source

A type synonym for the ordinary LIFO queue also known as the LCFS (Last Come - First Serviced) queue.

type SIROQueue m a = Queue m FCFS SIRO FCFS a Source

A type synonym for the SIRO (Serviced in Random Order) queue.

type PriorityQueue m a = Queue m FCFS StaticPriorities FCFS a Source

A type synonym for the queue with static priorities applied when storing the elements in the queue.

data Queue m si sm so a Source

Represents a queue using the specified strategies for enqueueing (input), si, internal storing (in memory), sm, and dequeueing (output), so, where a denotes the type of items stored in the queue. Type m denotes the underlying monad within which the simulation executes.

Creating Queue

newFCFSQueue :: MonadComp m => Int -> Event m (FCFSQueue m a) Source

Create a new FCFS queue with the specified capacity.

newLCFSQueue :: MonadComp m => Int -> Event m (LCFSQueue m a) Source

Create a new LCFS queue with the specified capacity.

newSIROQueue :: MonadComp m => Int -> Event m (SIROQueue m a) Source

Create a new SIRO queue with the specified capacity.

newPriorityQueue :: MonadComp m => Int -> Event m (PriorityQueue m a) Source

Create a new priority queue with the specified capacity.

newQueue Source

Arguments

:: (MonadComp m, QueueStrategy m si, QueueStrategy m sm, QueueStrategy m so) 
=> si

the strategy applied to the enqueueing (input) processes when the queue is full

-> sm

the strategy applied when storing items in the queue

-> so

the strategy applied to the dequeueing (output) processes when the queue is empty

-> Int

the queue capacity

-> Event m (Queue m si sm so a) 

Create a new queue with the specified strategies and capacity.

Queue Properties and Activities

enqueueStrategy :: Queue m si sm so a -> si Source

The strategy applied to the enqueueing (input) processes when the queue is full.

enqueueStoringStrategy :: Queue m si sm so a -> sm Source

The strategy applied when storing (in memory) items in the queue.

dequeueStrategy :: Queue m si sm so a -> so Source

The strategy applied to the dequeueing (output) processes when the queue is empty.

queueNull :: MonadComp m => Queue m si sm so a -> Event m Bool Source

Test whether the queue is empty.

See also queueNullChanged and queueNullChanged_.

queueFull :: MonadComp m => Queue m si sm so a -> Event m Bool Source

Test whether the queue is full.

See also queueFullChanged and queueFullChanged_.

queueMaxCount :: Queue m si sm so a -> Int Source

The queue capacity.

queueCount :: MonadComp m => Queue m si sm so a -> Event m Int Source

Return the current queue size.

See also queueCountStats, queueCountChanged and queueCountChanged_.

queueCountStats :: MonadComp m => Queue m si sm so a -> Event m (TimingStats Int) Source

Return the queue size statistics.

enqueueCount :: MonadComp m => Queue m si sm so a -> Event m Int Source

Return the total number of input items that were enqueued.

See also enqueueCountChanged and enqueueCountChanged_.

enqueueLostCount :: MonadComp m => Queue m si sm so a -> Event m Int Source

Return the number of lost items.

See also enqueueLostCountChanged and enqueueLostCountChanged_.

enqueueStoreCount :: MonadComp m => Queue m si sm so a -> Event m Int Source

Return the total number of input items that were stored.

See also enqueueStoreCountChanged and enqueueStoreCountChanged_.

dequeueCount :: MonadComp m => Queue m si sm so a -> Event m Int Source

Return the total number of requests for dequeueing the items, not taking into account the failed attempts to dequeue immediately without suspension.

See also dequeueCountChanged and dequeueCountChanged_.

dequeueExtractCount :: MonadComp m => Queue m si sm so a -> Event m Int Source

Return the total number of output items that were actually dequeued.

See also dequeueExtractCountChanged and dequeueExtractCountChanged_.

queueLoadFactor :: MonadComp m => Queue m si sm so a -> Event m Double Source

Return the load factor: the queue size divided by its maximum size.

See also queueLoadFactorChanged and queueLoadFactorChanged_.

enqueueRate :: MonadComp m => Queue m si sm so a -> Event m Double Source

Return the rate of the input items that were enqueued: how many items per time.

enqueueStoreRate :: MonadComp m => Queue m si sm so a -> Event m Double Source

Return the rate of the items that were stored: how many items per time.

dequeueRate :: MonadComp m => Queue m si sm so a -> Event m Double Source

Return the rate of the requests for dequeueing the items: how many requests per time. It does not include the failed attempts to dequeue immediately without suspension.

dequeueExtractRate :: MonadComp m => Queue m si sm so a -> Event m Double Source

Return the rate of the output items that were actually dequeued: how many items per time.

queueWaitTime :: MonadComp m => Queue m si sm so a -> Event m (SamplingStats Double) Source

Return the wait time from the time at which the item was stored in the queue to the time at which it was dequeued.

See also queueWaitTimeChanged and queueWaitTimeChanged_.

queueTotalWaitTime :: MonadComp m => Queue m si sm so a -> Event m (SamplingStats Double) Source

Return the total wait time from the time at which the enqueueing operation was initiated to the time at which the item was dequeued.

In some sense, queueTotalWaitTime == queueInputWaitTime + queueWaitTime.

See also queueTotalWaitTimeChanged and queueTotalWaitTimeChanged_.

enqueueWaitTime :: MonadComp m => Queue m si sm so a -> Event m (SamplingStats Double) Source

Return the enqueue wait time from the time at which the enqueueing operation was initiated to the time at which the item was stored in the queue.

See also enqueueWaitTimeChanged and enqueueWaitTimeChanged_.

dequeueWaitTime :: MonadComp m => Queue m si sm so a -> Event m (SamplingStats Double) Source

Return the dequeue wait time from the time at which the item was requested for dequeueing to the time at which it was actually dequeued.

See also dequeueWaitTimeChanged and dequeueWaitTimeChanged_.

queueRate :: MonadComp m => Queue m si sm so a -> Event m Double Source

Return a long-term average queue rate calculated as the average queue size divided by the average wait time.

This value may be less than the actual arrival rate as the queue is finite and new arrivals may be locked while the queue remains full.

See also queueRateChanged and queueRateChanged_.

Dequeuing and Enqueuing

dequeue Source

Arguments

:: (MonadComp m, DequeueStrategy m si, DequeueStrategy m sm, EnqueueStrategy m so) 
=> Queue m si sm so a

the queue

-> Process m a

the dequeued value

Dequeue suspending the process if the queue is empty.

dequeueWithOutputPriority Source

Arguments

:: (MonadComp m, DequeueStrategy m si, DequeueStrategy m sm, PriorityQueueStrategy m so po) 
=> Queue m si sm so a

the queue

-> po

the priority for output

-> Process m a

the dequeued value

Dequeue with the output priority suspending the process if the queue is empty.

tryDequeue Source

Arguments

:: (MonadComp m, DequeueStrategy m si, DequeueStrategy m sm) 
=> Queue m si sm so a

the queue

-> Event m (Maybe a)

the dequeued value of Nothing

Try to dequeue immediately.

enqueue Source

Arguments

:: (MonadComp m, EnqueueStrategy m si, EnqueueStrategy m sm, DequeueStrategy m so) 
=> Queue m si sm so a

the queue

-> a

the item to enqueue

-> Process m () 

Enqueue the item suspending the process if the queue is full.

enqueueWithInputPriority Source

Arguments

:: (MonadComp m, PriorityQueueStrategy m si pi, EnqueueStrategy m sm, DequeueStrategy m so) 
=> Queue m si sm so a

the queue

-> pi

the priority for input

-> a

the item to enqueue

-> Process m () 

Enqueue with the input priority the item suspending the process if the queue is full.

enqueueWithStoringPriority Source

Arguments

:: (MonadComp m, EnqueueStrategy m si, PriorityQueueStrategy m sm pm, DequeueStrategy m so) 
=> Queue m si sm so a

the queue

-> pm

the priority for storing

-> a

the item to enqueue

-> Process m () 

Enqueue with the storing priority the item suspending the process if the queue is full.

enqueueWithInputStoringPriorities Source

Arguments

:: (MonadComp m, PriorityQueueStrategy m si pi, PriorityQueueStrategy m sm pm, DequeueStrategy m so) 
=> Queue m si sm so a

the queue

-> pi

the priority for input

-> pm

the priority for storing

-> a

the item to enqueue

-> Process m () 

Enqueue with the input and storing priorities the item suspending the process if the queue is full.

tryEnqueue Source

Arguments

:: (MonadComp m, EnqueueStrategy m sm, DequeueStrategy m so) 
=> Queue m si sm so a

the queue

-> a

the item which we try to enqueue

-> Event m Bool 

Try to enqueue the item. Return False in the monad if the queue is full.

tryEnqueueWithStoringPriority Source

Arguments

:: (MonadComp m, PriorityQueueStrategy m sm pm, DequeueStrategy m so) 
=> Queue m si sm so a

the queue

-> pm

the priority for storing

-> a

the item which we try to enqueue

-> Event m Bool 

Try to enqueue with the storing priority the item. Return False in the monad if the queue is full.

enqueueOrLost Source

Arguments

:: (MonadComp m, EnqueueStrategy m sm, DequeueStrategy m so) 
=> Queue m si sm so a

the queue

-> a

the item which we try to enqueue

-> Event m Bool 

Try to enqueue the item. If the queue is full then the item will be lost and False will be returned.

enqueueOrLost_ Source

Arguments

:: (MonadComp m, EnqueueStrategy m sm, DequeueStrategy m so) 
=> Queue m si sm so a

the queue

-> a

the item which we try to enqueue

-> Event m () 

Try to enqueue the item. If the queue is full then the item will be lost.

enqueueWithStoringPriorityOrLost Source

Arguments

:: (MonadComp m, PriorityQueueStrategy m sm pm, DequeueStrategy m so) 
=> Queue m si sm so a

the queue

-> pm

the priority for storing

-> a

the item which we try to enqueue

-> Event m Bool 

Try to enqueue with the storing priority the item. If the queue is full then the item will be lost and False will be returned.

enqueueWithStoringPriorityOrLost_ Source

Arguments

:: (MonadComp m, PriorityQueueStrategy m sm pm, DequeueStrategy m so) 
=> Queue m si sm so a

the queue

-> pm

the priority for storing

-> a

the item which we try to enqueue

-> Event m () 

Try to enqueue with the storing priority the item. If the queue is full then the item will be lost.

Awaiting

waitWhileFullQueue :: MonadComp m => Queue m si sm so a -> Process m () Source

Wait while the queue is full.

Summary

queueSummary :: (MonadComp m, Show si, Show sm, Show so) => Queue m si sm so a -> Int -> Event m ShowS Source

Return the summary for the queue with desciption of its properties and activities using the specified indent.

Derived Signals for Properties

queueNullChanged :: MonadComp m => Queue m si sm so a -> Signal m Bool Source

Signal when the queueNull property value has changed.

queueNullChanged_ :: MonadComp m => Queue m si sm so a -> Signal m () Source

Signal when the queueNull property value has changed.

queueFullChanged :: MonadComp m => Queue m si sm so a -> Signal m Bool Source

Signal when the queueFull property value has changed.

queueFullChanged_ :: MonadComp m => Queue m si sm so a -> Signal m () Source

Signal when the queueFull property value has changed.

queueCountChanged :: MonadComp m => Queue m si sm so a -> Signal m Int Source

Signal when the queueCount property value has changed.

queueCountChanged_ :: MonadComp m => Queue m si sm so a -> Signal m () Source

Signal when the queueCount property value has changed.

enqueueCountChanged :: MonadComp m => Queue m si sm so a -> Signal m Int Source

Signal when the enqueueCount property value has changed.

enqueueCountChanged_ :: MonadComp m => Queue m si sm so a -> Signal m () Source

Signal when the enqueueCount property value has changed.

enqueueLostCountChanged :: MonadComp m => Queue m si sm so a -> Signal m Int Source

Signal when the enqueueLostCount property value has changed.

enqueueLostCountChanged_ :: MonadComp m => Queue m si sm so a -> Signal m () Source

Signal when the enqueueLostCount property value has changed.

enqueueStoreCountChanged :: MonadComp m => Queue m si sm so a -> Signal m Int Source

Signal when the enqueueStoreCount property value has changed.

enqueueStoreCountChanged_ :: MonadComp m => Queue m si sm so a -> Signal m () Source

Signal when the enqueueStoreCount property value has changed.

dequeueCountChanged :: MonadComp m => Queue m si sm so a -> Signal m Int Source

Signal when the dequeueCount property value has changed.

dequeueCountChanged_ :: MonadComp m => Queue m si sm so a -> Signal m () Source

Signal when the dequeueCount property value has changed.

dequeueExtractCountChanged :: MonadComp m => Queue m si sm so a -> Signal m Int Source

Signal when the dequeueExtractCount property value has changed.

dequeueExtractCountChanged_ :: MonadComp m => Queue m si sm so a -> Signal m () Source

Signal when the dequeueExtractCount property value has changed.

queueLoadFactorChanged :: MonadComp m => Queue m si sm so a -> Signal m Double Source

Signal when the queueLoadFactor property value has changed.

queueLoadFactorChanged_ :: MonadComp m => Queue m si sm so a -> Signal m () Source

Signal when the queueLoadFactor property value has changed.

queueWaitTimeChanged :: MonadComp m => Queue m si sm so a -> Signal m (SamplingStats Double) Source

Signal when the queueWaitTime property value has changed.

queueWaitTimeChanged_ :: MonadComp m => Queue m si sm so a -> Signal m () Source

Signal when the queueWaitTime property value has changed.

queueTotalWaitTimeChanged :: MonadComp m => Queue m si sm so a -> Signal m (SamplingStats Double) Source

Signal when the queueTotalWaitTime property value has changed.

queueTotalWaitTimeChanged_ :: MonadComp m => Queue m si sm so a -> Signal m () Source

Signal when the queueTotalWaitTime property value has changed.

enqueueWaitTimeChanged :: MonadComp m => Queue m si sm so a -> Signal m (SamplingStats Double) Source

Signal when the enqueueWaitTime property value has changed.

enqueueWaitTimeChanged_ :: MonadComp m => Queue m si sm so a -> Signal m () Source

Signal when the enqueueWaitTime property value has changed.

dequeueWaitTimeChanged :: MonadComp m => Queue m si sm so a -> Signal m (SamplingStats Double) Source

Signal when the dequeueWaitTime property value has changed.

dequeueWaitTimeChanged_ :: MonadComp m => Queue m si sm so a -> Signal m () Source

Signal when the dequeueWaitTime property value has changed.

queueRateChanged :: MonadComp m => Queue m si sm so a -> Signal m Double Source

Signal when the queueRate property value has changed.

queueRateChanged_ :: MonadComp m => Queue m si sm so a -> Signal m () Source

Signal when the queueRate property value has changed.

Basic Signals

enqueueInitiated :: MonadComp m => Queue m si sm so a -> Signal m a Source

Return a signal that notifies when the enqueuing operation is initiated.

enqueueStored :: MonadComp m => Queue m si sm so a -> Signal m a Source

Return a signal that notifies when the enqueuing operation is completed and the item is stored in the internal memory of the queue.

enqueueLost :: MonadComp m => Queue m si sm so a -> Signal m a Source

Return a signal which notifies that the item was lost when attempting to add it to the full queue with help of enqueueOrLost, enqueueOrLost_ or similar functions that imply that the element can be lost. All their names are ending with OrLost or OrLost_.

In other cases the enqueued items are not lost but the corresponded process can suspend until the internal queue storage is freed. Although there is one exception from this rule. If the process trying to enqueue a new element was suspended but then canceled through cancelProcess from the outside then the item will not be added.

dequeueRequested :: MonadComp m => Queue m si sm so a -> Signal m () Source

Return a signal that notifies when the dequeuing operation was requested.

dequeueExtracted :: MonadComp m => Queue m si sm so a -> Signal m a Source

Return a signal that notifies when the item was extracted from the internal storage of the queue and prepared for immediate receiving by the dequeuing process.

Overall Signal

queueChanged_ :: MonadComp m => Queue m si sm so a -> Signal m () Source

Signal whenever any property of the queue changes.

The property must have the corresponded signal. There are also characteristics similar to the properties but that have no signals. As a rule, such characteristics already depend on the simulation time and therefore they may change at any time point.