Microsimulation API
Static Public Member Functions | List of all members
ssim::Sim Class Reference

a generic discrete-event sequential simulator More...

#include <ssim.h>

Static Public Member Functions

static ProcessId create_process (Process *) throw ()
 creates a new process More...
 
static int stop_process (ProcessId) throw ()
 stops the execution of a given process More...
 
static void stop_process () throw ()
 stops the execution of the current process More...
 
static void clear () throw ()
 clears out internal data structures More...
 
static void self_signal_event (const Event *e) throw ()
 signal an event to the current process immediately More...
 
static void self_signal_event (const Event *e, Time delay) throw ()
 signal an event to the current process at the given time More...
 
static void signal_event (ProcessId p, const Event *e) throw ()
 signal an event to the given process immediately More...
 
static void signal_event (ProcessId p, const Event *e, Time d) throw ()
 signal an event to the given process at the given time More...
 
static void advance_delay (Time) throw ()
 advance the execution time of the current process. More...
 
static ProcessId this_process () throw ()
 returns the current process More...
 
static Time clock () throw ()
 returns the current virtual time for the current process More...
 
static void run_simulation ()
 starts execution of the simulation More...
 
static void stop_simulation () throw ()
 stops execution of the simulation More...
 
static void set_stop_time (Time t=INIT_TIME) throw ()
 stops the execution of the simulation at the given time More...
 
static void set_error_handler (SimErrorHandler *) throw ()
 registers a handler for simulation errors. More...
 
static void ignore_event (EventPredicate pred) throw ()
 

Detailed Description

a generic discrete-event sequential simulator

This class implements a generic discrete-event sequential simulator. Sim maintains and executes a time-ordered schedule of actions (or discrete events).

Notice that this class is designed to have only static members. It should therefore be seen and used more as a module than a class. In practice, this means that Sim does not define simulation objects, but rather a single, static simulator. This design is based on practical considerations: a simulation object would allow one to handle multiple simulations within the same program at the same time, however that situation is neither common nor desirable. Simulations tend to use a lot of memory and therefore having many of them is probably a bad idea. Also, having multiple simulation objects would require every process object to maintain a reference to the corresponding simulation context (object), so that processes can access the virtual clock of their own simulation, their scheduler, etc. This is both a waste of memory, for the many aditional references, and of CPU time for all the indirect calls to the simulation methods.

Definition at line 326 of file ssim.h.

Member Function Documentation

◆ advance_delay()

void ssim::Sim::advance_delay ( Time  delay)
throw (
)
static

advance the execution time of the current process.

This method can be used to specify the duration of certain actions, or certain steps within the same action. For example:

class SomeProcess : public Process {
//...
virtual void process_event(const Event * e) {
//
// suppose this response is called at (virtual) time X
// ...do something here...
// the above actions have a default duration of 0,
// therefore the following event is scheduled at time X + 5
//
signal_event(e, p, 5);
// ...do something else here...
// advance_delay(10) specifies a duration of 10, therefore
// the following (NULL) event is scheduled at time X + 15;
//
signal_event(NULL, 5);
}
};

Notice that a simulation process correspond to a single logical thread. This means that Process::process_event() is intended to process one event at a time. Because of this chosen semantics, the use of advance_delay(Time) may result in the current process missing some events. Referring to the above example, the overall duration of the execution step defined by SimpleProcess::process_event() is 15 time units. Therefore, a SimpleProcess executing its process_event at time X would miss every event scheduled for it between time X and X + 15.

The application may program a handler for missed events by programming and registering a SimErrorHandler object.

This method must be used within the simulation. The effect of using this method outside the simulation is undefined.

See also
Sim::clock().
SimErrorHandler

Definition at line 255 of file ssim.cc.

◆ clear()

void ssim::Sim::clear ( )
throw (
)
static

clears out internal data structures

Resets the simulator making it available for a completely new simulation. All scheduled actions are deleted together with the associated events. All process identifiers returned by previoius invocations of create_process are invalidated by this operation. Notice however that it is the responsibility of the simulation programmer to delete process objects used in the simulation.

Definition at line 115 of file ssim.cc.

◆ clock()

Time ssim::Sim::clock ( )
throw (
)
static

returns the current virtual time for the current process

Current virtual time.

Example:

void LoopProcess::process_event(const Event * e) {
cout << "Here I am at time:" << Sim::clock() << endl;
cout << "I just scheduled myself again for time: "
<< Sim::clock() + 20 << endl;
}
Returns
current virtual time for the current process.
See also
advance_delay(Time)

Definition at line 264 of file ssim.cc.

◆ create_process()

ProcessId ssim::Sim::create_process ( Process p)
throw (
)
static

creates a new process

Creates a new process with the given Process object. This method schedules the execution of the initialize method for the given object.

This method can be used safely within the simulation as well as outside the simulation.

Returns
the process id of the new simulation process.
See also
Process::initialize()

Definition at line 108 of file ssim.cc.

◆ ignore_event()

void ssim::Sim::ignore_event ( EventPredicate  pred)
throw (
)
static

Definition at line 131 of file ssim.cc.

◆ run_simulation()

void ssim::Sim::run_simulation ( )
static

starts execution of the simulation

Definition at line 148 of file ssim.cc.

◆ self_signal_event() [1/2]

void ssim::Sim::self_signal_event ( const Event e)
throw (
)
static

signal an event to the current process immediately

Signal an event to this process. The response is scheduled immediately (i.e., at the current time).

This method must be used within the simulation. The effect of using this method outside the simulation is undefined.

Parameters
eis the signaled event (possibly NULL)
See also
signal_event(ProcessId, const Event *) and Process::process_event(const Event *).

Definition at line 268 of file ssim.cc.

◆ self_signal_event() [2/2]

void ssim::Sim::self_signal_event ( const Event e,
Time  delay 
)
throw (
)
static

signal an event to the current process at the given time

Signal a delayed event to the current process. The response is scheduled with the given delay.

This method must be used within the simulation. The effect of using this method outside the simulation is undefined.

Parameters
eis the signaled event (possibly NULL)
delayis the delay from the current time
See also
signal_event() and Process::process_event(const Event *).

Definition at line 272 of file ssim.cc.

◆ set_error_handler()

void ssim::Sim::set_error_handler ( SimErrorHandler eh)
throw (
)
static

registers a handler for simulation errors.

An error handler is a callback object that handles all simulation errors.

See also
SimErrorHandler

Definition at line 284 of file ssim.cc.

◆ set_stop_time()

void ssim::Sim::set_stop_time ( Time  t = INIT_TIME)
throw (
)
static

stops the execution of the simulation at the given time

This method sets the absolute (virtual) time at which the simulation will terminate. This method can be used to limit the duration of a simulation even in the presence of schedulable actions. When called with the (default) INIT_TIME, the simulation is set for normal termination, that is, the simulation terminates in the absence of schedulable actions.

See also
stop_simulation()

Definition at line 237 of file ssim.cc.

◆ signal_event() [1/2]

void ssim::Sim::signal_event ( ProcessId  p,
const Event e 
)
throw (
)
static

signal an event to the given process immediately

Signal an event to the given process. The response is scheduled immediately (i.e., at the current time).

This method must be used within the simulation. The effect of using this method outside the simulation is undefined.

Parameters
pis the destination process. This must be a valid process id. That is, a process id returned by * create_process.
Using an invalid process id has undefined effects.
eis the signaled event (possibly NULL)
See also
self_signal_event() and Process::process_event(ProcessId, const Event *).

Definition at line 276 of file ssim.cc.

◆ signal_event() [2/2]

void ssim::Sim::signal_event ( ProcessId  p,
const Event e,
Time  d 
)
throw (
)
static

signal an event to the given process at the given time

Signal a delayed event to the current process. The response is scheduled with the given delay.

This method must be used within the simulation. The effect of using this method outside the simulation is undefined.

Parameters
pis the destination process. This must be a valid process id. That is, a process id returned by * create_process.
Using an invalid process id has undefined effects.
eis the signaled event (possibly NULL)
dis the signal delay starting from the current time
See also
self_signal_event() and Process::process_event(const Event *).

Definition at line 280 of file ssim.cc.

◆ stop_process() [1/2]

void ssim::Sim::stop_process ( )
throw (
)
static

stops the execution of the current process

Definition at line 241 of file ssim.cc.

◆ stop_process() [2/2]

int ssim::Sim::stop_process ( ProcessId  pid)
throw (
)
static

stops the execution of a given process

Definition at line 245 of file ssim.cc.

◆ stop_simulation()

void ssim::Sim::stop_simulation ( )
throw (
)
static

stops execution of the simulation

Definition at line 251 of file ssim.cc.

◆ this_process()

ProcessId ssim::Sim::this_process ( )
throw (
)
static

returns the current process

Process id of the process that is currently scheduled by the simulation. This method can be used by a Process in process_event to figure out its own process id.

Example:

class SimpleProcess : public Process {
void SimpleProcess::process_event(const Event *) {
cout << "My process id is: " << Sim::this_pocess() << endl;
}
};
Returns
process id of the current process, or NULL_PROCESSID if called outside the simulation.

Definition at line 260 of file ssim.cc.


The documentation for this class was generated from the following files:
ssim::Sim::signal_event
static void signal_event(ProcessId p, const Event *e)
signal an event to the given process immediately
Definition: ssim.cc:276
ssim::Sim::advance_delay
static void advance_delay(Time)
advance the execution time of the current process.
Definition: ssim.cc:255
ssim::Sim::self_signal_event
static void self_signal_event(const Event *e)
signal an event to the current process immediately
Definition: ssim.cc:268
ssim::Sim::clock
static Time clock()
returns the current virtual time for the current process
Definition: ssim.cc:264