[OPUS]

Halt_event - An event object created in response to a HALT command issued on the application's PSTAT


Availability:

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

Constructors:
Halt_event( )
~Halt_event( )

Methods:
clone( ) returns a copy of this object and sets the event trigger name and triggering entries
add_callback( ) assigns a callback function for this event type
process( ) calls Opus_env::close_event with Opus_env::IGNORE_EVENT if no callback is registered, // otherwise it calls the callback function
pstat_mesg( ) gets the Proc_stat object with which the process' PSTAT status field can be updated to indicate this event has occurred

Description

This type of Event object is created when polling on the PSTAT blackboard detects the command Proc_cmd::PSTAT_HALT_COMMAND in the application's PSTAT Proc_cmd field. The client must register a callback function for this event type in order to process it (by default, the process method calls Opus_env::close_event with Opus_env::IGNORE_EVENT). A callback function foo must have a signature and return type of

     void foo(const string&, Event*, const Opus_env&) 
This function will be passed the trigger name as the first argument, a pointer to this event object as the second the first argument, a pointer to this event object as the second argument, and a reference to the process' Opus_env object as the third argument.

Derived from

Event

See Also:


Halt_event::Halt_event - The Halt_event constructor.

Synopsis


Halt_event::Halt_event(
                       Blackboard* bbrd) // I - pointer to PSTAT
                                         //     blackboard

Halt_event::Halt_event(
                       Blackboard* bbrd,        // I - pointer to PSTAT
                                                //     blackboard
                       const string& s,         // I - Trigger name
                       const vector<Entry*>& v) // I - applications's PSTAT

Description

These methods create either a Halt_event object to be used as a factory or in response to an actual event. In the former case, only the blackboard on which this event occurs need be specified-- the object can then be used to create clones whenever a real event occurs. In the case of a real event, the trigger name and the vector of entry objects that are responsible for the event also are specified.

Warning: no checks are made that the correct blackboard type and entry types are used as calling arguments.

Exceptions Thrown

none


Halt_event::~Halt_event - The Halt_event destructor.

Synopsis


Halt_event::~Halt_event()

Description

This method destroys the object.

Exceptions Thrown

none


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

Synopsis


Event* Halt_event::clone() const

Event* Halt_event::clone(
                         const string& s,         // I - Trigger name
                         const vector<Entry*>& v) // I - triggers
                         const

Description

These methods create a new Halt_event object off the heap using the constructor with the same signature. The caller should delete the new object when it is no longer needed.

Returns

    A pointer to the new Halt_event object.

Exceptions Thrown

none


Halt_event::pstat_mesg - Get the Proc_stat object for updating the application's PSTAT status field.

Synopsis


Proc_stat* Halt_event::pstat_mesg() const

Description

This method returns a Proc_stat object containing the string Proc_stat::HALTED. The caller should delete the Proc_stat object when it is no longer needed.

Returns

    A pointer to a Proc_stat object containing the string 

Proc_stat::HALTED.

Exceptions Thrown

none


Halt_event::add_callback - Register the callback function for event processing.

Synopsis


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

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&) 
This method is static and specifies a callback function for all File_event objects until it is replaced.

Exceptions Thrown

none


Halt_event::process - Process this event.

Synopsis


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

Description

This method calls the callback function if it has been set with the set_callback method. Otherwise, Opus_env::close_event is called with Opus_env::IGNORE_EVENT. The callback function will be passed the trigger name as the first argument, a pointer to this event object as the second argument, and a reference to the process' Opus_env object as the third argument.

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


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