HASE Userguide

Hase++ manual

Hase++ is a library for C++ which provides discrete event simulations with entities running in separate threads. It is part of the HASE simulation environment, but may be used by itself. The interface is based on that of Jade's SIM++.

To define the behaviour of an entity, Hase++ must define a class inheriting from class sim_entity. It is allowed to use any C++-compatible code when describing this behaviour. The user can obviouly use any public method defined by the class sim_entity. Additionally, the user can use the services provided by the simulation system. Finally, to simplify the syntax, some macro instructions are provided.
Each entity lives as an independent thread, scheduled by the scheduler. All entities in a single project are executed in the same system process.

Hase++ uses predicates to filter and select incoming events and a number of pre-defined predicates are provided.

Class sim_entity

body

virtual void body() = 0

This method is virtual and abstract, it has to be overriden by sub-entities. This method must contain the entity's behaviour.

sim_get_next

void sim_get_next(sim_event & event)

This method returns as soon as the entity receives an event. If this event is already available in the deferred queue, this method returns immediately, otherwise the entity holds and has to be re-scheduled by the scheduler before resuming.

Parameters:

event is filled with the content of the incoming event (tag and value if relevant).

sim_get_next

void sim_get_next(sim_predicate & p, sim_event & event)

This method returns as soon as the entity receives an event that matches the predicate. If this event is already available in the deferred queue, this method returns immediately, otherwise the entity holds and has to be re-scheduled by the scheduler before resuming.

Parameters:

p The predicate that expresses the condition the event has to match before resuming the entity.

event is filled with the content of the incoming event (tag and value if relevant).

sim_get_next_before

bool sim_get_next_before(sim_predicate & pred, sim_event & event, sim_time timeout)

This method returns as soon as the entity receives an event that matches pred or the timeout has elapsed. If this event is already available in the deferred queue, this method returns immediately, otherwise the entity holds and has to be re-scheduled by the scheduler before resuming.

Parameters:

pred the predicate, which an event must match before timeout for the method to return true.

event is filled with the content of the incoming event (tag and value if relevant) iif the timeout did not elapse.

timeout relative simulation time before which the method returns even if no event arrived.

Returns:

false if the timeout elapsed, true otherwise

sim_get_next_before

bool sim_get_next_before(sim_event & event, sim_time timeout)

This method returns as soon as the entity receives an event or the timeout has elapsed. If this event is already available in the deferred queue, this method returns immediately, otherwise the entity holds and has to be re-scheduled by the scheduler before resuming.
This is equivalent to return sim_get_next_before(SIM_ANY, event, timeout);

Parameters:

event is filled with the content of the incoming event (tag and value if relevant) iif the timeout did not elapse.

timeout relative simulation time before which the method returns even if no event arrived.

Returns:

false if the timeout elapsed, true otherwise

sim_hold

void sim_hold(sim_time delay)

This method holds the entity for a given simulation time. When this simulation time is elapsed, the entity has to be re-scheduled by the scheduler in order to resume. In particular, sim_hold(0) is not equivalent to nothing when other entities are not holding.

Parameters:

delay This is a simulation time.

sim_schedule

void sim_schedule(sim_port & port, sim_time delay, int ev_type, void *ev_buf=0, int ev_len=0)

This method schedules an event on a port.

Parameters:

port: port which is used to send the event.

delay: delay after which the event is sent. This is delay must be expressed in simulation time. 0 means in the next micro-cycle.

ev_type: tag used to make a distinction between events.

ev_buf: a pointer to the value which has to be sent. If not specified, the event is just a tag and has no value.

ev_len: the length of the buffer containing the value. If not specified, the event is considered to have no value.

sim_reply

void sim_reply(sim_event & event, sim_time delay, int ev_type, void *ev_buf=0, int ev_len=0)

This method schedules an outgoing event on the same port where the incoming event arrived. The event will go back to the sender of the event. This mechanism can be used to acknowledge request without knowing the request sender.

Parameters:

event: event that has to be ackowledged

delay: delay after which the acknowledgment is sent. This is delay must be expressed in simulation time. 0 means in the next micro-cycle.

ev_type: tag used to make a distinction between events.

ev_buf: a pointer to the value which has to be sent. If not specified, the acknowledgment is just a tag and has no value.

ev_len: the length of the buffer containing the value. If not specified, the acknowledgment is considered to have no value.

sim_select

void sim_select(sim_predicate & p, sim_event & event)

This method selects the next event in the deferred queue that matches the predicate requirements. This method returns immediately whether there is an event available or not.

Parameters:

p The predicate that the event has to match before resuming the entity.

event is filled with the content of the incoming event (tag and value if relevant).

sim_trace

void sim_trace(int level, char *msg)

This method has to be used when the user wants to report some specific events to the tracefile which is produced at the end of the simulation.

Parameters:

level The level of importance for the message. The sim_system::set_trc_level(int) method allows the user to choose which messages are actually to be dumped into the trace file.

msg msg to be printed into the trace file.

sim_waiting

int sim_waiting(sim_predicate & p)

This method computes the number of events in the deferred queue, for which destination is this entity, that match the predicate requirements.

Parameters:

p The predicate which has to be matched.

Returns:

The number of waiting event matching the predicate.

sim_waiting

int sim_waiting(sim_event & event, sim_predicate & p)

This method computes the number of events in the deferred queue, for which destination is this entity, that match the predicate requirements.

Parameters:

p The predicate which has to be matched.

event is filled with the content of the incoming event (tag and value if relevant).

Returns:

The number of waiting event matching the predicate.

The sim_system class

sim_clock

sim_time sim_clock()

Returns:

The current simulation time.

Macro instructions

SIM_PUT(type,val)

Produces a packet with the C++ type type and the value val.

SIM_CAST(type,var,ev)

Extracts the packet contained in the event ev assuming its C++ type is type. The value of this event is put in the C++ variable var. Obviously, the type of this variable must be compatible with type.

Predicates

SIM_ANY

sim_from_port

Constructor:

sim_from_port(sim_port & p)
This predicate checks if an event comes from the port given in the constructor.

Example:

sim_port alua;
sim_event ev;

sim_from_port ina(alua);

if (sim_waiting(ev, ina)>0)
// execute some behaviour when receiving an event from the port alua.

sim_type_p

Constructors:

sim_type_p(int type1)
sim_type_p(int type1, int type2)
sim_type_p(int type1, int type2, int type3)
sim_type_p(int type1, int type2, int type3, int type4)
This predicate checks if an event is carrying on the type1, type2, type3 or type4 tags. A constructor with an array of int should be added soon.

Example:

sim_type_p expected(CLOCK, MEMORY);
sim_event ev;
if (sim_waiting(ev, expected)>0))
// execute some behaviour when receiving an event carrying either the tag CLOCK or the tag MEMORY.

Home : Research : Groups : Hase : Manuals : Hasepp