A package that allows output from programs run as a pipeline in ReadoutCallouts.tcl to be formatted in the OutputWindow or interpreted as commands.
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 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.
The user should be aware that mixing naked calls to output on std::cerr (or stderr) with Actions package calls is strongly discouraged. Instead, if the user is to make use of the Actions package, he/she should commit to using it for all of his/her output needs. The reason for this is that the Actions package launches a separate thread from which it will output to std::cerr. If the user chooses to output on the main thread by explicit calls to std::cerr and then also uses the Actions package, there will be no gaurantee that the integrity of the messages is kept. The reason for this is that the std::cerr object will be accessed from multiple threads without synchronization. The situation is called a data race, and the C++ standard says undefined behavior will follow.