dsim_network Class Reference

Represents a network of simulation objects. More...

List of all members.

Public Member Functions
void	declare_variable (const std::string &name, int type, const char *description)
	Declares a connection variable that connections may have.
int	type_for_variable (const std::string &name)
	Looks up the type declared for a connection variable.
dsim_connection *	create_connection (const std::string &source, const std::string &destination, bool bi_directional=true)
	Creates a connection between two objects.
unsigned int	connection_count ()
	Retrieves the number of connections in this network.
dsim_connection_iterator	connection_iterator ()
	Retrieves the iterator for the set of connections.
dsim_connection *	retrieve_connection (const std::string &source, const std::string &destination, bool bi_directional=true)
	Looks up a connection by the nodes it connects.
unsigned int	object_identifier (const std::string &path)
	Gets the unique, sequential model identifier associated with a path.

---

Detailed Description

Represents a network of simulation objects.

Networks in DSim represent directed cyclic graphs of simulation objects. Objects are added to the graph only via connections to other objects; networks do not support "orphaned" (no incoming or outgoing edges in the graph) objects.

Networks support variables for the connections between objects in the network; these variables are declared on the network, and then each connection between two objects may have separate values for those variables set.

Connections may be unidrectional or bidirectional. A bidirectional connection is equivalent to two unidirectional connections where the values of variables at both connections are kept identical.

Networks support iteration over the connections to allow the managing object to inspect the network and its objects, connections and variables.

---

Member Function Documentation

unsigned int dsim_network::connection_count

(

)

Retrieves the number of connections in this network.

Returns:

The number of connections in this network.

dsim_connection_iterator dsim_network::connection_iterator

(

)

Retrieves the iterator for the set of connections.

Returns:

An iterator for the connections, which is used to iterate over the connections at this network.

dsim_connection * dsim_network::create_connection	(	const std::string &	source,
		const std::string &	destination,
		bool	bi_directional = true
	)

Creates a connection between two objects.

Networks contain only connections- objects are contained only insofar as they are part of a connection, and iterations over the network occur via connections rather than objects.

Connections can be either unidirectional or bidirectional. When a connection is bidirectional, the order of the source and destination does not matter, and (a,b) is considered to be the same connection as (b,a); with unidirectional connections, however, the two are different. Also, loopback connections - where the source and destination are the same - are legal.

All objects referenced by connections in the network are given a unique (within this network) object identifier, which starts at 1 and increases sequentially as new objects are referenced. The object identifier for a given path can be retrieved via object_identifier().

Parameters:

source	The path of the source object for the connection.
destination	The path of the destination object for the connection.
bi_directional	Whether or not the connection is bi-directional.

Returns:

If the specified connection already exists, a pointer to it will be returned. If it does not yet exist, it will be created and a pointer to the newly created connection returned.

void dsim_network::declare_variable	(	const std::string &	name,
		int	type,
		const char *	description
	)

Declares a connection variable that connections may have.

All connections are not required to have all declared variables, but a connection cannot have any variable not declared at its network.

Parameters:

name	The name of the variable.
type	The type that values of this variable will have
description	A human-readable description of the variable, used to guide users setting up this network in a setup file.

unsigned int dsim_network::object_identifier

(

const std::string &

path )

Gets the unique, sequential model identifier associated with a path.

Parameters:

path	The path of the object to lookup

Returns:

The identifier (a positive integer greater than zero), unique within this network, for the object at the provided path. If the provided path is not part of a connection at this network, 0 is returned.

dsim_connection * dsim_network::retrieve_connection	(	const std::string &	source,
		const std::string &	destination,
		bool	bi_directional = true
	)

Looks up a connection by the nodes it connects.

Parameters:

source	The path to the source of the connection
destination	The path to the destination of the connection
bi_directional	Whether or not the connection is bi-directional

Returns:

A pointer to the connection that matches the given source, destination, bi_directional triplet. If bi_directional is true, the order of source and destination does not matter. If no matching connection is found, NULL is returned.

int dsim_network::type_for_variable

(

const std::string &

name )

Looks up the type declared for a connection variable.

Parameters:

name	The name of the variable to look up

Returns:

The type associated with the provided variable name, or sd_type_invalid if no such variable has been declared.