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

#include <limits.h>
#include <float.h>
#include <stdarg.h>
#include <stdbool.h>
#include <stdint.h>
#include <stdio.h>
#include <stdlib.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.

Classes
struct	simulation_configuration
	A set of configurable values used by other modules. More...

Macros
#define	SIMTIME_MAX DBL_MAX
	The maximum value of the logical simulation time, semantically never.

#define	Expent(mean) ((mean) * Poisson())

#define	INVALID_DIRECTION UINT64_MAX
	An invalid direction, used as error value for the functions which return a LP id.

#define	PP_NARG(...) PP_NARG_(__VA_ARGS__,PP_RSEQ_N())
	Compute the number of arguments to a variadic macro.

#define	PP_NARG_(...) PP_128TH_ARG(__VA_ARGS__)
	Compute the number of arguments to a variadic macro.

#define	PP_128TH_ARG(_1, _2, _3, _4, _5, _6, _7, _8, _9, _10, _11, _12, _13, _14, _15, _16, _17, _18, _19, _20, _21, _22, _23, _24, _25, _26, _27, _28, _29, _30, _31, _32, _33, _34, _35, _36, _37, _38, _39, _40, _41, _42, _43, _44, _45, _46, _47, _48, _49, _50, _51, _52, _53, _54, _55, _56, _57, _58, _59, _60, _61, _62, _63, _64, _65, _66, _67, _68, _69, _70, _71, _72, _73, _74, _75, _76, _77, _78, _79, _80, _81, _82, _83, _84, _85, _86, _87, _88, _89, _90, _91, _92, _93, _94, _95, _96, _97, _98, _99, _100, _101, _102, _103, _104, _105, _106, _107, _108, _109, _110, _111, _112, _113, _114, _115, _116, _117, _118, _119, _120, _121, _122, _123, _124, _125, _126, _127, N, ...) N
	Enumerate the arguments' count to a variadic macro.

#define	PP_RSEQ_N()
	Enumerate the arguments' count to a variadic macro in reverse order. More...

#define	InitializeTopology(geometry, ...) vInitializeTopology(geometry, PP_NARG(__VA_ARGS__), __VA_ARGS__)
	Initialize a topology struct. More...

Typedefs
typedef double	simtime_t
	Simulation time data type.

typedef uint64_t	lp_id_t
	Logical Process ID data type.

typedef void(*	ProcessEvent_t) (lp_id_t me, simtime_t now, unsigned event_type, const void event_content, unsigned event_size, void st)
	ProcessEvent callback function. More...

typedef bool(*	CanEnd_t) (lp_id_t me, const void *snapshot)
	Determine if simulation can be halted. More...

Enumerations
enum	rootsim_event { LP_INIT = 65534 , LP_FINI }

enum	log_level { LOG_TRACE , LOG_DEBUG , LOG_INFO , LOG_WARN , LOG_ERROR , LOG_FATAL , LOG_SILENT }

enum	topology_geometry { TOPOLOGY_HEXAGON = 1 , TOPOLOGY_SQUARE , TOPOLOGY_TORUS , TOPOLOGY_RING , TOPOLOGY_BIDRING , TOPOLOGY_STAR , TOPOLOGY_FCMESH , TOPOLOGY_GRAPH }

enum	topology_direction { DIRECTION_E , DIRECTION_W , DIRECTION_N , DIRECTION_S , DIRECTION_NE , DIRECTION_SW , DIRECTION_NW , DIRECTION_SE , DIRECTION_RANDOM }

Functions
void	ScheduleNewEvent (lp_id_t receiver, simtime_t timestamp, unsigned event_type, const void *event_content, unsigned event_size)
	API to inject a new event in the simulation. More...

void	SetState (void *new_state)
	Set the LP simulation state main pointer. More...

void *	rs_malloc (size_t req_size)

void *	rs_calloc (size_t nmemb, size_t size)

void	rs_free (void *ptr)

void *	rs_realloc (void *ptr, size_t req_size)

double	Random (void)
	Return a random value in [0,1] according to a uniform distribution. More...

uint64_t	RandomU64 (void)
	Return a random 64-bit value. More...

double	Poisson (void)
	Return a random number according to an Exponential distribution with unit mean Corresponds to the waiting time to the next event in a Poisson process of unit mean. More...

double	Normal (void)
	Return a pair of independent random numbers according to a Standard Normal Distribution. More...

int	RandomRange (int min, int max)

int	RandomRangeNonUniform (int x, int min, int max)

double	Gamma (unsigned ia)
	Return a number in according to a Gamma Distribution of Integer Order ia Corresponds to the waiting time to the ia-th event in a Poisson process of unit mean. More...

unsigned	Zipf (double skew, unsigned limit)
	Return 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. More...

lp_id_t	CountRegions (struct topology *topology)

lp_id_t	CountDirections (lp_id_t from, struct topology *topology)

lp_id_t	GetReceiver (lp_id_t from, struct topology *topology, enum topology_direction direction)

void	ReleaseTopology (struct topology *topology)

bool	AddTopologyLink (struct topology *topology, lp_id_t from, lp_id_t to, double probability)

bool	IsNeighbor (lp_id_t from, lp_id_t to, struct topology *topology)

struct topology *	vInitializeTopology (enum topology_geometry geometry, int argc,...)
	Initialize a topology region. More...

int	RootsimInit (const struct simulation_configuration *conf)
	Initialize the core library. More...

int	RootsimRun (void)
	Start the simulation. More...

void	RootsimStop (void)
	Force termination of the simulation.

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-2022 HPDCS Group https://hpdcs.github.io

Macro Definition Documentation

◆ InitializeTopology

#define InitializeTopology	(	geometry,
		...
	)	vInitializeTopology(geometry, PP_NARG(__VA_ARGS__), __VA_ARGS__)

Initialize a topology struct.

Parameters

geometry	The topology struct to initialize
...	The number of regions and/or the number of links, depending on the topology geometry

Returns: A pointer to the topology structure

◆ PP_RSEQ_N

#define PP_RSEQ_N ( )

Value:

         127,126,125,124,123,122,121,120, \
         119,118,117,116,115,114,113,112,111,110, \
         109,108,107,106,105,104,103,102,101,100, \
         99,98,97,96,95,94,93,92,91,90, \
         89,88,87,86,85,84,83,82,81,80, \
         79,78,77,76,75,74,73,72,71,70, \
         69,68,67,66,65,64,63,62,61,60, \
         59,58,57,56,55,54,53,52,51,50, \
         49,48,47,46,45,44,43,42,41,40, \
         39,38,37,36,35,34,33,32,31,30, \
         29,28,27,26,25,24,23,22,21,20, \
         19,18,17,16,15,14,13,12,11,10, \
         9,8,7,6,5,4,3,2,1,0

Enumerate the arguments' count to a variadic macro in reverse order.

Typedef Documentation

◆ CanEnd_t

typedef bool(* CanEnd_t) (lp_id_t me, const void *snapshot)

Determine if simulation can be halted.

Parameters

me	The logical process ID of the called LP
snapshot	The committed state of the logical process

Returns: true if the simulation can be halted, false otherwise

This function receives a committed snapshot of the logical process state. It can be inspected to determine whether the simulation can be halted, locally at the LP. The function should return true if the simulation can be halted, false otherwise.

Warning: The snapshot is in the committed part of the simulation trajectory, so it should not be modified. Any change to the snapshot might lead to undefined behavior.

◆ ProcessEvent_t

typedef void(* ProcessEvent_t) (lp_id_t me, simtime_t now, unsigned event_type, const void *event_content, unsigned event_size, void *st)

ProcessEvent callback function.

Parameters

me	The logical process ID of the called LP
now	The current simulation time
event_type	The type of the simulation event
event_content	The (model-specific) content of the simulation event
event_size	The size of the event content
st	The current state of the logical process

This function is called by the simulation kernel whenever a new event is extracted from the event queue. The event is executed in the speculative part of the simulation trajectory: any change to the simulation state might be reverted by the simulation kernel in case a straggler event is detected.

Warning: The event content is not a copy, so it should not be modified. Failing to do so might lead to undefined behavior in case of straggler events.; Do not perform any non-rollbackable operation in this function (e.g., I/O).

Enumeration Type Documentation

◆ log_level

enum log_level

Enumerator
LOG_TRACE	The logging level reserved to very low priority messages.
LOG_DEBUG	The logging level reserved to useful debug messages.
LOG_INFO	The logging level reserved to useful runtime messages.
LOG_WARN	The logging level reserved to unexpected, non deal breaking conditions.
LOG_ERROR	The logging level reserved to unexpected, problematic conditions.
LOG_FATAL	The logging level reserved to unexpected, fatal conditions.
LOG_SILENT	Emit no message during the simulation.

◆ topology_direction

enum topology_direction

Enumerator
DIRECTION_E	East direction.
DIRECTION_W	West direction.
DIRECTION_N	North direction.
DIRECTION_S	South direction.
DIRECTION_NE	North-east direction.
DIRECTION_SW	South-west direction.
DIRECTION_NW	North-west direction.
DIRECTION_SE	South-east direction.
DIRECTION_RANDOM	Get a random direction, depending on the topology.

◆ topology_geometry

enum topology_geometry

Enumerator
TOPOLOGY_HEXAGON	hexagonal grid topology
TOPOLOGY_SQUARE	square grid topology
TOPOLOGY_TORUS	a torus shaped grid topology (a wrapping around square topology)
TOPOLOGY_RING	a ring shaped topology walkable in a single direction
TOPOLOGY_BIDRING	a ring shaped topology
TOPOLOGY_STAR	a star shaped topology
TOPOLOGY_FCMESH	a fully-connected mesh
TOPOLOGY_GRAPH	a (weighted) graph topology

Function Documentation

◆ Gamma()

double Gamma ( unsigned ia )

Return a number in according to a Gamma Distribution of Integer Order ia Corresponds to the 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

◆ Normal()

double Normal ( void )

Return a pair of independent random numbers according to a Standard Normal Distribution.

Returns: A pair of random numbers

◆ Poisson()

double Poisson ( void )

Return a random number according to an Exponential distribution with unit mean Corresponds to the waiting time to the next event in a Poisson process of unit mean.

Returns: A random number

◆ Random()

double Random ( void )

Return a random value in [0,1] according to a uniform distribution.

Returns: The random number

◆ RandomU64()

uint64_t RandomU64 ( void )

Return a random 64-bit value.

Returns: The random number

◆ RootsimInit()

int RootsimInit ( const struct simulation_configuration * conf )

Initialize the core library.

This function must be invoked so as to initialize the core. The structure passed to this function is copied into a library variable, that is used by the core to support the simulation run.

Parameters

conf	A pointer to a struct simulation_configuration used to configure the core library.

Returns: zero if the configuration is successful, non-zero otherwise.

◆ RootsimRun()

int RootsimRun ( void )

Start the simulation.

This function starts the simulation. It must be called after having initialized the ROOT-Sim core by calling RootsimInit(), otherwise the invocation will fail.

Returns: zero on successful simulation completion, non-zero otherwise.

◆ ScheduleNewEvent()

void ScheduleNewEvent	(	lp_id_t	receiver,
		simtime_t	timestamp,
		unsigned	event_type,
		const void *	event_content,
		unsigned	event_size
	)

API to inject a new event in the simulation.

This is a function pointer that is setup at simulation startup to point to either ScheduleNewEvent_parallel() in case of a parallel/distributed simulation, or to ScheduleNewEvent_serial() in case of a serial simulation.

Parameters

receiver	The ID of the LP that should receive the newly-injected message
timestamp	The simulation time at which the event should be delivered at the recipient LP
event_type	Numerical event type to be passed to the model's dispatcher
event_content	The event content
event_size	The size (in bytes) of the event content

◆ SetState()

void SetState ( void * state )

Set the LP simulation state main pointer.

Parameters

state The state pointer to be passed to ProcessEvent() for the invoker LP

◆ vInitializeTopology()

struct topology* vInitializeTopology	(	enum topology_geometry	geometry,
		int	argc,
			...
	)

Initialize a topology region.

This is a variadic function, that initializes a topology depending on its actual shape. In case the topology is a grid, two unsigned parameters should be passed, to specify the width and height of the grid. For all other topologies (included generic graphs) only a single unsigned parameter is needed, which is the number of elements composing the topology.

Parameters

geometry	The geometry to be used in the topology, a value from enum topology_geometry
argc	This is the number of variadic arguments passed to the function, computed thanks to some preprocessor black magic. This allows to make some early sanity check and prevent users to mess with the stack or initialize wrong topologies.
...	If geometry is TOPOLOGY_HEXAGON, TOPOLOGY_SQUARE, or TOPOLOGY_TORUS, two unsigned should be passed, to specify the width and height of the topology's grid. For all the other topologies, a single unsigned, determining the number of elements that compose the topology should be passed.

Returns: A pointer to as newly-allocated opaque topology struct. Releasing the topology (and all the memory internally used to represent it) can be done by passing it to ReleaseTopology().

◆ Zipf()

unsigned Zipf	(	double	skew,
		unsigned	limit
	)

Return 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

Classes

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ InitializeTopology

◆ PP_RSEQ_N

Typedef Documentation

◆ CanEnd_t

◆ ProcessEvent_t

Enumeration Type Documentation

◆ log_level

◆ topology_direction

◆ topology_geometry

Function Documentation

◆ Gamma()

◆ Normal()

◆ Poisson()

◆ Random()

◆ RandomU64()

◆ RootsimInit()

◆ RootsimRun()

◆ ScheduleNewEvent()

◆ SetState()

◆ vInitializeTopology()

◆ Zipf()