Functions

Model Initialization

dsim_model member functions that handle initialization tasks. More...

Functions

virtual void * dsim_model::describe_setup (void *ds)
 Overridden by subclasses to describe the custom setup data that they can handle.
void dsim_model::describe_setup_command (void *ds, const char *command, const char *description)
 Called by subclasses from within describe_setup() to describe a setup command that they accept.
virtual bool dsim_model::parse_setup (const char *command, const char *data)
 Overridden by subclasses to handle custom setup data.
virtual void dsim_model::initialize_data ()
 Overridden by subclasses to create variables and outlets.
virtual void dsim_model::initialization_complete ()
 Overridden by subclasses to request variables and set up for propagation.

Detailed Description

dsim_model member functions that handle initialization tasks.

These methods handle object initialization tasks, as well as providing documentation for the types of custom setup commands that this model handles (describe_setup() and describe_setup_command()). Most subclasses will at least override initialize_data() and initialization_complete(); those that need to provide custom setup commands will also override parse_setup(), describe_setup(), and describe_setup_command().


Function Documentation

void * dsim_model::describe_setup ( void *  ds ) [virtual, inherited]

Overridden by subclasses to describe the custom setup data that they can handle.

By overriding describe_setup(), models are able to self-document the setup commands that they accept. This is necessary for users to properly set up objects of this model with the DSim Manager application, as only described setup commands can be used from that application. Models that do not accept custom setup commands do not need to provide an implementation of this function, but models that override parse_setup() should also override describe_setup().

Within the describe_setup() implemenation, describe_setup_command() should be called once for each setup command that this model accepts.

Always call your model's superclass's implementation of describe_setup() first.

Parameters:
dsAn opaque pointer to a setup data structure. It should be passed unchanged to calls to describe_setup_command, and then provided as the functions return value.
Returns:
The function should return its argument, ds.
void dsim_model::describe_setup_command ( void *  ds,
const char *  command,
const char *  description 
) [inherited]

Called by subclasses from within describe_setup() to describe a setup command that they accept.

Documents a single setup command accepted by this model.

Parameters:
dsThe opaque setup pointer provided as the parameter to the call to describe_setup().
commandA command accepted by this model, which should match one of the strings handled by this model's implementation of parse_setup().
descriptionA human-readable description of this command. This description will be displayed to users who are setting up objects of this model to allow them to properly use the custom setup commands.
void dsim_model::initialization_complete (  ) [virtual, inherited]

Overridden by subclasses to request variables and set up for propagation.

Called by the simulation on all objects to indicate that initialization has completed. At the time of this call, all objects will have had initialize_data() called on them, all networks, targets, and outlets will be set up, and all custom setup lines will have been handled. This is the appropriate function for any intialization tasks which require the rest of the simulation to be set-up and accessible.

Models that override this function must take care to call their superclass's implementation first.

Reimplemented in dsim_ideal_gravity, dsim_ideal_spring, and dsim_second_order.

void dsim_model::initialize_data (  ) [virtual, inherited]

Overridden by subclasses to create variables and outlets.

Called by the simulation engine on all objects after all objects have been created and placed appropriately in the simulation hierarchy. Models should override this function to do any variable initialization that the model requires: all calls to create_* functions should take place within this function.

When the simulation calls initialize_data(), it is the model's first opportunity to use DSim function calls. However, the order in which models are initialized is undefined, so models should not attempt to access the simulation hierarchy, look up external variables or objects, or otherwise expect that any other objects in the system have been set up. Initialization tasks that require interacting with the rest of the simulation should be deferred until initialization_complete() is called.

Models that override this function must take care to call their superclass's implementation first.

Reimplemented in dsim_ideal_gravity, dsim_ideal_spring, dsim_rigid_body, and dsim_second_order.

bool dsim_model::parse_setup ( const char *  command,
const char *  data 
) [virtual, inherited]

Overridden by subclasses to handle custom setup data.

Handles a custom setup command from the setup file for this object. Exactly what the model does with this command is entirely up to the model. This function is always called after initialize_data(); all simulation objects will have been at least initially set up at this point, and DSim methods may be invoked.

Models that override parse_setup() should also override describe_setup_command() to document the setup commands. Also, any commands not handled by this model should be passed to the superclass implementation of the method for handling.

Parameters:
commandThe command string provided for this custom setup line.
dataThe data string for the command. The format and interpretation of this command is entirely determined by the model that handles the command.
Returns:
If the command was successfully handled by this model (or a superclass), return true. Returning false will stop setup file parsing and report a simulation error (generally stopping the run of the simulation.)
 All Classes Files Functions Typedefs Enumerations Enumerator