60.1. Introduction

The versatility of the filter framework makes it likely that the user will want to run a filter in an online setting. The mechanism that allows the launching of any filter in the online settiing is through the ReadoutCallouts.tcl script that is run by the ReadoutGUI. Within this script one can capture the output of a filter program to print to either the terminal or the ReadoutGUI's OutputWindow. Doing so will result in the output of the filter program being treated as just a stream of text. With actually less effort in the ReadoutCallouts.tcl script, the user can enable their filter program's output to be formatted or even initiate TCL command executions in the interpreter of the ReadoutGUI. Why would you want this feature? Consider, for example, wanting a filter program to output warning messages that would be highlighted so as to stand out to the user. In more advanced cases, one might want to execute commands in the tcl interpreter that spawned it given some observed condition in the data stream. The most obvious example of this is a filter requesting for the run to end because it observed some bizarre data. Accomplishing any of these things is made possible with the actions library.

The actions library provides a very simple mechanism for accomplishing these tasks. It is implemented as two pieces, a set of C++ functions and a tcl package. The idea is that the filter code seeking to do something of the sort already described above will call one of the functions in the Actions namespace. Then when the user writes the code in the ReadoutCallouts.tcl script to launch the filter, they will do so by launching it as a pipeline. In addition, they will register the actions::onReadable handler for when the pipeline is readable. That's it! The result will be extended capabilities of their filter program when run in the environment of the ReadoutGUI.

Here is the list of C++ methods that are supported for use in a filter program:

• void Error(std::string message);
• void Log(std::string message);
• void Warning(std::string message);
• void Output(std::string message);
• void Debug(std::string message);
• void TCLCommand(std::string message);
• void BeginRun();
• void PauseRun();
• void ResumeRun();
• void EndRun(bool propagate = true);

It is worthwhile to mention that using these C++ functions in a filter program does not restrict the program to run only in the context of the ReadoutGUI. These function merely format the message and output it on stderr.