A filter writer must supply a generate_data: method, and can use the one in signal_filter as a template. A "compute_input_range!" method is required if the filter needs more (or less) time steps than the number requested in order to perform its calculations.
Signal_filter is not a true abstract class since it can be instantiated, but it's generate_data: method merely copies requested data from its signal_in to the requesting signal_data out object.
error Can be set in generate_data method to indicate an error condition in the filter.
signal_in Name of the upstream connection, ie, the name of a signal_data object. Typically set with "signal_in= [upstream_filter new_connection?]".
available_channels? Returns a list of ALL channels available to the filter (1 - N). This message is typically forwarded up the pipeline until someone can answer it: usually a reader.
compute_channels! Method sent by connection signal_data objects. Each connection can have a different set of requested channels. When a connection gets a channels=+-, it sends compute_channels! to its parent (the filter) so that the filter can examine ALL of its connections and make sure that its signal_in is generating all needed channels. This method should not normally be sent by the user.
compute_input_range! Internal method used by the filter to determine the range of time steps needed for a particular range requested by a connection. Most filters request the same range from their signal_in that the connection is requesting, but some filters (ie, low_pass) may need additional steps on either side of the requested range. This method should not normally be sent by the user.
connection? Return the name of the signal_data object at "connection_number". If connection_number < 1, it returns and empty string. If connection_number equals (no_connections + 1), a new_connection? is returned. If connection_number > (no_connections + 1), an empty_string is returned.
connection_number= argument Same as "@".
connection_number? Return the value of connection number set by "@" or "connection_number=".
connections? Returns a list of all the connection names.
connection_number= argument Same as "@".
does_not_understand? Messages not understood by the filter are passed to the signal_data connection at connection_number.
error= argument Set the error instance variable to argument. 0 is assumed to be no error.
error? Get the value of the error instance variable.
generate_data: start_packet end_packet start_index This method should NOT be called directly from the shell or another object. It is an internal method called during a request_data: from a connection. This function is implemented by the filter writer. Start_packet and end_packet are the packets (time- steps) needed by the requesting connection. start_index is the offset into the channel arrays where the filter should start filling data (it is computed by the connection (signal_data object) when it receives its request; by passing it to generate_data, we remove the need for the filter to recalculate it or send a message back to the connection to get it).
in_request_end? When a request for a time range is made by a connection, "request_data:" determines the range needed from signal_in (with "compute_input_range!"). "in_request_end" is saved as a private variable for use by "generate_data:", rather than requiring it to recompute.
in_request_start? When a request for a time range is made by a connection, "request_data:" determines the range
needed from signal_in (with "compute_input_range!"). "in_request_start" is saved as a private variable for use by "generate_data:", rather than requiring it to recompute.
new_connection? Creates a new signal_data object and puts its name at connection_number (no_connections + 1), increments no_connections, and returns the name of the new connection. Works the same as setting connection number to (no_connections + 1) and doing a "connection?".
no_connections? Returns the number of exisitng output connections on the filter.
recomputing_mtime? Before requesting data, the pipeline terminus is expected to send a recomputing_mtime? to its signal_in. This gets propagated all the way back up to the start of the pipeline. If any object in the pipeline has been modified, each object knows that it's cached data is no longer up to date, so the entire cache must be regenerated on the next "request_data:".
request_data:( start_time, end_time, start_index, requestor_name) This message is sent by the connection objects (signal_data). Specifying the time range needed, and the index into the signal_data channel caches. The requestor also sends its name so the filter knows which of its connections is requesting data. This should not be called directly from the shell or another object, but only through a connection.
request_end? Returns the end_time from the most recent "request_data:".
request_name? Returns the name of the last requesting object.
request_object? Returns the object pointer of last requesting object.
request_start? Returns the last start time requested by an object.
requestor= This is a "dummy" method in the filter (at least at present), and kind of a kludge. When a signal_data (a filter connection) is asked for its "available_channels?", it forwards the method to its parent. This method propagates back to a reader. However, some readers have multiple "kinds" of signal output, and each kind may have a different set of available channels. The reader has no way of knowing who sent such a message, so the signal_data is required to first send a "requestor=" in case the reader needs to differentiate between pipelines. The filter must accept this method as well, even though it does nothing with it
sample_rate? Returns the sample rate (in Hz) of the incoming data. It forwards this message to its signal_in and it gets propagted back up the pipeline until someone can answer it. signal_readers MUST respond with the actual sample rate of the data. Filters that decimate (or interpolate) should override this message, get the sample_rate from their signal_in, and return the decimated sample rate.
shell_request_data:( start_time, end_time) Same as request_data, except without the "index" and "requestor" arguments. However, this first sends a "recomputing_mtime?" to the connection at "connection_number" which makes sure the cache is up to date. It then sends a "request_data:" to that connection with itself as requestor so that the proper protocol is used. A subsequent output! will print that connection's data. This alleviates the user at the shell or script level from first having to get the name of the connection, and then sending a recomputing_mtime? and request_data: to that connection.
sig_in? Returns a pointer to a SIGNALTYPE data structure for the signal_in. This is used within "generate_data:" for direct and efficient access to the signal_in data without the overhead of messages. It is set by "request_data:" when it receives a request. When "generate_data:" is called, sig_in should contain all the data needed to compute the
output data.
sig_out? Returns a pointer to a SIGNALTYPE data structure for the signal_data connection that is requesting new data.. This is used within "generate_data:" for direct and efficient access to the signal_data without the overhead of messages. It is set by "request_data:" when it receives a request. The "generate_data:" method fills sig_out with the filtered data.
signal_in= signal_data_name Sets signal_in the the name of an existing signal_data object. Typically set with "signal_in= [upstream_filter new_connection?]".
signal_in? Returns the name of the signal_in object.