dsim_model member functions that provide inter-object messaging functionality More...

Functions
virtual dsim_value	dsim_model::handle_message (const std::string &sender_path, const std::string &message_name, const dsim_value &argument)
	Overridden by subclasses to handle messages sent by other objects.
void	dsim_model::create_target (const char toarget_name, const char target_description, bool multiple=false)
	Create a target to be set in a setup file.
const char *	dsim_model::lookup_target (const char *target_name)
	Look up the target that was set in a setup file.
bool	dsim_model::set_target (const char target_name, const char target_path)
	Set the a target's path.
const std::vector< std::string > &	dsim_model::target_destinations (const std::string &target_name)
	Get the vector of destinations for a multi-valued target.
dsim_value	dsim_model::send_message (const char destination, const char message_name, const dsim_value &argument)
	Send a message to a destination object, and receive a value in return.

Detailed Description

dsim_model member functions that provide inter-object messaging functionality

In addition to communicating via variable values and outlets (or direct variable lookup), objects can pass messages. Messages consist of a string representing the name and a dsim_value argument; the object being messaged can then reply with a dsim_value return value.

Messaging allows objects to request that other objects take some action (perform some calculation, modify their state in some way, etc) and can occur at any time. This allows them to be more versatile than simple variable setting and retrieving, though more work is necessary to take advantage of them.

Objects can define "targets", with the actual target object being specified in the setup file. This way the actual destination of messages from the object can be changed easily by setup file modification rather than relying on hard-coded paths.

Function Documentation

void dsim_model::create_target	(	const char *	target_name,
		const char *	target_description,
		bool	multiple = `false`
	)		`[protected, inherited]`

Create a target to be set in a setup file.

Creates a target for this object. Targets are named references to other objects in the simulation; an object typically creates a target during the initialize_data() call and then subsequently looks up the provided target destination via lookup_target() to find variables at that target or to send messages to the target.

Parameters:

target_name	The name to give the target. If two create_target calls are made for the same target name, the second call will overwrite the first.
target_description	A human-readable description of this target, used to guide a user during simulation setup.
multiple	If true, this target will allow multiple destinations to be set for it. Retrieve the entire set of destinations later using target_destinations().

dsim_value dsim_model::handle_message	(	const std::string &	sender_path,
		const std::string &	message_name,
		const dsim_value &	argument
	)		`[virtual, inherited]`

Overridden by subclasses to handle messages sent by other objects.

Models should override this function to provide message handling capabilities. For messages that are not handled by this model, the message should be passed to the superclass implementation of handle_message().

Parameters:

sender_path	The path to the object that sent the message.
message_name	The message being sent.
argument	The argument provided with the message. Not all messages will require an argument; for those that do not, the argument can be ignored.

Returns:: The value to be provided as a return value to the sender. If no return value is appropriate, simply return a dsim_value object created with the default constructor: return dsim_value();

Reimplemented in dsim_rigid_body.

const char * dsim_model::lookup_target ( const char * target_name ) [protected, inherited]

Look up the target that was set in a setup file.

Looks up the destination set for a target with a provided name.

Parameters:

target_name The name of the target to retrieve.

Returns:: If the target exists, the specified destination path will be returned. An empty string will be returned if the target does not exist or does not have a destination set.

dsim_value dsim_model::send_message	(	const char *	destination,
		const char *	message_name,
		const dsim_value &	argument
	)		`[protected, inherited]`

Send a message to a destination object, and receive a value in return.

Sends a message to a specified destination object, and returns the value returned by that object.

Parameters:

destination	The path to the object to which the message should be sent.
message_name	The name of the message that should be sent. If the destination object does not exist or does not handle the message, a warning will be emitted.
argument	A value argument to provide with the message. If no argument should be sent, an invalid dsim_value (created by simply calling the default constructor) can be provided.

Returns:: The value returned by the destination object, if the message send was successful and the object returned a value; otherwise an invalid dsim_value will be returned.

bool dsim_model::set_target	(	const char *	target_name,
		const char *	target_path
	)		`[protected, inherited]`

Set the a target's path.

Sets a target's destination path.

Parameters:

target_name	The name of the target to set.
target_path	The destination path to set for the target.

Returns:: True, if the named target exists, or false if target_name specified an invalid target.

const std::vector< std::string > & dsim_model::target_destinations ( const std::string & target_name ) [protected, inherited]

Get the vector of destinations for a multi-valued target.

Retrieves the set of destinations stored for a multi-valued target.

Parameters:

target_name The name of the target to retrieve.

Returns:: If the target exists, a vector containing the stored destinations will be returned. An exception is thrown if the target does not exist.

Model Messaging

Functions

Detailed Description

Function Documentation