This class is available for the OPUS Blackboard API. The initial OPUS 2.0 release is described here
Constructors:
Command_bb( ) | |
~Command_bb( ) |
Methods:
post( ) | posts a copy of the Command entry argument on the blackboard |
erase( ) | locates and erases the Command object on the blackboard with the same label as the calling argument |
replace( ) | replaces the blackboard Command object with the same label as the first calling argument with a copy of the second argument |
search( ) | searches for a Command object on the blackboard with the same label as the first argument and executes it using any calling arguments in the first argument as additional calling arguments to the located Command object |
lock_entry( ) | no-op |
str( ) | gets the blackboard name |
test_driver( ) | runs the test driver |
Description
The command blackboard stores entries of function pointers and their associated calling arguments. The entries are Command objects which are indexed on the blackboard by their string label (each entry must have a unique label). This abstraction allows the event polling mechanism to call an arbitrary function each pass through the polling loop, then generate an event if the return value of the function indicates that it should do so. Complicated algorithms can be run as part of the polling process in this way.
Like other blackboards, the search method attempts to locate an entry on the blackboard with the same label as the Command object passed into the method. If a match is found, the execute method of the located Command object is called (if the search condition Command object has any calling arguments of its own, they are passed to the execute method of the located Command object as additional calling arguments for that object).
If the execute method returns true, the located Command object is cloned and pushed onto the vector supplied as the second argument. If the execute method returns false, nothing is added to the results vector. The search method returns the size of the results vector in any case.
Derived from
Example
#include <vector> #include <string> #include <iostream> #include "command.h" #include "command_bb.h" using namespace std; // The following function demonstrates a global function to be // placed on the Command Blackboard by an OAPI client. This simple // example dumps its arguments to cout, then returns true. bool foo(vector<string>& args) { for (int i = 0; i < args.size(); i++) cout << args[i] << endl; return(true); } // The following driver posts a command on the Command Blackboard, // then does a search for it which results in its execution. int main(int argc, char* argv[]) { string label("Foo Command"); // give the command a name string arg("/tmp"); // a command argument Command* com; com = new Command(label, foo); // create new Command that points // to foo() com->add_arg(arg); // add a single calling argument Command_bb com_bb; com_bb.post(com); // post Command on blackboard delete com; // no longer needed com = new Command(label); // create Command for search vector<string> results; // results vector // search returns size of results // vector if (com_bb.search(com, results)) { cout << "Command execution returns true." << endl; delete results[0]; // delete search result } else { cout << "Command not found or returned false." << endl; } delete com; // no longer needed return(0); }
See Also:
Command_bb::Command_bb - The Command_bb constructor.
Synopsis
Command_bb::Command_bb()
Description
This method constructs a Command_bb object.
Exceptions Thrown
Command_bb::~Command_bb - The Command_bb destructor.
Synopsis
Command_bb::~Command_bb()
Description
This method destroys the object. Each Command object on the blackboard is deleted, so care should be taken to prevent the object from going out of scope until it is no longer needed.
Exceptions Thrown
Command_bb::post - Post a copy of a Command object on the blackboard.
Synopsis
void Command_bb::post( const Entry* e) // I - Command object to post
Description
A copy of the Command object is constructed and posted to the blackboard. If a Command object already exists on the blackboard with the same Com_label value, posting fails and an exception is thrown.
Exceptions Thrown
Bad_val<Entry*> | - if argument is null; Bad_val.arg points to the calling argument |
Type<Entry*> | - if argument is not of type Command; Type.arg points to the calling argument |
Already<Entry*> | - if Command with same Com_label already exists; Already.arg points to the calling argument |
Example
bool foo(vector<string>&); Command_bb cbb; string label("COMMAND1"); Command* com = new Command(label, foo); cbb->post(com); delete com;
Command_bb::erase - Remove a Command entry from the blackboard.
Synopsis
void Command_bb::erase( const Entry* e) // I - pointer to a Command // object with a label // matching the one to // delete
Description
A search is made of the blackboard for a Command object with a Com_label value identical to the calling argument's. If found, the blackboard entry is deleted. If no match is found, an exception is thrown.
Exceptions Thrown
Bad_val<Entry*> | - if argument is null; Bad_val.arg points to the calling argument |
Type<Entry*> | - if argument is not of type Command; Type.arg points to the calling argument |
No_entry<Entry*> | - if no match to the argument's Com_label is found; No_entry.arg points to the calling argument |
Example
Command_bb cbb; string label("COMMAND1"); Command* com = new Command(label); // create new Command with label // matching the one to delete try { cbb.erase(com); // attempt to erase it } catch(No_entry<Entry*>) { // no such command cout << label << " was not found."; } delete com; // no longer needed
Command_bb::replace - Replace a Command object on the blackboard with another.
Synopsis
void Command_bb::replace( const Entry* old_ent, // I - Command object with // the same Com_label // as the one to be // replaced const Entry* new_ent) // I - Replacement Command // object
Description
An attempt is made to erase the Command object with the same Com_label as the first argument from the blackboard. If successful, a copy of the second argument is posted.
Exceptions Thrown
Bad_val<Entry*> | - if argument is null; Bad_val.arg points to the calling argument |
Type<Entry*> | - if argument is not of type Command; Type.arg points to the calling argument |
No_entry<Entry*> | - if no match to the argument's Com_label is found; No_entry.arg points to the calling argument |
Bad_val<Entry*> | - if argument is null; Bad_val.arg points to the calling argument |
Type<Entry*> | - if argument is not of type Command; Type.arg points to the calling argument |
Already<Entry*> | - if Command with same Com_label already exists; Already.arg points to the calling argument |
Example
bool foo(vector<string>&); Command_bb cbb; Command* old_com = new Command(old_label); // create new Command with // label matching the one // to delete Command* new_com = new Command(new_label, // create replacement foo); // Command try { cbb.replace(old_com, new_com); // erase old; post new } catch(...) { cout << "Replacement failed." << endl; } delete old_com; // no longer needed delete new_com; // no longer needed
Command_bb::search - Search for and execute a Command on the blackboard.
Synopsis
int Command_bb::search( const Entry* e, // I - a Command object // with the same // Com_label as // the search target vector<Entry*>& results) // I/O - results vector const
Description
A search for a Command object with the same Com_label as the first argument is made on the blackboard. If a match is found, the execute method of the located Command object is called (if the search condition Command object has any calling arguments of its own, they are passed to the execute method of the located Command object as additional calling arguments for that object).
If the execute method returns true, the located Command object is cloned and pushed onto the vector supplied as the second argument. If the execute method returns false, nothing is added to the results vector.
Returns
The size of the results vector just prior to returning.
Exceptions Thrown
Bad_val<Entry*> | - if argument is null; Bad_val.arg points to the calling argument |
Type<Entry*> | - if first argument is not of type Command; Type.arg points to the calling argument |
No_entry<Entry*> | - if Command not found on Command Blackboard; No_entry.arg points to the calling argument |
Example
Command_bb cbb; string label("COMMAND1"); Command* com = new Command(label); // create new Command with // label we are looking for vector<Entry*> results; // results vector try { if(cbb.search(com, results)) { cout << "Command execution returns" " true." << endl; delete results[0]; // delete result } } catch(...) { cout << "Search failed." << endl; } delete com; // no longer needed
Command_bb::lock_entry - none
Synopsis
Opus_lock* Command_bb::lock_entry( const Entry* e)
Description
Creates a Null_lock object off the heap and returns a pointer to it. The client should delete the object when it is no longer needed.
Returns
A pointer to a Null_lock object allocated off the heap.
Exceptions Thrown
Command_bb::str - Get the blackboard name.
Synopsis
string Command_bb::str() const
Description
This method returns a string describing the blackboard.
Returns
string containing the blackboard name
Exceptions Thrown
Example
Command_bb cbb; cout << "About to post command on " << cbb.str() << endl;
Command_bb::test_driver - Test the blackboard implementation.
Synopsis
bool Command_bb::test_driver()
Description
This method exercises the blackboard methods. Diagnostic output is sent to cerr. If all of the tests pass, this method returns true. Otherwise, it returns false. All exceptions generated during the test are caught and reported.
Returns
true - if all tests pass;false - if one or more of the tests fail
Exceptions Thrown
Example
Command_bb cbb; cout << "Running the Command Blackboard test driver." << endl; if (cbb.test_driver()) cout << "Pass." << endl; else cout << "Fail." << endl;
Copyright © 1997-2000 The Association of Universities for
Research in Astronomy, Inc. All Rights Reserved.
For more information, contact opushelp@stsci.edu
Last modified: 25 April 2000