Superclass for all data source plugins. More...
Inherited by VCArchiveSource, VCControlDeck2Source, VCControlDeckSource, VCDSim2Source, VCDSimSource, VCFlatFileSource, and VCTestSource.
Public Member Functions | |
| VCDataSource (const ds_dictionary *init_data) | |
| Constructor. | |
| virtual | ~VCDataSource () |
| Destructor. | |
| virtual void | run_source () |
| The primary run loop. This function should not return until the source is ready to close. | |
Protected Member Functions | |
| bool | wait_for_configuration () |
| Whether or not the user has indicated a desire to provide configuration data. | |
| virtual bool | initialize () |
| Called by the superclass to initialize the data source. | |
| virtual bool | configure (const ds_dictionary *configuration_data) |
| Called by the superclass to handle configuration data. | |
| virtual ds_dictionary * | configuration_query (const ds_dictionary *query) |
| Called by the superclass to respond to configuration queries from configurators. | |
| virtual bool | setup_metadata () |
| Called by the superclass to define the data tree for this source. | |
| virtual bool | run () |
| Called by the superclass to handle actions that must occur when the source transitiions to the run state. | |
| virtual bool | pause () |
| Called by the superclass to pause the source. | |
| virtual bool | resume () |
| Called by the superclass to handle resuming fromm pause. | |
| virtual bool | terminate () |
| Called by the superclass to provide and handling that should occur at termination. | |
| virtual bool | reset () |
| Called by the superclass to provide "Quick Reset" functionality and increment the run number. | |
| void | configuration_required (const ds_dictionary *configuration_description) |
| Indicate that configuration is required, and optionally provide a dictionary that describes what is needed. | |
| void | configuration_complete () |
| Indicate that the source is now fully configured. | |
| void | metadata_complete () |
| Indicate that the source has has defined all of the required metadata. | |
| void | run_completed () |
| Indicate that the source has finished producing data for this run. | |
| void | increment_run () |
| Increment the run number; all subsequent data will be sent tagged with the new run number. | |
| VCDataSourceState_t | stage () |
| Get the current state of the source. | |
| int | define_point (const char *path, int type, const char *units="", const char *description="") |
| Define a data point produced by this source. | |
| int | lookup_point (const char *path) |
| Look up the id of a defined point based on its path. | |
| void | define_point_dimensions (int key, int rows, int columns) |
| Provide dimension hints for a defined point. | |
| void | define_point_attribute (int key, const char *attribute, const char *value) |
| Provide an attribute/value pair for a defined point. | |
| void | set_point_as_unlogged (int key, bool unlogged) |
| Mark a point as unlogged (data is not saved) | |
| int | define_command (const char *command_path, int type, const char *units="", const char *description="") |
| Define a command accepted by this source. | |
| int | lookup_command (const char *path) |
| Look up the id of a defined command based on its path. | |
| void | define_command_dimensions (int key, int rows, int columns) |
| Provide dimension hints for a defined command. | |
| void | define_command_attribute (int key, const char *attribute, const char *value) |
| Provide an attribute/value pair for a defined point. | |
| void | store_data (int index, void *data) |
| Set the current value of the point with the provided id. | |
| void | send_data (const ds_date &datestamp, bool no_broadcast=false) |
| Send the values of all points that have been updated since the last store_data() call. | |
| void | complete_historical_load () |
| Indicate that any historical data has been loaded and sent. | |
| virtual bool | commands_arrived () |
| Called by the superclass when new commands have arrived from the client. | |
| virtual bool | handle_command (int key, const char *path, void *data, unsigned int length, const ds_date &execute_time) |
| Called by the superclass to handle a specific command. | |
| void | run_commands_until_date (const ds_date &stop_date) |
| Ask the data source to call handle_command() for any commands that should be executed before a specific time. | |
| ds_date | next_command_execute_time () |
| Get the execution time of the next scheduled command. | |
| bool | unpack_data (void *destination, int data_type, void *data, unsigned int length) |
| Unpack command data based on its type. | |
| void | install_timer (const char *name, double period, bool repeat, void(*callback)(VCDataSource *source, const char *name, void *context), void *context) |
| Install a timer callback. | |
| void | remove_timer (const char *name) |
| Delete a timer callback. | |
| bool | run_subtask (bool dup_stdout, bool dup_stderr, int *input_fd, int *output_fd, const char *path, const char *args[]) |
| Start up a subprocess and pipe its input and output into this data source. | |
| void | throw_error (const char *msg,...) |
| Move the data source into the error state, and print a message to the console describing the problem. | |
| void | log_message (VCLogSeverity_t severity, const char *msg,...) |
| Print a log message to the console with a standard prefix giving the data, process, etc. | |
| void | handle_messages (const ds_date *stop_date=NULL) |
| Ask the data source to handle any messages for a period of time. Subclasses must call this at least periodically. | |
The VCDataSource class provides a superclass for all data source plugins. User plugins override specific virtual functions to customize the behavior of the data source, and call VCDataSource functions to access relevant functionality.
| VCDataSource::VCDataSource | ( | const ds_dictionary * | init_data ) |
Data source constructor. Subclasses must be sure to pass in the init_data paramter from the factory function without modification.
| init_data | The initialization dictionary for the data source. |
| bool VCDataSource::commands_arrived | ( | ) | [protected, virtual] |
When command messages arrive from VisualCommander, this method will be called, giving the data source an opportunity to see when the next command should be executed. The default implementation does nothing, and it is not required to override this method.
| void VCDataSource::complete_historical_load | ( | ) | [protected] |
Inform all clients that historical data has been loaded and that they should re-check the available range of data. This function should generally be called after a sequence of send_data() calls has been made with the no_broadcast flag set to true.
ds_dictionary *send_dict = new ds_dictionary(*data_dict);
| void VCDataSource::configuration_complete | ( | ) | [protected] |
Indicate that all configuration has ocurred, and that the data source is now ready to continue the startup sequence. The stage will be moved to VCDataSourceInitializing.
This function will throw an error if it is called when the stage is not VCDataSourceNeedsConfig or VCDataSourceStarting.
| ds_dictionary * VCDataSource::configuration_query | ( | const ds_dictionary * | query ) | [protected, virtual] |
Handle a configurator's configuration query to the source. Many sources will not need to implement this function.
| query | The dictionary provided by the configurator. The meaning of the content of this dictionary is entirely user-defined. |
| void VCDataSource::configuration_required | ( | const ds_dictionary * | configuration_description ) | [protected] |
Indicate that the data source requires configuration data, and optionally provide a description of what is required. This function will also move the data source to the VCDataSourceNeedsConfig stage.
| configuration_description | An optional configuraton description dictionary, or NULL if no description is provided. The meaning of the content of the dictionary, if provided, is entirely user defined; a configurator may use it in the client to customize the configuration options presented to the user. |
| bool VCDataSource::configure | ( | const ds_dictionary * | configuration_data ) | [protected, virtual] |
Handle configuration data sent to the source. If the configuration data is sufficient to complete the configuration of the source, this function should call configuration_complete() before returning.
| configuration_data | The configuration dictionary provided by the configurator |
| int VCDataSource::define_command | ( | const char * | command_path, |
| int | type, | ||
| const char * | units = "", |
||
| const char * | description = "" |
||
| ) | [protected] |
Define a command handled by this source.
| command_path | The path to the command. Paths take the form A|B|C:D, where A, B and C are volume names and D is the name of the point. That is, a path is formed by concatenating all parent volumes, in order from the root, with a pipe character '|' between each name, and by then appending a colon and the name of the command. To define a top-level command, simply provide no volume name; the colon is still required. Note that commands and points share a path namespace- a point and a command cannot both have the same path. |
| type | The data type of the command. Available options are:
|
| units | A string giving the units for the command, or an empty string if there are no units. Must not be null. |
| description | A string giving a human-readable description of the command, or an empty string if no description is available. Must not be null. |
| void VCDataSource::define_command_attribute | ( | int | key, |
| const char * | attribute, | ||
| const char * | value | ||
| ) | [protected] |
Provide an attribute/value pair for a command. Attribute/value pairs are visible to the user when they are inspecting source metadata, and they are also often used by displays to determine how a command should be interpreted or handled. Their meaning is entirely user-defined and they are not used internally by VisualCommander.
| key | The id of the command to provide an attribute for |
| attribute | The name of the attribute. Must not be null. Must be a null-terminated string. |
| value | the value for the attribute. Must not be null. Must be a null-terminated string. |
| void VCDataSource::define_command_dimensions | ( | int | key, |
| int | rows, | ||
| int | columns | ||
| ) | [protected] |
Provide dimension hints for a command. The dimension hints may be used by displays to determine what data to send. However, the dimensions are not enforced by the system- it sthe responsibility of the source, upon receiving a command, to ensure that the provided data is valid.
Integer and Double commands have implicit dimension hints of 1x1.
| key | The id of the command to add hints for |
| rows | The number of rows the command is expected to have |
| columns | The number of columns the command is expected to have |
| int VCDataSource::define_point | ( | const char * | path, |
| int | type, | ||
| const char * | units = "", |
||
| const char * | description = "" |
||
| ) | [protected] |
Define a point for which data will be provided by this source.
| path | The path to the point. Paths take the form A|B|C:D, where A, B and C are volume names and D is the name of the point. That is, a path is formed by concatenating all parent volumes, in order from the root, with a pipe character '|' between each name, and by then appending a colon and the name of the point. To define a top-level point, simply provide no volume name; the colon is still required. |
| type | The data type of the point. Available options are:
|
| units | A string giving the units for the point, or an empty string if there are no units. Must not be null. |
| description | A string giving a human-readable description of the point, or an empty string if no description is available. Must not be null. |
| void VCDataSource::define_point_attribute | ( | int | key, |
| const char * | attribute, | ||
| const char * | value | ||
| ) | [protected] |
Provide an attribute/value pair for a point. Attribute/value pairs are visible to the user when they are inspecting source metadata, and they are also often used by displays to determine how a point should be interpreted. Their meaning is entirely user-defined and they are not used internally by VisualCommander.
| key | The id of the point to provide an attribute for |
| attribute | The name of the attribute. Must not be null. Must be a null-terminated string. |
| value | the value for the attribute. Must not be null. Must be a null-terminated string. |
| void VCDataSource::define_point_dimensions | ( | int | key, |
| int | rows, | ||
| int | columns | ||
| ) | [protected] |
Provide dimension hints for a point. Dimension hints are often used by displays to set up expected sizes prior to the arrival of data. These dimensions are not binding- every value stored in the point could have different dimensions- but many displays perform poorly when points do not contain dimension hints or do not follow the provided dimensions.
Integer and Double data points have implicit dimension hints of 1x1.
| key | The id of the point to add hints for |
| rows | The number of rows the point is expected to have |
| columns | The number of columns the point is expected to have |
| bool VCDataSource::handle_command | ( | int | key, |
| const char * | path, | ||
| void * | data, | ||
| unsigned int | length, | ||
| const ds_date & | execute_time | ||
| ) | [protected, virtual] |
Called by run_commands_until_date() to handle a single command. The default implementation does nothing.
| key | The id of the command. |
| path | The path of the command. |
| data | A pointer to the raw data provided for the command. This data is in packed form, and must be unpacked prior to use; see the unpack_data() function. |
| length | The length of the data provided. |
| execute_time | The time scheduled for the execution of this command. |
| void VCDataSource::handle_messages | ( | const ds_date * | stop_date = NULL ) |
[protected] |
Cause the data source to handle network communication and check for incoming messages until the provided stop date. All other functions are called during a call to handle_messages. If the default run_source() implementation is used, this method is called automatically; if it is overridden, the provided implementation must be careful to call handle_messages() periodically.
| stop_date | A pointer to a wall-clock date. The call will block until a message has been handled, or this data arrives, whichever comes first. |
| void VCDataSource::increment_run | ( | ) | [protected] |
Increment the run number that is included with all data, indicating that all subsequent data is associated with a new run. Generally called from within an implementation of reset().
| bool VCDataSource::initialize | ( | ) | [protected, virtual] |
Handle plugin any plugin initialization. If the plugin will require configuration (or if wait_for_configuration() is true), this function should also call configuration_required() and provide a description of the required configuration.
| void VCDataSource::install_timer | ( | const char * | name, |
| double | period, | ||
| bool | repeat, | ||
| void(*)(VCDataSource *source, const char *name, void *context) | callback, | ||
| void * | context | ||
| ) | [protected] |
Install a timer callback. The callback will be called after a certain period, and may optionally repeat. Timers are named, and only one timer with a given name may exist at a time. Timers are fired only during calls to handle_message(). If the default run_source() implementation is used, messages are handled continuously; if the data source is calling handle_message(), be aware that gaps in handle_message() coverage may impact the accuracy of timers.
| name | The name of the timer. Will be provided as the second parameter of the callback when it is called. |
| period | The period of the timer, in seconds. |
| repeat | If this paramter is true, the timer will fire every period seconds. If not, it will fire after period seconds have elapsed and then remove itself. |
| callback | A pointer to the function that should be called when the timer fires. The function should take three parameters: a pointer to this data source, a pointer to the name of the timer, and a context pointer that is installed with the timer. |
| context | A user-defined context pointer, passed without modification to the callback function when it is called. |
| void VCDataSource::log_message | ( | VCLogSeverity_t | severity, |
| const char * | msg, | ||
| ... | |||
| ) | [protected] |
Print a log message to the console, including a prefix that identifies the data source. The message will also be sent to the client to possibly be displayed to the user.
| severity | The severity level of the message. One of
|
| msg | A printf-style format string. |
| ... | Arguments required by the format string. |
ds_dictionary *send_dict = new ds_dictionary(*data_dict);
| int VCDataSource::lookup_command | ( | const char * | path ) | [protected] |
Look up the id of a defined command, given its path.
| path | The path of the command to look up. Must not be null. |
| int VCDataSource::lookup_point | ( | const char * | path ) | [protected] |
Look up the id of a defined point, given its path.
| path | The path of the point to look up. Must not be null. |
| void VCDataSource::metadata_complete | ( | ) | [protected] |
Indicate that all metadata has been defined. The metadata will be published to clients and the storage manager, and the source will move into the VCDataSourceReady stage.
This function will throw an error if it is called when the stage is not VCDataSourceInitializing
| ds_date VCDataSource::next_command_execute_time | ( | ) | [protected] |
Retrieve the date of the next command scheduled for execution.
| bool VCDataSource::pause | ( | ) | [protected, virtual] |
Perform any actions necessary to pause the output of the source.
| void VCDataSource::remove_timer | ( | const char * | name ) | [protected] |
Remove a timer and prevent it from firing.
| name | The name of the timer to be removed. |
| bool VCDataSource::reset | ( | ) | [protected, virtual] |
Perform a soft reset of the source. This should involve incrementing the run number via a call to increment_run(). The source will move back to the Ready state after this call, and subsequently start again with another call to run().
| bool VCDataSource::resume | ( | ) | [protected, virtual] |
Perform any actions necessary to resume the output of the source.
| bool VCDataSource::run | ( | ) | [protected, virtual] |
Perform any steps necessary to start running the source- for instance, installing data acquisition timers. The default implementation does nothing.
| void VCDataSource::run_commands_until_date | ( | const ds_date & | stop_date ) | [protected] |
Cause the data source to iterate over all as-yet-unexecuted commands and call handle_command() for each one with an execute time less than or equal to the provided stop date
| stop_date | The latest date of a command that should be executed |
| void VCDataSource::run_completed | ( | ) | [protected] |
Indicate that the source has finished producing data for this run. The stage will be moved to VCDataSourceRunCompleted.
| void VCDataSource::run_source | ( | ) | [virtual] |
Subclasses may override this method to provide a custom run loop. If this method is overridden, the run loop must be sure to regularly call handle_messages() to ensure that the data source can send and receive data from clients and the server.
The default implementation of this method does a simple message-handling and blocking run loop, and also handles firing installed timers at appropriate intervals. Data sources that need to block on different external entities will probably need to provide a custom implementation.
| bool VCDataSource::run_subtask | ( | bool | dup_stdout, |
| bool | dup_stderr, | ||
| int * | input_fd, | ||
| int * | output_fd, | ||
| const char * | path, | ||
| const char * | args[] | ||
| ) | [protected] |
A convenience function for starting an external process and setting up pipes to read its output and write to its input.
| dup_stdout | true if the subprocess's standard output should be captured |
| dup_stderr | true if the subprocess's standard error should be captured |
| input_fd | A pointer to an integer in which the file descriptor used for writing to the process's input will be stored |
| output_fd | A pointer too an integer in which the file descriptor used for reading from the process's output will be stored |
| path | The path of the process to run |
| args | An array of null-terminated strings providing arguments for the process. The first argument must be the name of the process should run; the last element of the array must be NULL. |
| void VCDataSource::send_data | ( | const ds_date & | datestamp, |
| bool | no_broadcast = false |
||
| ) | [protected] |
Send all data that has been stored since the last call to send_data, and tag each data with the provided timestamp. This function has no effect if the data source is not currently in the VCDataSourceRunning state.
| datestamp | The time to be associated with the data that is being sent. |
| no_broadcast | An optional paramter, defaulting to false. If true, the data will not be sent to clients. Some data sources may bulk load data of various times when the initially start running; this flag is used for this purpose. See complete_historical_load() for more data. |
| void VCDataSource::set_point_as_unlogged | ( | int | key, |
| bool | unlogged | ||
| ) | [protected] |
Mark a point as unlogged- that is, its data will not be stored or cached, such that historical data cannot be retrieved.
| key | The id of the point to affect |
| unlogged | True if the point should not be logged; false (the default) if it should be logged and its data saved. |
| bool VCDataSource::setup_metadata | ( | ) | [protected, virtual] |
Define the points and commands that make up this source's data tree. Before returning from this function, metadata_complete() should be called.
| VCDataSourceState_t VCDataSource::stage | ( | ) | [protected] |
Retrieve the current stage for the data source.
| void VCDataSource::store_data | ( | int | index, |
| void * | data | ||
| ) | [protected] |
Provide data for a point. This function does not actually send out the data, or associate the data with a timestamp; see send_data(). If the data source is not currently in the VCDataSourceRunning state, this function will have no effect.
| index | The id of the point to set data for. |
| data | A pointer to the data to be set. Must be appropriate for the type of the data point. For instance, if the data point is of type sd_type_double, this parameter should be a pointer to a double. If the data point is of type sd_type_matrix, this paramter should be a pointer to a matrix |
| bool VCDataSource::terminate | ( | ) | [protected, virtual] |
Perform any cleanup that should happen when the data source is terminated. Terminated sources exit shortly thereafter.
| void VCDataSource::throw_error | ( | const char * | msg, |
| ... | |||
| ) | [protected] |
Cause the data source to enter the VCDataSourceError state, and print an error message to the console. The message will also be sent to clients to be displayed to the user.
| msg | A printf-style format string. |
| ... | Arguments required by the format string. |
ds_dictionary *send_dict = new ds_dictionary(*data_dict);
| bool VCDataSource::unpack_data | ( | void * | destination, |
| int | data_type, | ||
| void * | data, | ||
| unsigned int | length | ||
| ) | [protected] |
Unpack the raw data provided with a command into a usable location.
| destination | A pointer to the location where the unpacked data should go. For instance, if the data type is double, this parameter should point to valid, allocated space for a double. If the data type is matrix, this parameter should point to a valid ml_matrix object. |
| data_type | The data type for the data. |
| data | The raw data buffer to unpack. |
| length | The length of the raw data buffer. |
1.7.2