SSim C++ API documentation (v. 1.5.0)
Main Page | Namespace List | Class Hierarchy | Class List | File List | Namespace Members | Class Members | Examples

ssim::Sim Class Reference

a generic discrete-event sequential simulator More...

#include <ssim.h>

List of all members.

Static Public Member Functions

ProcessId create_process (Process *)
 creates a new process

int stop_process (ProcessId)
 stops the execution of a given process

void stop_process ()
 stops the execution of the current process

void clear ()
 clears out internal data structures

void self_signal_event (const Event *) throw ()
 signal an event to the current process immediately

void self_signal_event (const Event *, Time delay) throw ()
 signal an event to the current process at the given time

int signal_event (ProcessId, const Event *) throw ()
 signal an event to the given process immediately

int signal_event (ProcessId, const Event *, Time) throw ()
 signal an event to the given process at the given time

void advance_delay (Time)
 advance the execution time of the current process.

ProcessId this_process ()
 returns the current process

Time clock ()
 returns the current virtual time for the current process

void run_simulation ()
 starts execution of the simulation

void stop_simulation ()
 stops execution of the simulation

void set_stop_time (Time t=INIT_TIME)
 stops the execution of the simulation at the given time

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).

Member Function Documentation

void ssim::Sim::advance_delay (  Time   )  [inline, 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);
     
          advance_delay(10);

          // ...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() and TProcess::main() are 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 would miss every event scheduled for it between time X and X + 15. A semantically identical situation would occur for a sequential process. For example:

  class SomeTProcess : public TProcess {
      //...
      virtual void main() {
          // ...
          const Event * e;
          e = wait_for_event();

          // now suppose wait_for_event() returns a signal at time X
          // and we do something with this signal...
          // and this "something" costs us 20 time units
          advance_delay(20);

          // now, our virtual clock is X + 20, so we have missed 
          // all the signals between X and X + 20
          e = wait_for_signal();
      }
  };

In this example, the process misses all the events signaled within 20 time units after the first event. This is because the process is busy working on the first event.

See also:
Sim::clock().

void ssim::Sim::clear (   )  [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.

Time ssim::Sim::clock (   )  [inline, 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;
      self_signal_event(NULL, 20)
      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)
Examples:
tp.cc.

ProcessId ssim::Sim::create_process (  Process *   )  [static]
 

creates a new process

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

Returns:
the process id of the new simulation process.
See also:
Process::init()
Examples:
tp.cc.

void ssim::Sim::self_signal_event (  const Event *  ,
Time  delay
)  throw () [inline, 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.

See also:
signal_event() and Process::process_event(const Event *).

void ssim::Sim::self_signal_event (  const Event *   )  throw () [inline, 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).

See also:
signal_event(ProcessId, const Event *) and Process::process_event(const Event *).
Examples:
tp.cc.

void ssim::Sim::set_stop_time (  Time  t = INIT_TIME  )  [inline, 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()

int ssim::Sim::signal_event (  ProcessId  ,
const Event *  ,
Time 
)  throw () [inline, static]
 

signal an event to the given process at the given time

Signal an event to the given process. The response is scheduled immediately.

Returns:
0 if the destination process is still active; -1 if the destination process has terminated.
See also:
self_signal_event() and Process::process_event(const Event *).

int ssim::Sim::signal_event (  ProcessId  ,
const Event * 
)  throw () [inline, 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).

Returns:
0 if the destination process is still active; -1 if the destination process has terminated.
See also:
self_signal_event() and Process::process_event(ProcessId, const Event *).
Examples:
tp.cc.

ProcessId ssim::Sim::this_process (   )  [inline, 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 or by a TProcess in main 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 a simulation.

The documentation for this class was generated from the following file:
Copyright © 2002-2004 University of Colorado.
Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts and no Back-Cover Texts. A copy of the license is included in the section entitled "GNU Free Documentation License". This documentation is authored and maintained by Antonio Carzaniga