Copyright	Copyright (c) 2009-2014, 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

Description

Tested with: GHC 7.8.3

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

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

MonadTrans Event
MonadCompTrans Event
ParameterLift Event
SimulationLift Event
DynamicsLift Event
EventLift Event
MonadComp m => ResultComputing Event m
Monad m => Monad (Event m)
Functor m => Functor (Event m)
MonadFix m => MonadFix (Event m)
Applicative m => Applicative (Event m)
MonadIO m => MonadIO (Event m)

class EventLift t where Source

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

Methods

liftEvent :: MonadComp m => Event m a -> t m a Source

Lift the specified Event computation into another computation.

Instances

EventLift Event
EventLift Cont
EventLift Process

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
Ord EventProcessing
Show EventProcessing

runEventInStartTime :: MonadComp 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 :: MonadComp 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

class EventQueueing m where Source

A type class of monads that allow enqueueing the events.

Minimal complete definition

newEventQueue, enqueueEvent, runEventWith, eventQueueCount

Associated Types

data EventQueue m :: * Source

It represents the event queue.

Methods

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

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

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

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

The events are processed when calling the runEvent function. So, if you want to insist on their immediate execution then you can apply something like

  liftDynamics $ runEvent IncludingCurrentEvents $ return ()

although this is generally not good idea.

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

EventQueueing IO
TemplateEventQueueing m => EventQueueing m

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

Enqueue the event with an ability to cancel it.

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

Actuate the event handler in the specified time points.

enqueueEventWithIntegTimes :: MonadComp m => Event m () -> Event m () Source

Actuate the event handler in the integration time points.

yieldEvent :: MonadComp m => Event m () -> Event m () Source

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

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 :: (MonadComp m, Exception e) => Event m a -> (e -> Event m a) -> Event m a Source

Exception handling within Event computations.

finallyEvent :: MonadComp m => Event m a -> Event m b -> Event m a Source

A computation with finalization part like the finally function.

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

Like the standard throw function.

Memoization

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

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

memoEventInTime :: MonadComp 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

Monad m => Monoid (DisposableEvent m)