This class is available for the OPUS Blackboard API. The initial OPUS 2.0 release is described here

Constructors:

Event( )
~Event( )

Methods:

clone( )	returns a copy of the object
pstat_mesg( )	gets the PSTAT blackboard status field to be applied for this event
add_callback( )	adds the function to the list of callbacks
process( )	calls the registered callback function or Opus_env::close_event with Opus_env::IGNORE_EVENT
num_entries( )	gets the count of triggering entries in the event
trigger_name( )	gets the trigger name
begin( )	returns an iterator pointing to the start of the triggers list
end( )	returns an iterator pointing to one past the last entry in the triggers list
add_entry( )	adds a copy of an entry to the triggers list
replace_entry( )	replaces an item in the triggers list
remove_entry( )	removes an item from the triggers list
find_entry( )	searches for a matching entry in the triggers list
str( )	gets the associated blackboard name
post( )	posts an entry on the associated blackboard
erase( )	removes an entry from the associate blackboard
replace( )	replaces one entry with another on the associated blackboard
search( )	searches for a matching entry on the associated blackboard
lock_entry( )	locks an entry on the associated blackboard
lock_list( )	locks a set of entries in the triggers list on the associated blackboard
test_driver( )	runs the test driver

Description

The Event class is the base class for all OPUS event objects. Events occur on a blackboard whenever polling with a trigger condition produces one or more matching entries. Once an event occurs, calling the process method results in an indirect call to the registered callback function for that event type. Clients implement these callback functions to perform whatever steps are necessary to process the event. Callbacks are registered using the static method add_callback. Any event without a registered callback has a default process method that does nothing but call Opus_env::close_event with Opus_env::IGNORE_EVENT. Each event derivative offers a full interface to the blackboard on which the event occurred in addition to methods useful for manipulating the entries responsible for the event.

Derived from

Blackboard

Example

  
    #include <iostream>
    #include "opus_env.h"
    #include "opus_lock.h"
    #include "event.h"
    #include "halt_event.h"
    #include "reinit_event.h"
    #include "file_event.h"
    #include "osf_event.h"
    #include "time_event.h"
    #include "msg.h"
    #include "opus_exceptions.h"
  
    using namespace std;
  
    // event handlers
    void time_event_process(const string&, Event*, const Opus_env&);
    void halt_event_process(const string&, Event*, const Opus_env&);
    void file_event_process(const string&, Event*, const Opus_env&);
    void cmd_event_process(const string&, Event*, const Opus_env&);
    void reinit_event_process(const string&, Event*, const Opus_env&);
    void osf_event_process(const string&, Event*, const Opus_env&);
  
    // define an object to throw for HALT events
    class Done { };
  
    // The following example is a simple shell application that uses
    // the OAPI. It initializes OPUS, then begins polling. Each event
    // handler prints out the Entry's that triggered it. A HALT event
    // terminates the application.
    int main(int argc, char* argv[])
    {
       Msg m;
       m.set_rpt_level(Msg::ALL);
  
       Opus_env opus(argc, argv);
       if (!opus.is_initialized()) {
          m << sev(Msg::F) << "Failed to construct Opus_env." << endm;
          exit(-1);
       }
  
       // register event process callbacks
       Halt_event::add_callback(halt_event_process);
       Reinit_event::add_callback(reinit_event_process);
       File_event::add_callback(file_event_process);
       Osf_event::add_callback(osf_event_process);
       Time_event::add_callback(time_event_process);
  
       try {
          while (true) {
             Event* e = opus.poll();
             try {
                e->process(opus);
             }
             catch(Done) {
                delete e;
                break;
             }
             delete e;
          }
       }
       catch(Opus_exceptions& oe) {
          m << sev(Msg::F) << type(Msg::SEVERE) <<
             "An OPUS exception was thrown." << endl << oe.which() << endl
            << oe.str() << endm;
          return(-1);
       }
       catch(...) {
          m << sev(Msg::F) << type(Msg::SEVERE) <<
          "A non-OAPI exception was thrown." << endm;
          return(-1);
       }
       return(0);
    }
  
    void time_event_process(
                            const string& title,
                            Event* evt,
                            const Opus_env& opus)
    {
       Msg m;
       m << "Processing Time_event." << endl;
    }
  
    void file_event_process(
                            const string& title,
                            Event* evt,
                            const Opus_env& opus)
    {
       Msg m;
       m << "Processing File_event. Entry's are: " << endl;
       for (Event::const_iterator vi = evt->begin(); vi != evt->end(); vi++) 
          m << (*vi)->str() << endl;
       m << endm;
  
       // lock Event Entry's
       vector<Opus_lock*> locks;
       evt->lock_list(locks);
       
       // should handle any Entry's that failed to lock here-- skipping
       // for sample code...
  
       // close out the event
       opus.close_event("FILE_SUCCESS", evt);
  
       // release locks
       int i;
       while(i = locks.size()) {
          delete locks[--i];
          locks.pop_back();
       }
    }
  
    void osf_event_process(
                           const string& title,
                           Event* evt,
                           const Opus_env& opus)
    {
       Msg m;
       m << "Processing Osf_event. Entry's are: " << endl;
       for (Event::const_iterator vi = evt->begin(); vi != evt->end(); vi++)
          m << (*vi)->str() << endl;
       m << endm;
  
       // lock Event Entry's
       vector<Opus_lock*> locks;
       evt->lock_list(locks);
       
       // should handle any Entry's that failed to lock here-- skipping
       // for sample code...
  
       // close out the event
       opus.close_event("OSF_SUCCESS", evt);
  
       // release locks
       int i;
       while(i = locks.size()) {
          delete locks[--i];
          locks.pop_back();
       }
    }
  
    void halt_event_process(
                            const string& title,
                            Event* evt,
                            const Opus_env& opus)
    {
       Msg m;
       m << "HALT command received. Terminating." << endm;
       throw done;
    }
  
    void reinit_event_process(
                              const string& title,
                              Event* evt,
                              const Opus_env& opus)
    {
       Msg m;
       m << "REINIT command received." << endm;
       opus.reinit();
    }
  

See Also:

• Time_event
• Halt_event
• File_event
• Command_event
• Reinit_event
• Osf_event
• Opus_env
• "OPUS API Blackboard and Support Classes Design Document"

Event::Event - The Event constructor.

Synopsis

Event::Event(
             Blackboard* bbrd) // I - blackboard associated with the event

Event::Event(
             Blackboard* bbrd,        // I - blackboard associated with the
                                      //     event
             const string& s,         // I - trigger name
             const vector<Entry*>& v) // I - the list of entries that
                                      //     triggered the event

Description

Constructors are provided for creating an Event object without any triggering entries (to be used as a factory object), and for creating an object in response to an actual event.

Exceptions Thrown

none

Event::~Event - The Event destructor.

Synopsis

Event::~Event() 

Description

The destructor deletes any entries contained by it.

Exceptions Thrown

none

Event::clone - Create a copy of this object.

Synopsis

Event* Event::clone() const

Event* Event::clone(
                    const string& s,         // I - Trigger name
                    const vector<Entry*>& v) // I - the list of triggering
                                             //     entries
                    const

Description

A new Event object is constructed off the heap and initialized according to the version of this method used. The two clone methods allow for creation of an Event object when no event has occurred (for use as a factory object) and in response to an actual event. The client should delete the new object when it is no longer needed.

Returns

    A pointer to a new Event object initialized using the corresponding
    constructor.

Exceptions Thrown

none

Event::pstat_mesg - Get the PSTAT status message update for this event.

Synopsis

Proc_stat* Event::pstat_mesg() const

Description

The base class implementation of this method always returns 0 (ie., no PSTAT status update is available for the event).

Returns

    0

Exceptions Thrown

none

Event::process - Process the event.

Synopsis

void Event::process(
                    const Opus_env& oenv) // I - Opus_env object reference

Description

This method calls the callback function, if it is specified, with the trigger name, a reference to the Opus_env object, and a pointer to the event itself. If no callback is registered, Opus_env::close_event is called with Opus_env::IGNORE_EVENT.

Exceptions Thrown

[any exceptions thrown by the callback function]

Bad_val<Event*>	- if the Event argument is NULL; Bad_val.arg contains the calling argument
Bad_val<string>	- if the status is not found; Bad_val.arg contains the calling argument
Exec<vector<Event::iterator>>	- if a failure occurs for any entry; Exec.arg contains a vector of iterators that point to the failed items

Event::str - Get the blackboard name associated with the event.

Synopsis

string Event::str() const

Description

This method returns the result of the str method called on the associated blackboard.

Returns

    string containing the associated blackboard's name.

Exceptions Thrown

none

Event::post - Post an entry on the associated blackboard.

Synopsis

void Event::post(
                 const Entry* e) // I - Entry object to post

Description

This method is a wrapper for the post method of the associated blackboard.

Exceptions Thrown

[any exceptions thrown by the blackboard's post method]

Event::erase - Erase an entry on the associated blackboard.

Synopsis

void Event::erase(
                  const Entry* e) // I - Entry object to erase

Description

This method is a wrapper for the erase method of the associated blackboard.

Exceptions Thrown

[any exceptions thrown by the blackboard's erase method]

Event::replace - Replace an entry on the associated blackboard with another.

Synopsis

void Event::replace(
                    const Entry* old_ent, // I - Entry object to replace
                    const Entry* new_ent) // I - replacement Entry object

Description

This method is a wrapper for the replace method of the associated blackboard.

Exceptions Thrown

[any exceptions thrown by the blackboard's replace method]

Event::search - Search for an entry on the associated blackboard.

Synopsis

int Event::search(
                  const Entry* cond,   // I - entry to search for
                  vector<Entry*>& res) // O - vector to hold matches
                  const

Description

This method is a wrapper for the search method of the associated blackboard.

Returns

    The number of matching entries on the associated blackboard.

Exceptions Thrown

[any exceptions thrown by the blackboard's search method]

Event::lock_entry - Lock an entry on the associated blackboard.

Synopsis

Opus_lock* Event::lock_entry(
                             const Entry* e) // I - entry to lock

Description

This method is a wrapper for the lock_entry method of the associated blackboard.

Returns

    A pointer to an Opus_lock object for the entry.

Exceptions Thrown

[any exceptions thrown by the blackboard's lock_entry method]

Event::begin - Get an iterator that points to the beginning of the triggers list.

Synopsis

Event::iterator Event::begin()

Event::const_iterator Event::begin() const

Description

An iterator initialized with the beginning of the triggering entries list is created and returned to the caller. Be aware that future calls to other methods (e.g., remove_entry) might invalidate the iterator returned by this method.

Returns

    An iterator that points to the beginning of the triggers list.

Exceptions Thrown

none

Event::end - Get an iterator that points to one past the end of the triggers list.

Synopsis

Event::iterator Event::end()

Event::const_iterator Event::end() const

Description

An iterator initialized with one past the end of the triggering entries list is created and returned to the caller. Be aware that future calls to other methods (e.g., remove_entry) might invalidate the iterator returned by this method.

Returns

    An iterator that points to one past the end of the triggers list.

Exceptions Thrown

none

Event::add_callback - Register a callback function for the event.

Synopsis

void Event::add_callback(
                         void (*pf)(const string&, Event*,
                                    const Opus_env&)) // I - pointer to
                                                      //     callback
                                                      //     function

Description

This method takes a function pointer that will serve as a callback function for all events of this type. The callback function foo must have a signature and return type of

     void foo(const string&, Event*, const Opus_env&) 

Exceptions Thrown

none

Event::add_entry - Add an Entry object to the triggering entries list.

Synopsis

void Event::add_entry(
                      const Entry* e) // I - entry to copy and add to list
                                      //     of triggering entries

Description

This method places a copy of the supplied entry into the list of entries that triggered the event.

Exceptions Thrown

none

Event::replace_entry - Replace an entry in the triggering entries list with another.

Synopsis

void Event::replace_entry(
                          const Entry* old_ent, // I - Entry to replace
                          const Entry* new_ent) // I - replacement Entry

Description

This method replaces the indicated Entry object in the list of triggering entries with a copy of the other Entry object. However, the change is not applied to the associated blackboard.

Exceptions Thrown

No_entry<Entry*>

- if the indicated entry is not found; No_entry.arg points to the entry to be replaced

Event::remove_entry - Remove an Entry object from the triggers list.

Synopsis

void Event::remove_entry(
                         const Entry* e) // I - Entry to remove from list

Description

The indicated Entry object is deleted from the triggering entries list, but is not removed from the associated blackboard.

Exceptions Thrown

No_entry<Entry*>

- if the entry is not found; No_entry.arg points to the entry to be removed

Event::find_entry - Locate an entry in the triggering entries list.

Synopsis

Event::iterator Event::find_entry(
                                  const Entry* e) // I - entry to locate

Event::const_iterator Event::find_entry(
                                        const Entry* e) // I - Entry to locate
                                        const

Description

A match to the supplied entry is searched for in the triggering entries list. If it is found, an iterator pointing to the entry is returned. If the entry is not found, the returned iterator will to one past the last entry on the list.

Returns

    An iterator initialized with the located Entry or one past the last
    entry on the list if no match is found.

Exceptions Thrown

none

Event::num_entries - Get the total number of entries that triggered this event.

Synopsis

int Event::num_entries(void) const

Description

The method returns the number of Entry objects stored on the triggering entries list. This value will include any modifications done to the list.

Returns

    The number of entries on the triggering entries list.

Exceptions Thrown

none

Event::trigger_name - Get the trigger name associated with this event.

Synopsis

string Event::trigger_name() const

Description

The name of the trigger that created this event is returned.

Returns

    string containing trigger name

Exceptions Thrown

none

Event::lock_list - Lock each entry in the triggers list on the associated blackboard.

Synopsis

void Event::lock_list(
                      vector<Opus_lock*>& locks) // O - container for the
                                                 //     entry locks

void Event::lock_list(
                      vector<Opus_lock*>& locks, // O - container for the
                                                 //     entry locks
                      iterator ei)               // I - single entry to lock

void Event::lock_list(
                      vector<Opus_lock*>& locks, // O - container for the 
                                                 //     entry locks
                      iterator first,            // I - first entry to lock
                      iterator xlast)            // I - one past the last
                                                 //     entry to lock

Description

The lock_entry method on the associated blackboard is called for each Entry object in the triggers list, or for the range of object indicated by the forms of this method that take iterator arguments. If a lock is obtained, a pointer to the Opus_lock object is placed in the supplied vector. If a lock attempts fails, a zero is placed in the vector instead.

Exceptions Thrown

none

Event::test_driver - The Event class test driver.

Synopsis

bool Event::test_driver() 

Description

The base class test driver does nothing except return true.

Returns

    true

Exceptions Thrown

none

For more information, contact opushelp@stsci.edu

Last modified: 25 April 2000