ROOT-Sim.h File Reference

ROOT-Sim header for model development. More...

#include <stdlib.h>
#include <stdio.h>
#include <stdint.h>
#include <string.h>
#include <stdbool.h>
#include <float.h>
#include <limits.h>
#include <argp.h>

Include dependency graph for ROOT-Sim.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	capability_info_t

Macros
#define	INIT   0
	This is the message code which is sent by the simulation kernel upon startup.
#define	INFTY   DBL_MAX
	Infinite timestamp: this is the highest timestamp in a simulation run.

Typedefs
typedef double	simtime_t
	This defines the type with whom timestamps are represented.
typedef enum _direction_t	direction_t
typedef unsigned long long	agent_t

Enumerations
enum	_topology_geometry_t {   TOPOLOGY_GEOMETRY_OFFSET = 1000, TOPOLOGY_HEXAGON = TOPOLOGY_GEOMETRY_OFFSET, TOPOLOGY_SQUARE, TOPOLOGY_RING,   TOPOLOGY_BIDRING, TOPOLOGY_TORUS, TOPOLOGY_STAR, TOPOLOGY_GRAPH }
enum	_direction_t {   DIRECTION_E = 0, DIRECTION_W = 1, DIRECTION_N = 2, DIRECTION_S = 3,   DIRECTION_NE = 2, DIRECTION_SW = 3, DIRECTION_NW = 4, DIRECTION_SE = 5,   DIRECTION_INVALID = UINT_MAX }
enum	_topology_type_t { TOPOLOGY_OBSTACLES, TOPOLOGY_COSTS, TOPOLOGY_PROBABILITIES }
enum	capability_t {   CAP_SCHEDULER, CAP_CKTRM_MODE, CAP_LPS_DISTRIBUTION, CAP_STATS,   CAP_STATE_SAVING, CAP_THREADS, CAP_LPS, CAP_OUTPUT_DIR,   CAP_P, CAP_GVT, CAP_GVT_SNAPSHOT_CYCLES, CAP_SEED,   CAP_VERBOSE, CAP_NPWD, CAP_FULL, CAP_INC,   CAP_A, CAP_SIMULATION_TIME, CAP_DETERMINISTIC_SEED, CAP_SERIAL,   CAP_CORE_BINDING, CAP_PREEMPTION, CAP_ECS, CAP_LINUX_MODULES,   CAP_LP_REBINDING, CAP_MPI, CAP_SILENT }
	Capability enumeration. More...

Functions
	__attribute ((weak)) extern struct argp model_argp
	This can be implemented by the model for smart argument handling. More...
double	Random (void)
int	RandomRange (int min, int max)
int	RandomRangeNonUniform (int x, int min, int max)
double	Expent (double mean)
double	Normal (void)
double	Gamma (int ia)
double	Poisson (void)
int	Zipf (double skew, int limit)
void	SetState (void *new_state)
double	GetValueTopology (unsigned from, unsigned to)
void	SetValueTopology (unsigned from, unsigned to, double value)
unsigned int	FindReceiver (void)
unsigned int	RegionsCount (void)
unsigned int	DirectionsCount (void)
unsigned int	NeighboursCount (unsigned int region)
unsigned int	GetReceiver (unsigned int from, direction_t direction, bool reachable)
unsigned int	FindReceiverToward (unsigned int to)
double	ComputeMinTour (unsigned int source, unsigned int dest, unsigned int result[RegionsCount()])
int	GetNeighbourInfo (direction_t i, unsigned int *region_id, void **data_p)
void	TrackNeighbourInfo (void *neighbour_data)
bool	IterAgents (agent_t *agent_p)
unsigned	CountAgents (void)
agent_t	SpawnAgent (unsigned user_data_size)
void	KillAgent (agent_t agent)
void *	DataAgent (agent_t agent, unsigned *data_size_p)
void	ScheduleNewLeaveEvent (simtime_t time, unsigned int event_type, agent_t agent)
unsigned	CountVisits (const agent_t agent)
void	GetVisit (const agent_t agent, unsigned *region_p, unsigned *event_type_p, unsigned i)
void	SetVisit (const agent_t agent, unsigned region, unsigned event_type, unsigned i)
void	EnqueueVisit (agent_t agent, unsigned region, unsigned event_type)
void	AddVisit (agent_t agent, unsigned region, unsigned event_type, unsigned i)
void	RemoveVisit (agent_t agent, unsigned i)
unsigned	CountPastVisits (const agent_t agent)
void	GetPastVisit (const agent_t agent, unsigned *region_p, unsigned *event_type_p, simtime_t *time_p, unsigned i)
bool	CapabilityAvailable (enum capability_t which, struct capability_info_t *info)
	Query runtime capabilities while executing the model. More...

Variables
unsigned int	n_prc_tot
	This is the definition of the number of LPs running in the current simulation. More...
void(*	ScheduleNewEvent )(unsigned int receiver, simtime_t timestamp, unsigned int event_type, void *event_content, unsigned int event_size)
	This is the function pointer to correctly set ScheduleNewEvent API version, depending if we're running serially or in parallel.
	topology_settings
	abm_settings

Detailed Description

ROOT-Sim header for model development.

This header defines all the symbols which are needed to develop a model to be simulated on top of ROOT-Sim.

This header is the only file which should be included when developing a simulation model. All function prototypes exposed to the application developer are exposed and defined here.

Copyright

Copyright (C) 2008-2019 HPDCS Group https://hpdcs.github.io

This file is part of ROOT-Sim (ROme OpTimistic Simulator).

ROOT-Sim is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; only version 3 of the License applies.

ROOT-Sim is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with ROOT-Sim; if not, write to the Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA

Author

Francesco Quaglia

Alessandro Pellegrini

Roberto Vitali

Date

3/16/2011

Definition in file ROOT-Sim.h.

Typedef Documentation

typedef enum _direction_t direction_t

These are the supported basic directions:

• TOPOLOGY_HEXAGON recognizes E, W, NE, SW, NW, SE
• TOPOLOGY_SQUARE and TOPOLOGY_TORUS recognize E, W, N, S
• TOPOLOGY_RING recognizes E
• TOPOLOGY_BIDRING recognizes E, W
• TOPOLOGY_STAR xxx to implement
• TOPOLOGY_GRAPH directions are actually directly mapped to the LPs IDs

The enum layout is intentional: do not modify it if you don't know what you're doing!

Enumeration Type Documentation

enum _direction_t

These are the supported basic directions:

• TOPOLOGY_HEXAGON recognizes E, W, NE, SW, NW, SE
• TOPOLOGY_SQUARE and TOPOLOGY_TORUS recognize E, W, N, S
• TOPOLOGY_RING recognizes E
• TOPOLOGY_BIDRING recognizes E, W
• TOPOLOGY_STAR xxx to implement
• TOPOLOGY_GRAPH directions are actually directly mapped to the LPs IDs

The enum layout is intentional: do not modify it if you don't know what you're doing!

Enumerator
DIRECTION_E	DIRECTION_E.
DIRECTION_W	DIRECTION_W.
DIRECTION_N	DIRECTION_N.
DIRECTION_S	DIRECTION_S.
DIRECTION_NE	DIRECTION_NE.
DIRECTION_SW	DIRECTION_SW.
DIRECTION_NW	DIRECTION_NW.
DIRECTION_SE	DIRECTION_SE.
DIRECTION_INVALID	A generic invalid direction.

Definition at line 113 of file ROOT-Sim.h.

enum _topology_geometry_t

These are the supported topology geometries

Enumerator
TOPOLOGY_GEOMETRY_OFFSET	arbitrary offset used to distinguish during debug different enums
TOPOLOGY_HEXAGON	hexagonal grid topology
TOPOLOGY_SQUARE	square grid topology
TOPOLOGY_RING	a ring shaped topology walkable in a single direction
TOPOLOGY_BIDRING	a ring shaped topology direction
TOPOLOGY_TORUS	a torus shaped grid topology (a wrapping around square topology)
TOPOLOGY_STAR	FIXME. Warning this still needs to be properly implemented FIXME
TOPOLOGY_GRAPH	an arbitrary shaped topology

Definition at line 89 of file ROOT-Sim.h.

enum _topology_type_t

Enumerator
TOPOLOGY_OBSTACLES	all crossing costs and probabilities are set to 1, but there can be not crossable regions
TOPOLOGY_COSTS	decisions on next hops are taken based on the costs undertaken to cross the boundaries
TOPOLOGY_PROBABILITIES	decisions are taken at random but are weighted on the palatability of neighbours

Definition at line 128 of file ROOT-Sim.h.

enum capability_t

Capability enumeration.

This enum allows to query from the model, using the CapabilityAvailable() API, what capabilities are current enabled in the runtime environment. Refer to the documentation of the CapabilityAvailable() API for further information on the Capability subsystem.

Warning

The order of the enum members is important, as it is used by the CapabilityAvailable() API to reduce the number of execution steps it takes to deliver the required information.

Definition at line 245 of file ROOT-Sim.h.

Function Documentation

__attribute

(

(weak)

)

This can be implemented by the model for smart argument handling.

Defining this struct in the model source code activates the topology subsystem.

< The topology type the model wants to use

< The default geometry to use when nothing else is specified

< The minimum number of LPs needed out of the topology

< This is set if the model needs to use SetTopology()

Definition at line 137 of file ROOT-Sim.h.

Here is the call graph for this function:

bool CapabilityAvailable	(	enum capability_t	which,
		struct capability_info_t *	info
	)

Query runtime capabilities while executing the model.

Several capabilities might be compiled out while building the runtime, or there are command line flags which enable/disable some of them. Other capabilities are parameterizable, e.g. the GVT computation interval.

This function allows to retrieve information from the runtime environment, e.g. to fine tune the execution of the model. Additional information could be returned in the info structure. For example, in case of the GVT, the current GVT computation time interval will be returned. Please note that the different members in the info parameter are included in an anonymous union, therefore you should only access the member corresponding to the queried capability. In any other case, you will possibly read garbage.

Parameters

which	The capability you are querying the runtime for availability
info	A pointer to a model buffer where to store additional information, if available for the capability specified by which. If info is set to NULL, then no additional information will be provided.

Returns

true if the capability (as specified by the capability_t enum) is available in the current run, or not

Expose to the simulation model the internal configuration of the simulator, to allow fine-tuning of the model depending on the current runtime configuration and/or command-line parameters.

Author

Alessandro Pellegrini

Parameters

which	the capability which the model is querying for availability
info	if this parameter is non-NULL, additional information is sent back to the application in the appropriate corresponding field. If this member is non-NULL, the capability member is set to which value, to let the model know what member of the union is meaningful.

Definition at line 461 of file init.c.

double Expent

(

double

mean

)

This function returns a random number according to an Exponential distribution. The mean value of the distribution must be passed as the mean value.

Parameters

mean	Mean value of the distribution

Returns

A random number

Definition at line 120 of file numerical.c.

double Gamma

(

int

ia

)

This function returns a number in according to a Gamma Distribution of Integer Order ia, a waiting time to the ia-th event in a Poisson process of unit mean.

Author

D. E. Knuth

Parameters

ia	Integer Order of the Gamma Distribution

Returns

A random number

Definition at line 179 of file numerical.c.

Here is the call graph for this function:

Here is the caller graph for this function:

double GetValueTopology	(	unsigned	from,
		unsigned	to
	)

TODO Documentation!

Parameters

from
to

Returns

Definition at line 288 of file topology.c.

Here is the caller graph for this function:

double Normal

(

void

)

This function returns a number according to a Normal Distribution with mean 0

Returns

A random number

Definition at line 141 of file numerical.c.

Here is the call graph for this function:

double Poisson

(

void

)

This function returns the waiting time to the next event in a Poisson process of unit mean.

Returns

A random number

Definition at line 223 of file numerical.c.

Here is the call graph for this function:

double Random

(

void

)

This function returns a number in between (0,1), according to a Uniform Distribution. It is based on Multiply with Carry by George Marsaglia

Returns

A random number, in between (0,1)

Definition at line 80 of file numerical.c.

Here is the caller graph for this function:

void SetState

(

void *

new_state

)

This function sets the buffer of the current LP's state

Author

Francesco Quaglia

Parameters

new_state

The new buffer

Definition at line 323 of file state.c.

void SetValueTopology	(	unsigned	from,
		unsigned	to,
		double	value
	)

Change the weight assigned to the link between region from to region to. A link is intended as a crossable edge on the topology graph. A weight has different meanings depending on the _topology_type_t of the topology. For TOPOLOGY_COSTS it's the cost to pay to cross the link For TOPOLOGY_PROBABILITIES it's the weight of the probability to choose that link during movement. In other words given a region n0 having self weight w0 having links to regions n1 n2 n3 n4... with weights w1 w2 w3 w4 the probability of choosing region nk as next hop is wk/(w0+w1+w2+w3...)

Parameters

from	the LP id of the source region of the link
to	the LP id of the sink region of the link
value	the new weight to be assigned to the link

Returns

0 on success, -1 otherwise.

Warning

Failure can happen if non existent links are specified or if value is an illegal argument (For TOPOLOGY_PROBABILITIES can't be negative for example)

Definition at line 261 of file topology.c.

Here is the caller graph for this function:

int Zipf	(	double	skew,
		int	limit
	)

This function returns a random sample from a Zipf distribution. Based on the rejection method by Luc Devroye for sampling: "Non-Uniform Random Variate Generation, page 550, Springer-Verlag, 1986

Parameters

skew	The skew of the distribution
limit	The largest sample to retrieve

Returns

A random number

Definition at line 237 of file numerical.c.

Here is the call graph for this function:

Variable Documentation

unsigned int n_prc_tot

This is the definition of the number of LPs running in the current simulation.

This is the definition of the number of LPs running in the current simulation.

Definition at line 64 of file core.c.