module

class module

The module class is an abstract simulation element

Public Classes

class data_ref

The data_ref class contains a pointer to data and a string which represents the data type refered to by the pointer

data_ref(void* data_arg = NULL, const string& type_arg = Type_Unknown): Default constructor
data_ref(const data_ref& source): Copy constructor
~data_ref(): Destructor
data_ref& operator=(const data_ref& rhs): Assignment operator
bool has_type(): Data type is not Type_Unknown
bool has_data(): Data pointer is not NULL
bool is_complete(): has_type && has_data
bool operator==(const data_ref& rhs): Data pointer and type are equal
bool operator!=(const data_ref& rhs): Not ==
void set_type(const string& type_arg): Sets type string to 'type_arg'
const string& get_type(): Retruns type string
void set_data(void* data_arg): Sets data pointer to 'data_arg'
void* get_data(): Returns data pointer
bool make_type(): Allocates space for type indicated by type string and sets data pointer to allocated space
bool parse_and_set(const string& str): Parse 'str' as type indicated by type string and set data pointed to by data pointer accordingly
void* data: Data pointer
string type: Type string

class data_str

The data_str class stores a string read from a data file and a string which contains the name of the source file and the line on which the data was found

data_str(const string& data_arg = "", const string& location_arg = ""): Default constructor
data_str(const data_str& source): Copy constructor
~data_str(): Destructor
data_str& operator=(const data_str& rhs): Assignment operator
void set_data(const string& data_arg): Sets data string to 'data_arg'
const string& get_data(): Returns data string
void set_location(const string& location_arg): Sets location string to 'location_arg'
const string& get_location(): Returns location string
string data: Data string
string location: Location string

enum message_type

Enumeration of message types

INT_ERROR: internal errors
INT_DEBUG: internal debugging messages
ERROR: usage errors
WARNING: usage warnings
INFO: user oriented informational messages
DEBUG: user oriented debugging messages
ALL_MESSAGES: all message types

class port

The port class represents an input or output to a module

enum state_bit: Enumerated bits for representing current state
const string NAME_SEPARATOR("::"): Used to separate port name from module name in output
port(const string& name_arg = "", const module* parent_arg = NULL): Default constructor
port(const port&): Copy constructor
~port(): Destructor
port& operator=(const port& rhs): Assignment operator
void set_name(const string& name_arg): Sets port name to 'name_arg'
string get_name(const module* with_respect_to = NULL): Returns port name
bool has_source(): The port has a data source, either its parent module or another port
bool immediate_source_is(const void* source_arg): The data source pointer is equal to 'source_arg'
bool eventual_source_is(const void* source_arg): The address of the data source (possibly several ports away) is 'source_arg'
bool has_complete_ref(): Data reference is complete ( see data_ref::is_complete() )
bool had_error(): An error has occured during resolution
bool is_resolved(): Resolution is complete
bool unset_source(): Disconnects this port from its source
bool set_source(port* remote_source_arg): Sets data source to 'remote_source_arg'
bool set_source(module* local_source_arg): Sets data source to 'local_source_arg'
const data_ref& get_ref(const data_ref& default_ref): Returns data reference
bool tick_nq_source( adlib_queue<module*>* pretickq, adlib_queue<module*>* tickq, adlib_queue<module*>* tbdq ): Asks source to add itself and it's dependencies to the pretick and tick queues as needed
string name: The name of the port
const module* parent: The module to which the port is attached
module* local_source: The immediate data source if it is a module
port* remote_source: The immediate data source if it is a port
adlib_flexible_array1d <port*> dependent: A list of ports which have the port as an immediate data source
adlib_bitset32 state: The current state of the port
data_ref ref: The eventual data source
void add_dependent(port* p): Adds a port to the 'dependent' list
void remove_dependent(port* p): Removes a port from the 'dependent' list

Public Methods
bool connect(const string& pfname, module* dest, const string& ptname): Attempts to connect port 'pfname' on module 'dest' to port 'ptname' on this module
void copy_message_interface(const module& source): Copies the message interface of the source module
void disable_messages(message_type index): Disables output of messages of type 'index'
bool disconnect(const string& pfname, module* dest, const string& ptname): Attempts to disconnect port 'pfname' on module 'dest' from port 'ptname' on this module
void enable_messages(message_type index): Enables output of messages of type 'index'
adlib_stack <string> get_bound_port_names(): Returns stack containing name of ports with a source
string get_name(const module* with_respect_to = NULL): Gets name of module with respect to 'with_respect_to'
data_ref get_port_ref(port* pt): Returns data_ref belonging to port 'pt'
inline adlib_real get_time_now(): Returns the current time as recorded by the module's internal clock
adlib_real get_time_step(): Returns the simulation time step for this module
const string& get_type(): Returns module type
adlib_stack <string> get_unbound_port_names(): Returns stack containing name of ports with no source
void load(file_reader* fr = NULL, int depth = 0): Loads configuration information from a description file
string make_indexed_input_name(int index): Constructs and returns a standard input name from an integer index
string make_indexed_output_name(int index): Constructs and returns a standard output name from an integer index
virtual module* make_type( const string& name_arg, const module* parent_arg, const string& mod_type ): Returns a pointer to a new module of type 'mod_type' if possible, otherwise NULL
bool messages_enabled(message_type index): Output of messages of type 'index' is enabled
module(const module& source): Copy Constructor
module(const string& name_arg, const module* parent_arg, const string& mod_type): Constructor
inline adlib_real module::get_time_now()
inline void module::pretick(): inline functions
inline void module::tick()
virtual module* new_type(const string& name_arg, const module* parent_arg): Returns a pointer to a new module of the same type
module& operator=(const module& rhs): Assignment operator
bool parse_indexed_input_name(const string& pname, int* index = NULL): Parses a standard input name as constructed by 'make_indexed_input_name'
bool parse_indexed_output_name(const string& pname, int* index = NULL): Parses a standard output name as constructed by 'make_indexed_output_name'
inline void pretick(): Instructs a module to produce output values for the next time interval
bool resolve_dependencies(): Attempts to resolve all ports upon this module depends
void save(file_writer* fw): Saves configuration information to a description file
void send_messages_to(ostream* os, message_type index): Sets the destination of messages of type 'index'
void set_name(const string& name_arg): Sets the name of the module to 'name_arg'
bool set_time_step(adlib_real time_step_arg): Sets the simulation time step for this module
inline void tick(): Instructs a module to read from its inputs and write to its outputs
bool tick_nq_dependencies( adlib_queue<module*>* pretickq, adlib_queue<module*>* tickq, adlib_queue<module*>* tbdq, bool recursive ): Enters this module and all modules upon which it depends into the pretick and tick queues as needed
virtual ~module(): Destructor

Public

enum message_type

Enumeration of message types

INT_ERROR: internal errors
INT_DEBUG: internal debugging messages
ERROR: usage errors
WARNING: usage warnings
INFO: user oriented informational messages
DEBUG: user oriented debugging messages
ALL_MESSAGES: all message types

Protected Fields
const string Mod_Type: Stores the module type

Protected Methods
virtual void action(): Called by 'tick()'
virtual bool describe_port( const string& port_name, data_ref* default_ref = NULL, bool* is_dependent = NULL ): Requests information about port 'port_name'
string file_reader_location(const file_reader& fr): Returns a string suitable for output containing the current read location of 'fr'
bool file_reader_next(file_reader* fr, int depth): Moves 'fr' to the next field at argument depth 'depth'
port* find_or_add_port(const string& pname): Returns a pointer to port 'pname'
port* find_port(const string& pname): Returns a pointer to port 'pname' if it exists, otherwise NULL
virtual adlib_stack <string> get_dependencies(): Returns list of all ports upon which this module depends
void have_delay(): Identifies module as having an internal delay
string int_to_string(int i): Converts 'i' to a string
ostream& mess(message_type index): Returns a ostream to which messages of type 'index' may be written
ostream& mess_cont(message_type index): Returns a ostream to which messages of type 'index' may be written
void parse_error(const file_reader& fr, const string& as): Outputs a standard parse error message
void parse_error( const string& field, const string& as, const string& location ): Outputs a standard parse error message
virtual void preaction(): Called by 'pretick()'
string real_to_string(adlib_real x, int precision): Converts 'x' to a string with precision 'precision'
void remove_port(port* p): Removes port 'p'
void set_all( file_reader* fr, int depth, const adlib_array1d<string>& keyword, const adlib_array1d<string>& err, adlib_array1d<data_ref>* ref, adlib_array1d< adlib_stack<data_str> >* str ): This function reads through all fields produced by 'fr' at argument depth 'depth' looking for fields of the form "<keyword> = <value>"
virtual void set_data_pointer(const string& port_name, const void* data_pointer): Sets a pointer to the location of input data from port 'port_name'
void set_time_now(adlib_real time_now_arg): Sets the module's interal clock to 'time_now_arg'
virtual void sub_load(file_reader* fr, int depth): Request that the module use information presented by 'fr' at argument depth 'depth' or deeper to configure itself
virtual void sub_save(file_writer* fw): Not yet implemented
virtual bool sub_set_time_step(adlib_real time_step_arg): Sets the module's internal time step to 'time_step_arg'
void syntax_error(const file_reader& fr): Outputs a standard syntax error message

Private Fields
adlib_flexible_array1d <port> io_port: Array of ports
adlib_array1d <message_stream> message_left: Array of message streams
string name: Module name
const module* parent: The module's parent
adlib_bitset32 state: Current state of the module
adlib_real time_now: The current time
adlib_real time_step: The simulation time step

Private Methods
void build_message_headers(): Builds message headers and configures message streams
bool connect_from(port* pf, const string& ptname): Connects port 'pf' to local port 'ptname'
bool disconnect_from(port* pf, const string& ptname): Disconnects port 'pf' from local port 'ptname'
const string MOD_NAME_SEPARATOR("."): Used by 'get_name()' to contruct module name

Private
enum state_bit: Enumeration of internal state indicators

Documentation

The module class is an abstract simulation element. It provides a general interface and takes care of io bookkeeping for derived classes.

class data_ref

The data_ref class contains a pointer to data and a string which represents the data type refered to by the pointer

data_ref(void* data_arg = NULL, const string& type_arg = Type_Unknown)

Default constructor

data_ref(const data_ref& source)

Copy constructor

~data_ref()

Destructor

data_ref& operator=(const data_ref& rhs)

Assignment operator

bool has_type()

Data type is not Type_Unknown

bool has_data()

Data pointer is not NULL

bool is_complete()

has_type && has_data

bool operator==(const data_ref& rhs)

Data pointer and type are equal

bool operator!=(const data_ref& rhs)

Not ==

void set_type(const string& type_arg)

Sets type string to 'type_arg'

const string& get_type()

Retruns type string

void set_data(void* data_arg)

Sets data pointer to 'data_arg'

void* get_data()

Returns data pointer

bool make_type()

Allocates space for type indicated by type string and sets data pointer to allocated space. Returns success. Will fail if type string is not recognized or space is not availible.

bool parse_and_set(const string& str)

Parse 'str' as type indicated by type string and set data pointed to by data pointer accordingly. Returns success. Will fail if type string is not recognized or space is not availible.

The data_str class stores a string read from a data file and a string which contains the name of the source file and the line on which the data was found

data_str(const string& data_arg = "", const string& location_arg = "")

Default constructor

data_str(const data_str& source)

Copy constructor

~data_str()

Destructor

data_str& operator=(const data_str& rhs)

Assignment operator

void set_data(const string& data_arg)

Sets data string to 'data_arg'

const string& get_data()

Returns data string

void set_location(const string& location_arg)

Sets location string to 'location_arg'

const string& get_location()

Returns location string

string data

Data string

string location

Location string

class port

The port class represents an input or output to a module

enum state_bit

Enumerated bits for representing current state

const string NAME_SEPARATOR("::")

Used to separate port name from module name in output

port(const string& name_arg = "", const module* parent_arg = NULL)

Default constructor

port(const port&)

Copy constructor

~port()

Destructor

port& operator=(const port& rhs)

Assignment operator

void set_name(const string& name_arg)

Sets port name to 'name_arg'

string get_name(const module* with_respect_to = NULL)

Returns port name

bool has_source()

The port has a data source, either its parent module or another port

bool immediate_source_is(const void* source_arg)

The data source pointer is equal to 'source_arg'

bool eventual_source_is(const void* source_arg)

The address of the data source (possibly several ports away) is 'source_arg'

bool has_complete_ref()

Data reference is complete ( see data_ref::is_complete() )

bool had_error()

An error has occured during resolution

bool is_resolved()

Resolution is complete

bool unset_source()

Disconnects this port from its source. Returns success. Will fail if resolution has begun.

bool set_source(port* remote_source_arg)

Sets data source to 'remote_source_arg'

bool set_source(module* local_source_arg)

Sets data source to 'local_source_arg'

const data_ref& get_ref(const data_ref& default_ref)

Returns data reference

bool tick_nq_source( adlib_queue<module*>* pretickq, adlib_queue<module*>* tickq, adlib_queue<module*>* tbdq )

Asks source to add itself and it's dependencies to the pretick and tick queues as needed. Return value results from eventual call to tick_nq_dependencies

string name

The name of the port

const module* parent

The module to which the port is attached

module* local_source

The immediate data source if it is a module

port* remote_source

The immediate data source if it is a port

adlib_flexible_array1d <port*> dependent

A list of ports which have the port as an immediate data source

adlib_bitset32 state

The current state of the port

data_ref ref

The eventual data source

void add_dependent(port* p)

Adds a port to the 'dependent' list

void remove_dependent(port* p)

Removes a port from the 'dependent' list

enum message_type

Enumeration of message types

INT_ERROR

internal errors

INT_DEBUG

internal debugging messages

user oriented informational messages

DEBUG

user oriented debugging messages

ALL_MESSAGES

all message types

module(const string& name_arg, const module* parent_arg, const string& mod_type)

Constructor

module(const module& source)

Copy Constructor

virtual ~module()

Destructor

module& operator=(const module& rhs)

Assignment operator

const string& get_type()

Returns module type

virtual module* make_type( const string& name_arg, const module* parent_arg, const string& mod_type )

Returns a pointer to a new module of type 'mod_type' if possible, otherwise NULL. Generally this will only succeed if the module called is of type 'mod_type' or is a composite type (i.e. 'box'). Default behavior is to return the result of 'new_type(...)' if 'mod_type == get_type()', otherwise return NULL.

virtual module* new_type(const string& name_arg, const module* parent_arg)

Returns a pointer to a new module of the same type. The intension here is to provide a simple means of creating instances of classes derived from module without knowing the explicit type. All this function need contain is: '{ return new <derived class name>(name_arg, parent_arg); }'

void set_name(const string& name_arg)

Sets the name of the module to 'name_arg'

string get_name(const module* with_respect_to = NULL)

Gets name of module with respect to 'with_respect_to'. The returned name is recursively built by calling the parent module until either the module called has no parent, the module's parent is 'with_respect_to' or the module itself is 'with_respect_to'. The constant 'MOD_NAME_SEP' is used to separate the module's internal name from the name returned by its parent.

void load(file_reader* fr = NULL, int depth = 0)

Loads configuration information from a description file. This function may be called more then once.

void save(file_writer* fw)

Saves configuration information to a description file. Not yet implemented.

bool set_time_step(adlib_real time_step_arg)

Sets the simulation time step for this module

adlib_real get_time_step()

Returns the simulation time step for this module

void send_messages_to(ostream* os, message_type index)

Sets the destination of messages of type 'index'

void enable_messages(message_type index)

Enables output of messages of type 'index'

void disable_messages(message_type index)

Disables output of messages of type 'index'

bool messages_enabled(message_type index)

Output of messages of type 'index' is enabled

void copy_message_interface(const module& source)

Copies the message interface of the source module

string make_indexed_input_name(int index)

Constructs and returns a standard input name from an integer index

string make_indexed_output_name(int index)

Constructs and returns a standard output name from an integer index

bool parse_indexed_input_name(const string& pname, int* index = NULL)

Parses a standard input name as constructed by 'make_indexed_input_name'. Sets 'index' to input index. Returns success.

bool parse_indexed_output_name(const string& pname, int* index = NULL)

Parses a standard output name as constructed by 'make_indexed_output_name'. Sets 'index' to output index. Returns success.

adlib_stack <string> get_unbound_port_names()

Returns stack containing name of ports with no source. Typically these are unclaimed input ports.

adlib_stack <string> get_bound_port_names()

Returns stack containing name of ports with a source. Typically these are output ports, or claimed input ports.

bool connect(const string& pfname, module* dest, const string& ptname)

Attempts to connect port 'pfname' on module 'dest' to port 'ptname' on this module. Returns success.

bool disconnect(const string& pfname, module* dest, const string& ptname)

Attempts to disconnect port 'pfname' on module 'dest' from port 'ptname' on this module. Returns success.

data_ref get_port_ref(port* pt)

Returns data_ref belonging to port 'pt'

bool resolve_dependencies()

Attempts to resolve all ports upon this module depends

bool tick_nq_dependencies( adlib_queue<module*>* pretickq, adlib_queue<module*>* tickq, adlib_queue<module*>* tbdq, bool recursive )

Enters this module and all modules upon which it depends into the pretick and tick queues as needed. This function maybe called many times, but any one module can only enter a given queue once. A return value of 'true' indicates that the port will recieve data with no artificial delay. 'false' indicates that a causal loop has been detected and that the port will recieve data which is one step behind.

inline void tick()

Instructs a module to read from its inputs and write to its outputs. This also increments the module's internal clock.

inline void pretick()

Instructs a module to produce output values for the next time interval. Input values should not by used at this time. This does not increment the module's internal clock. This function should be used by modules which have an internal delay which allows them to produce output at a given time without knowing the input at that time (i.e. a propagator).

inline adlib_real get_time_now()

Returns the current time as recorded by the module's internal clock

const string Mod_Type

Stores the module type

void have_delay()

Identifies module as having an internal delay. This module will be preticked and should be able to produce its output before recieving its input.

void set_time_now(adlib_real time_now_arg)

Sets the module's interal clock to 'time_now_arg'

ostream& mess(message_type index)

Returns a ostream to which messages of type 'index' may be written. A header including the name of the module and a message type indicator will precede the message in the ostream. The message should be terminated by an 'endl'.

ostream& mess_cont(message_type index)

Returns a ostream to which messages of type 'index' may be written. No header is written to the message, so this should only be used to continue a message line in progress.

void remove_port(port* p)

Removes port 'p'

port* find_port(const string& pname)

Returns a pointer to port 'pname' if it exists, otherwise NULL

port* find_or_add_port(const string& pname)

Returns a pointer to port 'pname'

string file_reader_location(const file_reader& fr)

Returns a string suitable for output containing the current read location of 'fr'

bool file_reader_next(file_reader* fr, int depth)

Moves 'fr' to the next field at argument depth 'depth'. Returns success. Fields at an argument depth greater than 'depth' will be skipped (a warning message will result).

void parse_error(const file_reader& fr, const string& as)

Outputs a standard parse error message

void parse_error( const string& field, const string& as, const string& location )

Outputs a standard parse error message

void syntax_error(const file_reader& fr)

Outputs a standard syntax error message

void set_all( file_reader* fr, int depth, const adlib_array1d<string>& keyword, const adlib_array1d<string>& err, adlib_array1d<data_ref>* ref, adlib_array1d< adlib_stack<data_str> >* str )

This function reads through all fields produced by 'fr' at argument depth 'depth' looking for fields of the form "<keyword> = <value>". If 'ref' is non-null the value of each keyword encountered is set using 'data_ref::parse_and_set(<value>)'. Failure will produce a parse error (with 'parse_error(*fr, err[<keyword index>]'). If 'str' is non-null the <value> and location (as produced by 'file_reader_location(*fr)') for each keywork encountered is recorded therein.

virtual bool describe_port( const string& port_name, data_ref* default_ref = NULL, bool* is_dependent = NULL )

Requests information about port 'port_name'. A NULL argument indicates that that information is not needed. 'default_ref' is the data_ref which the port will use as a data source if it is not otherwise connected. For outputs, this data_ref should refer to the output data location and type. For inputs, this should refer to the default input location and type. 'is_dependent' indicates whether the port depends on the module for data (typically an output) or not (typically an input).

virtual adlib_stack <string> get_dependencies()