/**

\page overview ODEMx - An Overview of the Library.

This page describes the following topics:
<ul>
	<li>\ref structure</li>
	<li>\ref module_base</li>
	<li>\ref module_coroutine</li>
	<li>\ref module_data</li>
	<li>\ref module_protocol</li>
	<li>\ref module_random</li>
	<li>\ref module_statistics</li>
	<li>\ref module_synchronization</li>
	<li>\ref module_test</li>
	<li>\ref module_util</li>
</ul>

\section structure Library Structure
On this page we give an overview of the structure of ODEMx and its primary
simulation components.
ODEMx is divided into the modules \ref base, \ref coroutine, \ref data,
\ref protocol, \ref random, \ref statistics, \ref synch, \b Test,
and \ref util. All modules depend on the modules Data and Utilities.
The following sections describe the concepts implemented by each module.

\section module_base Base Components
The \ref base module contains the core of the simulation building blocks, such
as the simulation context (including a default implementation), base classes
for events and processes, as well as the scheduler with its execution list.
Besides time-discrete processes, ODEMx also provides support for time-continuous
processes on the basis of ordinary differential equations. 

Every simulation with ODEMx requires an implementation of the abstract base
class odemx::base::Simulation. This class provides a context for all the
other model components like processes, events, synchronization classes,
and random number generators. In user-defined simulation classes the method
@c initSimulation must be implemented in order to create and initialize model
components.

For convenience ODEMx also provides the class \c DefaultSimulation with an empty
implementation of @c initSimulation. If the user does not want to define a 
specific simulation class, this default implementation can be used. A reference
to a static object of this class is returned by the free function 
odemx::getDefaultSimulation. However, this requires that all simulation 
components are initialized globally, or from within the @c main function of the
simulation program. ODEMx allows at most one DefaultSimulation-object per program.
If users define their own simulation classes, several simulation contexts can
be used within the same program. This includes simulations inside 
of simulations as well as the parallel (interleaved) execution of simulations.

The base class for all simple simulations events is odemx::base::Event. 
Events typically describe exactly one action that happens during the
simulation run. Each different event type must be implemented as a 
specialization of this class, which usually only requires the definition
of the method \c eventAction. Events may reschedule themselves in order to
model recurring atomic actions in a system.

The class odemx::base::Process serves as base class for all user-defined classes modeling 
discrete processes. Each different type of process in a system model requires 
the specification of a new process class. This class has to define the behavior
(the sequence of actions, synchronizations and idle periods) of its objects as
an implementation of the method @c main.
While process classes are not necessarily associated with specific simulation
classes, every process object must be linked to only one simulation context.
Thus, the constructor of class Process requires a reference to a simulation
object.

The class odemx::base::Continuous is the base class
for continuous processes. Continuous itself is derived from Process, but
provides additional functions to define time-continuous behavior. This kind
of behavior can only be approximated by ODEMx by using a stepwise computation
of state changes, which of course introduces an inherent error rate. 
ODEMx is observing these error values to stay within defined boundaries.
In addition to its implementation of @c main, user-defined time-continuous processes 
must also provide an implementation of the method @c derivatives. In this
method the continuous state changes are coded by setting the change rates
for each state variable. A continuous computation phase is started in @c main
by calling the method @c integrate (which internally uses @c derivatives).
The output of continuous processes can be recorded by an object of type 
odemx::base::ContuTrace, which observes valid state changes and logs the 
computed values of each valid step to a text file. An object of type ContuTrace
is always linked to exactly one object of type Continuous.

\section module_coroutine Coroutine Implementation
The module \ref coroutine provides a platform-independent implementation of
coroutines, which are essentially functions whose execution can be stopped and
resumed at predefined points. This mechanism allows the modeling of 
pseudo-parallel function execution through coroutine switches, thereby
changing the execution context between several different coroutines in a 
sequentialized and deterministic manner. This concept is used for modeling 
ODEMx processes, whose logically parallel execution must be sequentialized, by 
implementing their lifetime and behavior on the basis of coroutines. The 
difference to threads is that coroutines are generally lighter constructs than
threads, and that their execution order is always deterministic and reproducible.   

The class odemx::coroutine::Coroutine is based on the Windows Fiber API. On POSIX
platforms, the functionality of fibers is emulated and implemented on top of the
user context and its related functions, which also allows context switching in
a deterministic manner. This implementation assigns each coroutine its own 
runtime stack, which may consume a lot of memory when simulations contain many 
processes. Therefore, ODEMx also
retains support for the legacy implementation of coroutines, which is based
on copying and replacing only the relevant part of the program's runtime stack
using the functions
@c setjmp and @c longjmp. While this method offers the advantage of a smaller
memory footprint, it has the drawback that processes cannot exchange addresses
of stack-allocated objects because these are simply not available at the 
expected address after a context switch.

\section module_data Data Collection, Storage, and Display 
Module \ref data combines all classes that deal with the computation, collection,
storage, and display of simulation data. Three different concepts
are employed for the collection of simulation data:
@li Logging
@li Report
@li Observation.

@b Logging is provided by the external library CppLog. This concept is employed 
to collect detailed data about state changes in the system model. Logging 
components play one of three roles: source, channel, and sink. 
Channels represent different logging
categories such as trace, debug, or statistics. ODEMx data sources are represented
by the class odemx::data::Producer, which is used as base class for nearly all
ODEMx model elements. Logging sinks are classes that implement a record-consumer
interface. ODEMx provides sinks that write simple text or XML, and it can also
store records in a database. Supported database management systems (DBMS) are 
SQLite, which is embedded in ODEMx, and external DBMSs, which support access 
via ODBC.  

@b Report is a concept that allows the display of accumulated data in tables. 
Report-producing classes implement the interface odemx::data::ReportProducer
to be accessed upon report
generation (either simple text or XML format). Currently, the report concept
is used by statistics-computing classes only. These components collect their
data internally and compute statistical characteristics. All relevant information
such as component name, parameters, reset time, and the computed values is fed
to predefined tables, which are then arranged for display by an implementation
of the base class odemx::data::Report.  

@b Observation is a concept that focuses on the observation of the state 
changes of specific objects.
There are two roles: observer and observable. One observable object may have
multiple observers. Observable classes must be derived from the class template
odemx::data::Observable and additionally provide an @c Observer interface,
which must be implemented by specific observer classes in order to be able
to receive notifications. When certain state changes occur, all registered 
observers of an observable object are notified via calls to the interface.

\section module_protocol Communication Protocol Simulation
The module \ref protocol contains higher level modeling classes for simulating
communication networks. Conceptually, networks are modeled as collections of
interconnected nodes, each of which owns one or more network interfaces for
communicating with connected peers. There is no base class for nodes, as these
can be of arbitrary structure. ODEMx merely requires that one or several 
transmission media manage a network topology of registered network interfaces.
Links between these interfaces are set via the method @c Medium::addLink. It
is also possible to dynamically remove links during a simulation run.
For convenience, simple communication services can also be realized without
specifying a network topology. In this case, each network node only needs 
to use its own Service object (derived from class odemx::protocol::Service),
which implements the network topology as direct connections between all 
registered nodes.

More advanced communication models usually employ a protocol stack (as
provided by the class odemx::protocol::Stack), which is typically comprised 
of several protocol layers, each offering one or several different protocol
services. Access to services is provided through asynchronous interfaces, 
so-called service access points (SAP, modeled by class odemx::protocol::Sap).
The service functionality is always implemented by subclasses of 
odemx::protocol::ServiceProvider. This base class is the foundation for more
specific implementations such as Service, Entity, and Device. Service
providers are the active components in protocol simulations and are therefore
derived from class Process. Their behavior is implemented as waiting period for
input on one of their SAPs. Users must define what is to be done when one
of these input queues contains data.

When using a stack as communication interface of network nodes, it is 
possible to create simulation models that include the physical layer. This 
requires the definition of network interfaces by subclassing 
odemx::protocol::Device, and the use of one or several transmission media
representing cables or radio waves. However, it is also possible to abstract
from the network topology by simply using a Service implementation in the
lowest layer of the stack. Transmission errors can be modeled by implementing
the interface odemx::protocol::ErrorModel. Instances of such classes can then
be registered globally with Service implementations or a Medium object. In the
latter case, it is also possible to assign each link between two nodes its own
error model.

\section module_random Random Number Generation 
The \ref random module is a collection of random number generators (RNGs),
which can be used for statistical simulations. Various discrete and continuous
distributions can be generated by these classes. Examples are Poisson, uniform,
or negative exponential distribution. All RNGs provide a method @c sample, 
which returns the next random number. The parameters for each generator are set
in the constructor.

\section module_statistics Statistics Computation
Module \ref statistics contains classes for statistical analyses. The provided
components are able to compute various statistical characteristics such as
min, max, mean and the standard deviation. There are also classes for creating
histograms and linear correlation analyses.    

\section module_synchronization Process Synchronization
An important part of process simulations is the synchronization of different
processes with certain situations during a simulation. The module 
\ref synchronization is a collection of classes which implement
model components for various synchronization tasks. 

There are two resource-type classes: odemx::sync::Bin and odemx::sync::Res.
Both classes are used to model resource-like synchronization. A process is
blocked if the resource is exhausted. Otherwise it continous its actions by
acquiring resources. Bin and Res use token counters to simulate real resources.
There are also template-implementations of these classes, which use actual
token objects of the type provided as template argument.

Furthermore, the classes odemx::sync::WaitQ and odemx::sync::CondQ provide
queue-like synchronisation components. The WaitQ provides a 
master-slave-synchronisation (MSS). MSS is a synchronisation between two
processes. One of them (the master) takes control of the other (the slave)
after a successful synchronization. The slave is delivered to the master
according to different schemes. It can simply be the first process in the 
waiting queue, but it can also be chosen according to the criteria of a 
selection function, or a weight function provided by the queued master.
An odemx::sync::CondQ is used to wait for an arbitrary condition. A process
provides a function which implements the condition check. The condition is 
checked every time any process object signals a CondQ object. The user is
responsible to call @c signal on a CondQ when the relevant situation changes 
occur in the system model.

Additionally, the synchronization module contains classes for the implementation of
a wait-alert concept. The concept's core component is the interface @c IMemory,
which is intended to store pointers to waiting processes in order to alert them 
at a later point in simulation time. To use the concept, processes call the 
method @c wait with a number of IMemory objects. As soon as one of them becomes 
available and calls @c alert, the process is rescheduled for immediate 
execution. As soon as it continues its execution, the process can check its
alerter and determine the appropriate action. There are several IMemory 
implementations available. The default implementation is the class Memory,
which provides the storage of Process pointers and the means to alert waiting
processes. Other classes are odemx::sync::Timer, which uses a Memory member
to implement its functionality, and the class templates PortHeadT and PortTailT,
which subclass Memory to use its functionality. The latter port construct models
a limited buffer with separate input(tail) and output(head) interfaces.

Finally, the class Wait is an observer example implementation that synchronizes
a process with a set of partner processes. The process that creates the Wait
object is blocked until one or all of its partner processes are terminated.

\section module_test Unit Tests
The test module contains unit tests for all ODEMx components. To allow for
quick and easy test suite creation and execution of all tests, the external
library UnitTest++ is used. It has been integrated in ODEMx and provides
an easy-to-use interface for the creation of new test cases and test suites.
The test module contains its own documentation in odemx/test/Doc.

\section module_util Utilities
This module contains utility classes and functions to simplify the implementation
of other ODEMx components. This involves memory mangement, string conversions,
and sorting. These components are usually not used directly.

*/
