[OPUS]

Relative_time_bb - A blackboard for marking elapsed times.


Availability:

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

Constructors:
Relative_time_bb( )
~Relative_time_bb( )

Methods:
post( ) no-op
erase( ) no-op
replace( ) no-op
search( ) check if offset + ref. time less than current time
lock_entry( ) returns null lock
str( ) get blackboard name
new_time( ) create new time entry with Delta_time
test_driver( ) test implementation

Description

The purpose of this blackboard is to determine whether or not a time interval has elapsed. The search method reads the time interval from the Delta_time Field of the Time_entry calling argument, and adds it to the last referenced elapsed time. If the system clock indicates that the time has passed, the Time_entry is copied into the results vector to indicate a successful search. If the time is in the future, the search method returns as if the the search was unsuccessful.

Note: because the reference time used as the basis for the Delta_time offset is stored by the blackboard, any instance of a Relative Time Blackboard can support only a single Time_entry object.

Derived from

Blackboard

Example

  
    #include <iostream>
    #include <vector>
    #include "relative_time_bb.h"
    #include "entry.h"
    #include "time_entry.h"
  
    using namespace std;
  
    // The following example uses the Relative Time Blackboard as a
    // one hour timer.
    int main(int argc, char* argv[])
    {
       Relative_time_bb rtbb;
       Time_entry* t_ent = rtbb.new_time("000:01:00:00");
                                              // one hour offset
                                              // time entry
  
       vector<Entry*> results;                // results vector
       while(true) {
          if (abb.search(t_ent, results)) {   // 1 hour has passed
             cout << "It's time!" << endl;
             delete results[0];               // delete result
             break;
          } else {
             sleep(60);                       // wait before testing
          }
       }
       delete t_ent;                          // delete search condition
  
       return(0);
    }
  

See Also:


Relative_time_bb::Relative_time_bb - The Relative_time_bb constructor.

Synopsis


Relative_time_bb::Relative_time_bb()

Description

This method xonstructs an instance of the relative time blackboard.

Exceptions Thrown

none


Relative_time_bb::~Relative_time_bb - The Relative_time_bb destructor.

Synopsis


Relative_time_bb::~Relative_time_bb()

Description

This method destroys the object.

Exceptions Thrown

none


Relative_time_bb::post - Post a copy of a Time_entry object on the blackboard.

Synopsis


void Relative_time_bb::post(
                            const Entry* e)

Description

This method performs no useful function. A diagnostic message indicating that this method is a no-op is reported.

Exceptions Thrown

none


Relative_time_bb::erase - Erase a Time_entry object on the blackboard.

Synopsis


void Relative_time_bb::erase(
                             const Entry* e)

Description

This method performs no useful function. A diagnostic message indicating that this method is a no-op is reported.

Exceptions Thrown

none


Relative_time_bb::replace - Replace a Time_entry object on the blackboard with another.

Synopsis


void Relative_time_bb::replace(
                               const Entry* old_ent,
                               const Entry* new_ent)

Description

This method performs no useful function. A diagnostic message indicating that this method is a no-op is reported.

Exceptions Thrown

none


Relative_time_bb::search - Compare the current system time with the offset in the search condition plus a reference time.

Synopsis


int Relative_time_bb::search(
                            const Entry* e,       // I - Time_entry with
                                                  //     Delta_time
                            vector<Entry*>& res)  // I - results vector
                            const

Description

A comparison is made between the current system time and the offset embedded in the first argument added to a reference time stored in the blackboard object. If the Time_entry offset plus reference time is in the past, the reference time is updated with the sum and the Time_entry argument is copied and pushed onto the vector second argument. This copy is allocated off the heap with new and should be deleted by the caller once the object is no longer needed.

Returns

    The size of the vector second argument after the time test is

performed.

Exceptions Thrown

Bad_val<Entry*> - if the first argument is null; Bad_val.arg contains the calling argument
Type<Entry*> - if the first argument is not of type Time_entry; Type.arg contains the calling argument

Example

  
    Relative_time_bb rtbb;
    Time_entry* t_ent = rtbb.new_time("001:00:00:00"); // create time
                                                       // offset of 24 h.
  
    vector<Entry*> results;                            // results vector
    while (!rtbb.search(t_ent, results)) sleep(300);   // loop for 24 hours
  
    delete results[0];                                 // delete result
    delete t_ent;                                      // delete search
                                                       // condition
  


Relative_time_bb::new_time - Create a new Time_entry object containing a Delta_time field.

Synopsis


Time_entry* Relative_time_bb::new_time(
                                       const time_t t) // I - offset in
                                       const           //     seconds

Time_entry* Relative_time_bb::new_time(
                                       const string& t) // I - time
                                       const            //     string

Description

This method creates a new Time_entry object containing a Delta_time object for use with this blackboard. If a string argument is provided, it must be in the format DDD:HH:MM:SS or HH:MM:SS where DDD is the number of days, HH is the number of hours [0-23], MM is the number of minutes [0-59], and SS is the number of seconds[0-61].

Returns

    A pointer to the new Time_entry object.

Exceptions Thrown

Bad_val<string> - if the time string is invalid; Bad_val.arg contains the calling argument

Example

  
    Relative_time_bb rtbb;
    Time_entry* t_ent = rtbb.new_time(300); // 300 second offset
  


Relative_time_bb::lock_entry - Place a lock on a Time_entry object on the blackboard.

Synopsis


Opus_lock* Relative_time_bb::lock_entry(
                                        const Entry* ce) // I - entry to 
                                                         //     lock

Description

This method creates an Null_lock object. The returned object is allocated off the heap, and should be deleted by the client when it is no longer needed.

Returns

    Null_lock object allocated off the heap.

Exceptions Thrown

none


Relative_time_bb::str - Get the blackboard name.

Synopsis


string Relative_time_bb::str() const

Description

This method returns a string describing the blackboard.

Returns

    string containing the blackboard name

Exceptions Thrown

none

Example

  
    Relative_time_bb rtbb;
    cout << "The relative time blackboard name is: " << rtbb.str() << endl;
  


Relative_time_bb::test_driver - Test the blackboard implementation.

Synopsis


bool Relative_time_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

none

Example

  
    Relative_time_bb rtbb;
    cout << "Running the Relative Time Blackboard test driver." << endl;
    if (rtbb.test_driver()) cout << "Pass." << endl;
    else                    cout << "Fail." << endl;
  

OPUS API index · STScI Home Page · Search · Topics · Index

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