bcds.phison.sim
Class SimCore<V,E>

java.lang.Object
  bcds.phison.sim.SimCore<V,E>

Direct Known Subclasses:

SimTask

public class SimCore<V,E>
extends java.lang.Object

Implements a minimal core of a discrete-event simulator targeted at path-oriented networks. Essentially, it keeps the (simulated) time, handles the event list, and activates processing modules and callback funcions. The simulated time is an integer (Java's int type).

Complementary information such as topology, link capacities, and random number generator, is kept in a separate structure of type SimGlobals which provides an execution context, mainly for the benefit of processing modules. This context, whose instance is received from the caller, contains both private and shared data. Examples of private data are the topology object and the modules list, while the statistical collector is a shared object. The restriction observed on a a shared resource, is that the resource itself and its fields are never reassigned. This class expects only one non-null object in the context instance, namely, the list of processing modules (field pmreg), of type PmRegistry.

Additionally, a reference to a global "options" structure (of type SimParams) is also kept and passed on to processing modules. This structure is treated as containing read-only (that is, input only) data.

The event list contains future events. It is organized as a priority queue, sorted by simulated time. The event to be removed next is the one closest in time to the previous event (or the first one, when the simulation starts). Every time an event is removed from the event queue, the method processEventOnCurrentTime(EventEntry) is called, with the removed event entry as parameter. The entry consists of the event type and an arbitrary event parameter that varies according to the event type.

Notes:

• This class does not perform any input/ouput by itself.
• Callers must be prepared to handle the LimitReachedException. This does not signal an error but a termination condition.
• Processing modules or callback functions may throw exceptions; none of such exceptions are catched in this class.
• Processing modules can perform arbitrary actions. For example, one may release a connection that was accepted, and set to null its path-related fields so that subsequent modules might interpret that as a connection request rejection.
• Processing modules and callback functions may insert new events; in fact, that is how it is anticipated that events will be added to the simulation.

Author:

Juan Segovia S.

Nested Class Summary

class

SimCore.EventEntry The class EventEntry combines in a single structure an event type and an event parameter.

Constructor Summary

SimCore(SimGlobals<V,E> context, SimParams opt)
Creates a new instance.

Method Summary

void	advanceTime(int new_time) Extracts and processes all events previous to new_time and sets the simulation time to the new time.
void	callProcessingModules(SimEvents ev, ConnectionInfo<V,E> request) Iterates over the processing modules list and calls each module's run method with ev and request as parameters.
SimGlobals<V,E>	ctx() Returns the context associated to this simulator.
void	enqueueCall(int clock, NullaryProc procedure) Inserts an event that will provoke that the procedure's NullaryProc.run() method be called at time clock.
void	enqueueEvent(SimEvents ev, ConnectionInfo<V,E> rq) Enqueues a future event whose time is taken from rq.clock.
ConnRequestErrorCode	getLastBlockingReason() Returns the reason why the last connection request has failed.
long	getSimStartTime() Returns the computer's time in milliseconds recorded when start() was called, or 0 if the simulation has not started.
long	getSimStopTime() Returns the computer's time in milliseconds recorded when stop() was called, or 0 if the simulation has not stopped.
int	getTime() Returns the current (simulated) time.
SimParams	opt() Returns the options associated to this simulator.
void	processEnqueuedEventsPreviousTo(int time_limit) Extracts all the events whose time are less than time_limit.
void	setLastBlockingReason(ConnRequestErrorCode ec) Sets the reason why a given connection is rejected.
void	shutdownProcessingModules() Iterates over the processing modules list and calls each module's shutdown method.
void	start() Starts the simulation by calling advancingTime(0).
void	stop() Stops the simulation.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

SimCore

public SimCore(SimGlobals<V,E> context,
               SimParams opt)

Creates a new instance. The parameters context and opt are saved so that they can be passed on to processing modules. The current time is set to -1, which will be the time seen by processing modules at setup time. The event queue is created empty.

Method Detail

start

public void start()

Starts the simulation by calling advancingTime(0). It may only be called once. The current time, as reported by System.currentTimeMillis(), is recorded. The maximum simulation time is set, based on what is provided in opt.maxtime.

Throws:

java.lang.RuntimeException - if it is called more than once.

stop

public void stop()

Stops the simulation. It first calls processEnqueuedEventsPreviousTo(int) to process all pending events up to the maximum time set for the simulation and then records the simulation stop time that can later be retrived by calling getSimStopTime().

getLastBlockingReason

public ConnRequestErrorCode getLastBlockingReason()

Returns the reason why the last connection request has failed. If it has not, it returns ConnRequestErrorCode.NONE. The internal state is reset to NONE each time an event is removed from the queue.

setLastBlockingReason

public void setLastBlockingReason(ConnRequestErrorCode ec)

Sets the reason why a given connection is rejected. It is assumed that it correponds to the latest connection request.

enqueueEvent

public void enqueueEvent(SimEvents ev,
                         ConnectionInfo<V,E> rq)

Enqueues a future event whose time is taken from rq.clock. This time must not be in the past, that is, its value must be larger than getTime(). The parameter rq is not necessarily a connection information object; instead, it is a convenient container for items that are typically needed when processing an event. Each call to this method should receive a new instance in rq; failing to do so means that information might be overwritten in undesirable ways. Also, the caller is responsible for any subsequent alteration of the object attributes.

When the event is extracted from the event list, it is passed to the processing modules.

If more than one event is inserted with the same time (clock), they are enqueued in the order of their arrival. See enqueueCall(int, NullaryProc) for more details and limitations.

If the requested insertion time is beyond the maximum simulation time, the request is silently ignored.

Throws:

java.lang.IllegalArgumentException - if the event time is in the past.

enqueueCall

public void enqueueCall(int clock,
                        NullaryProc procedure)

Inserts an event that will provoke that the procedure's NullaryProc.run() method be called at time clock. The event is enqueued with type TIMED_EVENT. The value of clock must be larger than getTime().

If more than one event is inserted with the same time (clock), they are enqueued in the order of their arrival. For this purpose, a small time increment D is employed so that the time used in the queue is clock + D. The value of D is incremented with each event enqueued within the same integer clock. One consequence of this approach is that is a limit on the number of events can can be added for a given (integer) time, which currently is 1000000 (one million events). Unless the program is run with assertions active, no error is reported if this limit is surpassed. Surpassing it means that the event time will be wrong, for D would be ≥ 1.

If the requested insertion time is beyond the maximum simulation time, the request is silently ignored.

Throws:

java.lang.IllegalArgumentException - if the event time is in the past.

processEnqueuedEventsPreviousTo

public void processEnqueuedEventsPreviousTo(int time_limit)

Extracts all the events whose time are less than time_limit. The simulation time is updated and the method processEventOnCurrentTime(bcds.phison.sim.SimCore.EventEntry) is called with each extracted event as parameter.

advanceTime

public void advanceTime(int new_time)

Extracts and processes all events previous to new_time and sets the simulation time to the new time. It does nothing if the current time is already new_time.

Throws:

java.lang.RuntimeException - if new_time is smaller than the current time.

LimitReachedException - if the new time is past the maximum allowed time.

ctx

public SimGlobals<V,E> ctx()

Returns the context associated to this simulator. This is the context object received in the constructor.

opt

public SimParams opt()

Returns the options associated to this simulator. This is the opt object received in the constructor.

getTime

public int getTime()

Returns the current (simulated) time. Only valid after stop().

getSimStartTime

public long getSimStartTime()

Returns the computer's time in milliseconds recorded when start() was called, or 0 if the simulation has not started.

getSimStopTime

public long getSimStopTime()

Returns the computer's time in milliseconds recorded when stop() was called, or 0 if the simulation has not stopped.

callProcessingModules

public void callProcessingModules(SimEvents ev,
                                  ConnectionInfo<V,E> request)

Iterates over the processing modules list and calls each module's run method with ev and request as parameters. After all modules have been activated, sets the last blocking reason to ConnRequestErrorCode.NONE.

shutdownProcessingModules

public void shutdownProcessingModules()

Iterates over the processing modules list and calls each module's shutdown method.