Copyright	Copyright (c) 2009-2017 David Sorokin <david.sorokin@gmail.com>
License	BSD3
Maintainer	David Sorokin <david.sorokin@gmail.com>
Stability	experimental
Safe Haskell	Safe-Inferred
Language	Haskell2010

Simulation.Aivika.Trans.Event

Contents

Event Monad
Event Queue
Cancelling Event
Error Handling
Memoization
Disposable
Retrying Computation
Synchronizing IO Actions
Debugging

Description

Tested with: GHC 8.0.1

The module defines the Event monad which is very similar to the Dynamics monad but only now the computation is strongly synchronized with the event queue.

Synopsis

data Event m a
class EventLift t m where
- liftEvent :: Event m a -> t m a
data EventProcessing
- = CurrentEvents
- | EarlierEvents
- | CurrentEventsOrFromPast
- | EarlierEventsOrFromPast
runEventInStartTime :: MonadDES m => Event m a -> Simulation m a
runEventInStopTime :: MonadDES m => Event m a -> Simulation m a
type EventPriority = Int
class EventQueueing m where
- data EventQueue m :: *
- newEventQueue :: Specs m -> m (EventQueue m)
- enqueueEventWithPriority :: Double -> EventPriority -> Event m () -> Event m ()
- enqueueEvent :: Double -> Event m () -> Event m ()
- runEvent :: Event m a -> Dynamics m a
- runEventWith :: EventProcessing -> Event m a -> Dynamics m a
- eventQueueCount :: Event m Int
enqueueEventWithCancellation :: MonadDES m => Double -> Event m () -> Event m (EventCancellation m)
enqueueEventWithStartTime :: MonadDES m => Event m () -> Event m ()
enqueueEventWithStopTime :: MonadDES m => Event m () -> Event m ()
enqueueEventWithTimes :: MonadDES m => [Double] -> Event m () -> Event m ()
enqueueEventWithIntegTimes :: MonadDES m => Event m () -> Event m ()
yieldEvent :: MonadDES m => Event m () -> Event m ()
eventPriority :: MonadDES m => Event m EventPriority
data EventCancellation m
cancelEvent :: EventCancellation m -> Event m ()
eventCancelled :: EventCancellation m -> Event m Bool
eventFinished :: EventCancellation m -> Event m Bool
catchEvent :: (MonadException m, Exception e) => Event m a -> (e -> Event m a) -> Event m a
finallyEvent :: MonadException m => Event m a -> Event m b -> Event m a
throwEvent :: (MonadException m, Exception e) => e -> Event m a
memoEvent :: MonadDES m => Event m a -> Simulation m (Event m a)
memoEventInTime :: MonadDES m => Event m a -> Simulation m (Event m a)
newtype DisposableEvent m = DisposableEvent {
- disposeEvent :: Event m ()
}
retryEvent :: MonadException m => String -> Event m a
class (EventQueueing m, MonadIO (Event m)) => EventIOQueueing m where
- enqueueEventIO :: Double -> Event m () -> Event m ()
enqueueEventIOWithStartTime :: (MonadDES m, EventIOQueueing m) => Event m () -> Event m ()
enqueueEventIOWithStopTime :: (MonadDES m, EventIOQueueing m) => Event m () -> Event m ()
enqueueEventIOWithTimes :: (MonadDES m, EventIOQueueing m) => [Double] -> Event m () -> Event m ()
enqueueEventIOWithIntegTimes :: (MonadDES m, EventIOQueueing m) => Event m () -> Event m ()
traceEvent :: MonadDES m => String -> Event m a -> Event m a

Event Monad

data Event m a Source #

A value in the Event monad transformer represents a polymorphic time varying function which is strongly synchronized with the event queue.

Instances

Instances details

MonadTrans Event Source #
Instance details Defined in Simulation.Aivika.Trans.Internal.Event Methods lift :: Monad m => m a -> Event m a #
Monad m => MonadCompTrans Event m Source #
Instance details Defined in Simulation.Aivika.Trans.Internal.Event Methods liftComp :: m a -> Event m a Source #
Monad m => DynamicsLift Event m Source #
Instance details Defined in Simulation.Aivika.Trans.Internal.Event Methods liftDynamics :: Dynamics m a -> Event m a Source #
Monad m => EventLift Event m Source #
Instance details Defined in Simulation.Aivika.Trans.Internal.Event Methods liftEvent :: Event m a -> Event m a Source #
Monad m => ParameterLift Event m Source #
Instance details Defined in Simulation.Aivika.Trans.Internal.Event Methods liftParameter :: Parameter m a -> Event m a Source #
Monad m => SimulationLift Event m Source #
Instance details Defined in Simulation.Aivika.Trans.Internal.Event Methods liftSimulation :: Simulation m a -> Event m a Source #
MonadDES m => ResultComputing Event m Source #
Instance details Defined in Simulation.Aivika.Trans.Results Methods computeResultData :: Event m a -> ResultData a m Source # computeResultSignal :: Event m a -> ResultSignal m Source #
Monad m => MonadFail (Event m) Source #
Instance details Defined in Simulation.Aivika.Trans.Internal.Event Methods fail :: String -> Event m a #
MonadFix m => MonadFix (Event m) Source #
Instance details Defined in Simulation.Aivika.Trans.Internal.Event Methods mfix :: (a -> Event m a) -> Event m a #
MonadIO m => MonadIO (Event m) Source #
Instance details Defined in Simulation.Aivika.Trans.Internal.Event Methods liftIO :: IO a -> Event m a #
Applicative m => Applicative (Event m) Source #
Instance details Defined in Simulation.Aivika.Trans.Internal.Event Methods pure :: a -> Event m a # (<>) :: Event m (a -> b) -> Event m a -> Event m b # liftA2 :: (a -> b -> c) -> Event m a -> Event m b -> Event m c # (>) :: Event m a -> Event m b -> Event m b # (<*) :: Event m a -> Event m b -> Event m a #
Functor m => Functor (Event m) Source #
Instance details Defined in Simulation.Aivika.Trans.Internal.Event Methods fmap :: (a -> b) -> Event m a -> Event m b # (<$) :: a -> Event m b -> Event m a #
Monad m => Monad (Event m) Source #
Instance details Defined in Simulation.Aivika.Trans.Internal.Event Methods (>>=) :: Event m a -> (a -> Event m b) -> Event m b # (>>) :: Event m a -> Event m b -> Event m b # return :: a -> Event m a #
MonadException m => MonadCatch (Event m) Source #
Instance details Defined in Simulation.Aivika.Trans.Internal.Event Methods catch :: (HasCallStack, Exception e) => Event m a -> (e -> Event m a) -> Event m a #
(MonadException m, MonadMask m) => MonadMask (Event m) Source #
Instance details Defined in Simulation.Aivika.Trans.Internal.Event Methods mask :: HasCallStack => ((forall a. Event m a -> Event m a) -> Event m b) -> Event m b # uninterruptibleMask :: HasCallStack => ((forall a. Event m a -> Event m a) -> Event m b) -> Event m b # generalBracket :: HasCallStack => Event m a -> (a -> ExitCase b -> Event m c) -> (a -> Event m b) -> Event m (b, c) #
MonadException m => MonadThrow (Event m) Source #
Instance details Defined in Simulation.Aivika.Trans.Internal.Event Methods throwM :: (HasCallStack, Exception e) => e -> Event m a #
(Monad m, MonadRef m) => Observable (Ref m) (Event m) Source #
Instance details Defined in Simulation.Aivika.Trans.Ref.Base.Lazy Methods readObservable :: Ref m a -> Event m a Source #
(Monad m, MonadRef m) => Observable (Ref m) (Event m) Source #
Instance details Defined in Simulation.Aivika.Trans.Ref.Base.Strict Methods readObservable :: Ref m a -> Event m a Source #
(MonadDES m, ResultItemable (ResultValue a), ResultItemable (ResultValue (SamplingStats a))) => ResultProvider (Event m (SamplingCounter a)) m Source #
Instance details Defined in Simulation.Aivika.Trans.Results Methods resultSource :: ResultName -> ResultDescription -> Event m (SamplingCounter a) -> ResultSource m Source # resultSource3 :: ResultName -> ResultDescription -> ResultDescription -> Event m (SamplingCounter a) -> ResultSource m Source # resultSource' :: ResultName -> [ResultName] -> ResultId -> [ResultId] -> Event m (SamplingCounter a) -> ResultSource m Source #
(MonadDES m, ResultItemable (ResultValue a), ResultItemable (ResultValue (TimingStats a))) => ResultProvider (Event m (TimingCounter a)) m Source #
Instance details Defined in Simulation.Aivika.Trans.Results Methods resultSource :: ResultName -> ResultDescription -> Event m (TimingCounter a) -> ResultSource m Source # resultSource3 :: ResultName -> ResultDescription -> ResultDescription -> Event m (TimingCounter a) -> ResultSource m Source # resultSource' :: ResultName -> [ResultName] -> ResultId -> [ResultId] -> Event m (TimingCounter a) -> ResultSource m Source #
(Ix i, Show i, MonadDES m, ResultItemable (ResultValue [e])) => ResultProvider (Event m (Array i e)) m Source #
Instance details Defined in Simulation.Aivika.Trans.Results Methods resultSource :: ResultName -> ResultDescription -> Event m (Array i e) -> ResultSource m Source # resultSource3 :: ResultName -> ResultDescription -> ResultDescription -> Event m (Array i e) -> ResultSource m Source # resultSource' :: ResultName -> [ResultName] -> ResultId -> [ResultId] -> Event m (Array i e) -> ResultSource m Source #
(MonadDES m, ResultItemable (ResultValue [e])) => ResultProvider (Event m (Vector e)) m Source #
Instance details Defined in Simulation.Aivika.Trans.Results Methods resultSource :: ResultName -> ResultDescription -> Event m (Vector e) -> ResultSource m Source # resultSource3 :: ResultName -> ResultDescription -> ResultDescription -> Event m (Vector e) -> ResultSource m Source # resultSource' :: ResultName -> [ResultName] -> ResultId -> [ResultId] -> Event m (Vector e) -> ResultSource m Source #
(MonadDES m, ResultItemable (ResultValue a)) => ResultProvider (Event m a) m Source #
Instance details Defined in Simulation.Aivika.Trans.Results Methods resultSource :: ResultName -> ResultDescription -> Event m a -> ResultSource m Source # resultSource3 :: ResultName -> ResultDescription -> ResultDescription -> Event m a -> ResultSource m Source # resultSource' :: ResultName -> [ResultName] -> ResultId -> [ResultId] -> Event m a -> ResultSource m Source #

class EventLift t m where Source #

A type class to lift the Event computations into other computations.

Methods

liftEvent :: Event m a -> t m a Source #

Lift the specified Event computation into another computation.

Instances

Instances details

Monad m => EventLift Composite m Source #
Instance details Defined in Simulation.Aivika.Trans.Composite Methods liftEvent :: Event m a -> Composite m a Source #
MonadDES m => EventLift Cont m Source #
Instance details Defined in Simulation.Aivika.Trans.Internal.Cont Methods liftEvent :: Event m a -> Cont m a Source #
MonadDES m => EventLift Process m Source #
Instance details Defined in Simulation.Aivika.Trans.Internal.Process Methods liftEvent :: Event m a -> Process m a Source #
Monad m => EventLift Event m Source #
Instance details Defined in Simulation.Aivika.Trans.Internal.Event Methods liftEvent :: Event m a -> Event m a Source #

data EventProcessing Source #

Defines how the events are processed.

Constructors

CurrentEvents	either process all earlier and then current events, or raise an error if the current simulation time is less than the actual time of the event queue (safe within the `Event` computation as this is protected by the type system)
EarlierEvents	either process all earlier events not affecting the events at the current simulation time, or raise an error if the current simulation time is less than the actual time of the event queue (safe within the `Event` computation as this is protected by the type system)
CurrentEventsOrFromPast	either process all earlier and then current events, or do nothing if the current simulation time is less than the actual time of the event queue (do not use unless the documentation states the opposite)
EarlierEventsOrFromPast	either process all earlier events, or do nothing if the current simulation time is less than the actual time of the event queue (do not use unless the documentation states the opposite)

Instances

Instances details

Show EventProcessing Source #
Instance details Defined in Simulation.Aivika.Trans.Internal.Types Methods showsPrec :: Int -> EventProcessing -> ShowS # show :: EventProcessing -> String # showList :: [EventProcessing] -> ShowS #
Eq EventProcessing Source #
Instance details Defined in Simulation.Aivika.Trans.Internal.Types Methods (==) :: EventProcessing -> EventProcessing -> Bool # (/=) :: EventProcessing -> EventProcessing -> Bool #
Ord EventProcessing Source #
Instance details Defined in Simulation.Aivika.Trans.Internal.Types Methods compare :: EventProcessing -> EventProcessing -> Ordering # (<) :: EventProcessing -> EventProcessing -> Bool # (<=) :: EventProcessing -> EventProcessing -> Bool # (>) :: EventProcessing -> EventProcessing -> Bool # (>=) :: EventProcessing -> EventProcessing -> Bool # max :: EventProcessing -> EventProcessing -> EventProcessing # min :: EventProcessing -> EventProcessing -> EventProcessing #

runEventInStartTime :: MonadDES m => Event m a -> Simulation m a Source #

Run the Event computation in the start time involving all pending CurrentEvents in the processing too.

runEventInStopTime :: MonadDES m => Event m a -> Simulation m a Source #

Run the Event computation in the stop time involving all pending CurrentEvents in the processing too.

Event Queue

type EventPriority = Int Source #

The event priority (greater is higher).

class EventQueueing m where Source #

A type class of monads that allow enqueueing the events.

Minimal complete definition

newEventQueue, enqueueEventWithPriority, runEventWith, eventQueueCount

Associated Types

data EventQueue m :: * Source #

It represents the event queue.

Methods

newEventQueue :: Specs m -> m (EventQueue m) Source #

Create a new event queue by the specified specs with simulation session.

enqueueEventWithPriority :: Double -> EventPriority -> Event m () -> Event m () Source #

Enqueue the event which must be actuated at the specified time given the priority.

enqueueEvent :: Double -> Event m () -> Event m () Source #

Enqueue the event which must be actuated at the specified time.

runEvent :: Event m a -> Dynamics m a Source #

Run the EventT computation in the current simulation time within the DynamicsT computation involving all pending CurrentEvents in the processing too.

runEventWith :: EventProcessing -> Event m a -> Dynamics m a Source #

Run the EventT computation in the current simulation time within the DynamicsT computation specifying what pending events should be involved in the processing.

eventQueueCount :: Event m Int Source #

Return the number of pending events that should be yet actuated.

Instances

Instances details

EventQueueing IO Source #

An implementation of the EventQueueing type class.

Instance details

Defined in Simulation.Aivika.IO.Event

Associated Types

data EventQueue IO Source #

Methods

newEventQueue :: Specs IO -> IO (EventQueue IO) Source #

enqueueEventWithPriority :: Double -> EventPriority -> Event IO () -> Event IO () Source #

enqueueEvent :: Double -> Event IO () -> Event IO () Source #

runEvent :: Event IO a -> Dynamics IO a Source #

runEventWith :: EventProcessing -> Event IO a -> Dynamics IO a Source #

eventQueueCount :: Event IO Int Source #

enqueueEventWithCancellation :: MonadDES m => Double -> Event m () -> Event m (EventCancellation m) Source #

Enqueue the event with an ability to cancel it.

enqueueEventWithStartTime :: MonadDES m => Event m () -> Event m () Source #

Actuate the event handler in the start time point.

enqueueEventWithStopTime :: MonadDES m => Event m () -> Event m () Source #

Actuate the event handler in the final time point.

enqueueEventWithTimes :: MonadDES m => [Double] -> Event m () -> Event m () Source #

Actuate the event handler in the specified time points.

enqueueEventWithIntegTimes :: MonadDES m => Event m () -> Event m () Source #

Actuate the event handler in the integration time points.

yieldEvent :: MonadDES m => Event m () -> Event m () Source #

Enqueue the event which must be actuated with the current modeling time but later.

eventPriority :: MonadDES m => Event m EventPriority Source #

Return the current event priority.

Cancelling Event

data EventCancellation m Source #

It allows cancelling the event.

cancelEvent :: EventCancellation m -> Event m () Source #

Cancel the event.

eventCancelled :: EventCancellation m -> Event m Bool Source #

Test whether the event was cancelled.

eventFinished :: EventCancellation m -> Event m Bool Source #

Test whether the event was processed and finished.

Error Handling

catchEvent :: (MonadException m, Exception e) => Event m a -> (e -> Event m a) -> Event m a Source #

Exception handling within Event computations.

finallyEvent :: MonadException m => Event m a -> Event m b -> Event m a Source #

A computation with finalization part like the finally function.

throwEvent :: (MonadException m, Exception e) => e -> Event m a Source #

Like the standard throw function.

Memoization

memoEvent :: MonadDES m => Event m a -> Simulation m (Event m a) Source #

Memoize the Event computation, always returning the same value within a simulation run.

memoEventInTime :: MonadDES m => Event m a -> Simulation m (Event m a) Source #

Memoize the Event computation, always returning the same value in the same modeling time. After the time changes, the value is recalculated by demand.

It is possible to implement this function efficiently, for the Event computation is always synchronized with the event queue which time flows in one direction only. This synchronization is a key difference between the Event and Dynamics computations.

Disposable

newtype DisposableEvent m Source #

Defines a computation disposing some entity.

Constructors

DisposableEvent
Fields disposeEvent :: Event m () Dispose something within the `Event` computation.

Instances

Instances details

Monad m => Monoid (DisposableEvent m) Source #
Instance details Defined in Simulation.Aivika.Trans.Internal.Event Methods mempty :: DisposableEvent m # mappend :: DisposableEvent m -> DisposableEvent m -> DisposableEvent m # mconcat :: [DisposableEvent m] -> DisposableEvent m #
Monad m => Semigroup (DisposableEvent m) Source #
Instance details Defined in Simulation.Aivika.Trans.Internal.Event Methods (<>) :: DisposableEvent m -> DisposableEvent m -> DisposableEvent m # sconcat :: NonEmpty (DisposableEvent m) -> DisposableEvent m # stimes :: Integral b => b -> DisposableEvent m -> DisposableEvent m #

Retrying Computation

retryEvent :: MonadException m => String -> Event m a Source #

Retry the current computation as possible, using the specified argument as a SimulationRetry exception message in case of failure. It makes sense for parallel distributed simulation, when we have to make a rollback, awaiting for incoming messages.

Synchronizing IO Actions

class (EventQueueing m, MonadIO (Event m)) => EventIOQueueing m where Source #

A type class of monads that allows synchronizing the global modeling time before calling the event handler so that it is rather safe to perform IO actions within such a handler. It is mainly destined for parallel distributed simulation, but it should be supported in other cases too.

Methods

enqueueEventIO :: Double -> Event m () -> Event m () Source #

Like enqueueEvent but synchronizes the global modeling time before calling the specified event handler.

Instances

Instances details

EventIOQueueing IO Source #	An implementation of the `EventIOQueueing` type class.
Instance details Defined in Simulation.Aivika.IO.Event Methods enqueueEventIO :: Double -> Event IO () -> Event IO () Source #

enqueueEventIOWithStartTime :: (MonadDES m, EventIOQueueing m) => Event m () -> Event m () Source #

Like enqueueEventWithStartTime but synchronizes the global modeling time before calling the specified event handler.

enqueueEventIOWithStopTime :: (MonadDES m, EventIOQueueing m) => Event m () -> Event m () Source #

Like enqueueEventWithStopTime but synchronizes the global modeling time before calling the specified event handler.

enqueueEventIOWithTimes :: (MonadDES m, EventIOQueueing m) => [Double] -> Event m () -> Event m () Source #

Like enqueueEventWithTimes but synchronizes the global modeling time before calling the specified event handler.

enqueueEventIOWithIntegTimes :: (MonadDES m, EventIOQueueing m) => Event m () -> Event m () Source #

Like enqueueEventWithIntegTimes but synchronizes the global modeling time before calling the specified event handler.

Debugging

traceEvent :: MonadDES m => String -> Event m a -> Event m a Source #

Show the debug message with the current simulation time.