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

Simulation.Aivika.Internal.Event

Contents

Event Monad
Event Queue
Cancelling Event
Error Handling
Memoization
Disposable
Retrying Computation
Debugging

Description

Tested with: GHC 8.0.1

This is an internal implementation module that should never be used directly.

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.

The Dynamics computation is defined in all time points simultaneously, while the Event computation can be described in every time point differently and can change in discrete steps. Therefore, the former is destined for differential and difference equations of System Dynamics, while the latter is destined for discrete event simulation, being its core actually.

Synopsis

newtype Event a = Event (Point -> IO a)
class EventLift m where
data EventProcessing
- = CurrentEvents
- | EarlierEvents
- | CurrentEventsOrFromPast
- | EarlierEventsOrFromPast
invokeEvent :: Point -> Event a -> IO a
runEvent :: Event a -> Dynamics a
runEventWith :: EventProcessing -> Event a -> Dynamics a
runEventInStartTime :: Event a -> Simulation a
runEventInStopTime :: Event a -> Simulation a
enqueueEvent :: Double -> Event () -> Event ()
enqueueEventWithCancellation :: Double -> Event () -> Event EventCancellation
enqueueEventWithStartTime :: Event () -> Event ()
enqueueEventWithStopTime :: Event () -> Event ()
enqueueEventWithTimes :: [Double] -> Event () -> Event ()
enqueueEventWithPoints :: [Point] -> Event () -> Event ()
enqueueEventWithIntegTimes :: Event () -> Event ()
yieldEvent :: Event () -> Event ()
eventQueueCount :: Event Int
data EventCancellation
cancelEvent :: EventCancellation -> Event ()
eventCancelled :: EventCancellation -> Event Bool
eventFinished :: EventCancellation -> Event Bool
catchEvent :: Exception e => Event a -> (e -> Event a) -> Event a
finallyEvent :: Event a -> Event b -> Event a
throwEvent :: Exception e => e -> Event a
memoEvent :: Event a -> Simulation (Event a)
memoEventInTime :: Event a -> Simulation (Event a)
newtype DisposableEvent = DisposableEvent {
- disposeEvent :: Event ()
}
retryEvent :: String -> Event a
traceEvent :: String -> Event a -> Event a

Event Monad

newtype Event a Source #

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

Constructors

Event (Point -> IO a)

Instances

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

class EventLift m where Source #

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

Minimal complete definition

liftEvent

Methods

liftEvent :: Event a -> m a Source #

Lift the specified Event computation to another computation.

Instances

EventLift Event Source #
Instance details Defined in Simulation.Aivika.Internal.Event Methods liftEvent :: Event a -> Event a Source #
EventLift Composite Source #
Instance details Defined in Simulation.Aivika.Composite Methods liftEvent :: Event a -> Composite a Source #
EventLift Cont Source #
Instance details Defined in Simulation.Aivika.Internal.Cont Methods liftEvent :: Event a -> Cont a Source #
EventLift Process Source #
Instance details Defined in Simulation.Aivika.Internal.Process Methods liftEvent :: Event a -> Process 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

Eq EventProcessing Source #
Instance details Defined in Simulation.Aivika.Internal.Event Methods (==) :: EventProcessing -> EventProcessing -> Bool # (/=) :: EventProcessing -> EventProcessing -> Bool #
Ord EventProcessing Source #
Instance details Defined in Simulation.Aivika.Internal.Event 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 #
Show EventProcessing Source #
Instance details Defined in Simulation.Aivika.Internal.Event Methods showsPrec :: Int -> EventProcessing -> ShowS # show :: EventProcessing -> String # showList :: [EventProcessing] -> ShowS #

invokeEvent :: Point -> Event a -> IO a Source #

Invoke the Event computation.

runEvent :: Event a -> Dynamics a Source #

Run the Event computation in the current simulation time within the Dynamics computation involving all pending CurrentEvents in the processing too.

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

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

runEventInStartTime :: Event a -> Simulation a Source #

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

runEventInStopTime :: Event a -> Simulation a Source #

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

Event Queue

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

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

enqueueEventWithCancellation :: Double -> Event () -> Event EventCancellation Source #

Enqueue the event with an ability to cancel it.

enqueueEventWithStartTime :: Event () -> Event () Source #

Actuate the event handler in the start time point.

enqueueEventWithStopTime :: Event () -> Event () Source #

Actuate the event handler in the final time point.

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

Actuate the event handler in the specified time points.

enqueueEventWithPoints :: [Point] -> Event () -> Event () Source #

Actuate the event handler in the specified time points.

enqueueEventWithIntegTimes :: Event () -> Event () Source #

Actuate the event handler in the integration time points.

yieldEvent :: Event () -> Event () Source #

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

eventQueueCount :: Event Int Source #

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

Cancelling Event

data EventCancellation Source #

It allows cancelling the event.

cancelEvent :: EventCancellation -> Event () Source #

Cancel the event.

eventCancelled :: EventCancellation -> Event Bool Source #

Test whether the event was cancelled.

eventFinished :: EventCancellation -> Event Bool Source #

Test whether the event was processed and finished.

Error Handling

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

Exception handling within Event computations.

finallyEvent :: Event a -> Event b -> Event a Source #

A computation with finalization part like the finally function.

throwEvent :: Exception e => e -> Event a Source #

Like the standard throw function.

Memoization

memoEvent :: Event a -> Simulation (Event a) Source #

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

memoEventInTime :: Event a -> Simulation (Event 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 Source #

Defines a computation disposing some entity.

Constructors

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

Instances

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

Retrying Computation

retryEvent :: String -> Event a Source #

Retry the current computation as possible, using the specified argument as a SimulationRetry exception message in case of failure.

Debugging

traceEvent :: String -> Event a -> Event a Source #

Show the debug message with the current simulation time.