For the most part, users do not interact with the signal_data object, but signal pipeline objects do (ie, signal_filters & signal_readers). The reader- or filter- writer must have an understanding of the signal_data's internal SIGNALTYPE structure (in signal_data.h) as well as the messages that follow. Examples of manipulating the object can be found in the files: signal_scale_filter.cls, signal_file_reader.cls, as well as other signal_* classes.
parent The name of an object that is generating the signal_data object's time-steps (usually a signal_reader, signal_filter, or signal_gen).
query_channel Which channel to use for subsequent queries.
query_index The data array index for subsequent queries.
query_packet The packet number for subsequent queries.
static_data Sometimes you may want to use a signal_data to store a range of data but not regenerate if its parent is modified. Setting static_data to non-zero prevents it from resetting (clearing) its cache during a recomputing_mtime?.
available_channels? Returns an ordered list (1 - N) of all the channel number available from this object. The message is forwarded up the pipeline until someone can answer it (usually a signal_reader which knows how many channels it can produce).
channels+ channel_list Add the channels in channel_list to the signal_data's channels.
channels- channel_list Remove the channels in channel_list from the signal_data's channels.
channels=channel_list Set the signal_data's channels to "channel_list".
data_array_size? Get the size of the array of channel-data pointers. Used internally.
channels? Return an ordered list of the channels in the object.
does_not_understand Forwards all messages it does not understand to its parent, if one exists.
end_index? Returns the array index of the last valid time-step in the cache. Returns -1 if no valid data in cache.
end_packet? Returns the packet number of the last valid time- step in the cache. Returns -1 if no valid data in cache.
label? Returns the channel label string (if one exists) for the query_channel.
labels? Returns an ordered list of the channel labels.
labels_ptr? Returns a (char **) to the array of pointers to labels. Should only be used from within a .cls file.
no_channels? Returns the number of channels in the object.
no_packets? Returns the number of valid time-steps in the cache.
object? Returns the object-name (if one exists) representing the query_channel.
objects? Returns a list of object names for the channels.
objects_ptr? Returns a (char **) to the array of pointers to object names. Should only be used from within a .cls file.
output! Prints out information on the object and ALL data for all valid time-steps on a channel by channel basis. This can be quite a large output for many time-steps and is useful primarily for debugging.
parent= parent_name Set the object's parent to "parent_name". All requests for data and all messages that are not understood, are forwarded to the parent. signal_filters, and signal_readers, when they create a new connection, set the parent of the created signal_data to themselves.
parent? Get the name of the parent object.
query_channel= channel_number Set the query_channel to "channel_number". Subsequent "label?", "object?", etc messages refer to this variable. Same as "@".
query_channel? Get the value of the query_channel.
query_index= value Set the query_index to "value". At present, no other messages refer to the query_index. In future, it will be used in conjunction with the query_channel to get specifc data values from a channel's data_array via the shell or script.
query_index? Get the value of the query_index.
query_packet= value Set the query_packet to "value". At present, no other messages refer to the query_packet. In future, it will be used in conjunction with the query_channel to get specifc data values from a channel's data_array via the shell or script.
query_packet? Get the value of the query_packet.
realloc_cache: ( new_cache_size) Typically only called by the object itself either when it hasn't yet allocated its cache, or when it receives a "request_data:" for more time-steps than it has cache space.
recomputing_mtime? Returns the maximum mtime of itself and all upstream pipeline elements. If an upstream element has a higher mtime, the signal_data knows that its cache may not be accurate, so it "resets" its cache (basically clears it), so that a subsequent "request_data:" will know enough to regenerate the cache. This message should ALWAYS be sent before a "request_data:" to assure the integrity of cached data (filter objects automatically do this). If you are writing a class that accepts signal_data, make sure you precede your request_data: with this message.
request_data: ( start_time, end_time [, optional_name]) Fills the signal_data's cache, for all channels in it's channel list, with the time-steps from start_time to end_time (inclusive). Internally, the signal_data object deals with packet-numbers, so the times are converted to packet numbers by: packet_num = (int)((time / sample_rate) + 0.5). (ie, the nearest packet number). The sample rate of the incoming data has been obtained from the parent. Negative times are not allowed, and end_time must be >= start_time. When this call returns successfully, the data requested is guaranteed to be in the signal_data's SIGNALTYPE data_arrays and can be accessed directly (from the caller's C-code) in the structure. This message is forwarded to the parent (a filter or reader) who actually fills the data arrays. The optional_name field should always be the name of the calling object. It is made optional so that direct calls from the shell or from a lymb script do not have to supply a name. Objects that use signal_data should always include this field. The signal_data object uses it to keep track of channels=+- messages sent from multiple objects sharing a single connection.
reset_cache! An internal message used to reset the cache pointers to indicate no valid data in the cache. Should not typically be called by the user. (See recomputing_mtime?).
sig_struct? Get a pointer to the SIGNALTYPE structure. This structure provides direct access to the data from C-code rather than through lymb messages. This should not be called from the shell or script
level.
start_index? Get the index of the first valid time-step in the data arrays. If no valid data exists in the cache, -1 is returned.
start_packet? Get the packet number of the first valid time-step in the data arrays. If no valid data exists in the cache, -1 is returned.
static_data_off! Turn static_data mode off - data will subsequently be generated normally, and reset_cache! will be sent (if needed) during a recomputing_mtime?
static_data_on! Turn on static_data mode. A reset_cache! will not be sent during a recomputing_mtime?, even if the parent has been modified, keeping the cached data intact. During this mode, data that has not yet been cached can still be requested, and will be generated by a call to the parent. The user, when first filling a static signal_data, should call "static_data_off!", then generate the data with "recomputing_mtime?" and "request_data:" in the usual manner. Once the parent has generated the data, the user should call "static_data_on!" to "freeze" that data in the cache.