GlishEvent.h

This class implements a wrapper around Glish events so that they can be processed within a general event loop. A common interface for receiving and transmitting events allows heterogeneous events to be processed within the same loop.

Typically, the GlishSysEvent objects are either returned by the GlishSysEventSource class or passed as a parameter to a callback function. As a result, this class will rarely be constructed by the user.

Example

This example simply prints out the events it receives. It does this in a procedural manner.

     GlishSysEventSource source(argc, argv);
     GlishSysEvent event;
     GlishValue value;
     GlishArray array;
     GlishRecord record;
     while (source.connected()) {
         event = source.nextGlishEvent();
         cout << "Event " << event.type() << " : ";
         value = event.val();
         if (value.type() == GlishValue::ARRAY) {
             array = value;
             cout << array.format() << endl;
         } else {
             record = value;
             cout << record.format() << endl;
         }
     }

For another example of this type of processing see the example in the Glish module page. For an example of how this class is used in an event driven setting see the other example in the Glish module file or the example below.

Motivation

For X window based Glish clients, it is often necessary to handle Glish and X events in the same loop. See the example in the XSysEvent header file for an example of how X and Glish events can be combined.

Member Description

GlishSysEvent(const GlishSysEvent &other)
GlishSysEvent(const GlishSysEvent *other)

Copy constructor which uses reference semantics.

GlishSysEvent() : event(0), val_(0)

Default constructor which creates an invalid event.

~GlishSysEvent()

GlishSysEvent &operator=(const GlishSysEvent &other)

Assignment Operator using reference semantics.

SysEvent::Group group() const

Returns the group to which this event belongs.

GlishValue &val()

Returns the GlishValue which is stored in this event. This is the actual raw Glish value.

GlishValue::ValueType valType() const

Returns the type of the value stored in the event.

String type() const

Returns the event type of this Glish event. This is the name of the event.

Bool dispatch(SysEventTarget &)
Bool dispatch(SysEventTarget &, SysEventSource &)

Used to deliver this particular event to the SysEventTarget parameter.

Bool isRequest() const

Is this event a request event?

Bool isReply() const

Is this event a reply to a request event?

GlishSysEventSource *glishSource()

This will return the source of this event.

GlishSysEvent(GlishEvent ne, SysEventSource xs)

Used to construct a GlishEvent, when it arrives from the Glish client.

SysEvent *clone() const

Returns a deep copy of this object.

void fillVal() const

Internal function which fills the internal GlishValue object using the Glish Value from the event. This must be called before the accessors can be used.

class GlishSysEventSource : public SysEventSource

Interface

Public Members

GlishSysEventSource(int &argc,char **argv)

~GlishSysEventSource()

SysEvent::Group group() const

Client &client()

SysEvent nextEvent()

GlishSysEvent nextGlishEvent()

Bool nextGlishEvent(GlishSysEvent &event, Int timeOutInMillisec)

Bool waitingEvent()

void processEvent( GlishSysEvent )

Bool connected()

Bool hasInterpreter()

void postEvent(const String &name, const String &value)

void postEvent(const String &name, const Value *val)

void postEvent(const String &name, const GlishValue &val)

void postEvent(const String &name, const GlishArray &val)

void postEvent(const String &name, const GlishValue *val)

void postEvent(const char *name, const char *val)

void postEvent(const String &name, const char *val)

void postEvent(const char *name, const String &val)

void reply(const GlishValue &val)

void reply(const GlishValue *val)

Bool replyPending() const

void unrecognized()

Int addInputMask(fd_set *selectSet)

void Error( const String &msg )

Bool canCombine(const SysEventSource &other) const

Bool canCombine(const SysEventSource *other) const

Bool combine(SysEventSource &other)

Bool combine(SysEventSource *other)

Bool addTarget(SysEventTarget &tgt, const String &regx)

Bool addTarget(SysEventTarget *tgt, const String &regx, Bool ownTarget=False)

Bool addTarget(SysEventTargetProc tgt, const String &regx, void *userData=0)

Bool addTarget(GlishSysEventTargetProc tgt, const String &regx, void *userData=0)

Bool setDefault(SysEventTarget &tgt)

Bool setDefault(SysEventTarget *tgt, Bool ownTarget=False)

Bool setDefault(SysEventTargetProc tgt, void *userData=0)

Bool setDefault(GlishSysEventTargetProc tgt, void *userData=0)

Bool loop()

void invokeTarget()

Protected Members

GlishEvent *nextPrimitiveEvent(timeval *timeout, int &timedout)

Bool invokeTarget(GlishEvent *ev)

Description

Review Status

Reviewed By:

pshannon

Date Reviewed:

1994/10/28

Programs:

Demos:

dGlish

Prerequisite

SysEventSource
GlishSysEvent

Etymology

See SysEvent

Synopsis

This class implements a wrapper around the generation of Glish events. This allow Glish events to be used in a heterogeneous event loop. The loop can either be a procedural type of loop where the events are retrieved then processed, or an event driven loop.

Procedural Example

This demonstrates an echo client which simply echoes its events back through the GlishSysEventSource.

    GlishSysEventSource source(argc, argv);
    GlishSysEvent event;
    while (source.connected()) {
        event = source.nextGlishEvent();
        source.postEvent(event.type(),event.val());
    }

For another example of this type of event processing see the example in the Glish module page.

Event Driven Example

This class can also be used in an event driven manner. This next example demonstrates this:

    #include <aips/Glish.h>
    
    Bool helloCallback(GlishSysEvent &e, void *) {
        GlishSysEventSource *src =  (GlishSysEventSource*)e.source();
        (*src).postEvent("hello_got",e.type());
        return True;
    }
    Bool defaultCallback(GlishSysEvent &e, void *) {
        GlishSysEventSource *src =  (GlishSysEventSource*)e.source();
        (*src).postEvent("default_got",e.type());
        return True;
    }
    
    int main(int argc, char **argv)
    {
        GlishSysEventSource eventStream(argc, argv);
    
       eventStream.setDefault(defaultCallback);
       eventStream.addTarget(helloCallback,"^hello");
       eventStream.loop();
    }

In this example all of the events whose name begins with hello get directed to the helloCallback. The rest get directed to the defaultCallback. For other examples of event driven processing see the example in the Glish module page, or the example in the XSysEvent page which includes X Windows events in the loop.

Member Description

GlishSysEventSource(int &argc,char **argv)

Takes the command line parameters, argc and argv, and initializes the Glish Client to begin producing GlishEvents. Argc and argv are required because Glish uses the command line parameters to pass port information to the client.

~GlishSysEventSource()

SysEvent::Group group() const

Returns the group which this event source belongs to. The group indicates which type of events this particular SysEventSource generates.

Client &client()

Gets the "raw" Glish Client for performing operations.

If it is necessary to manipulate the underlying Glish Client, then the public interface of one or more of these classes probably needs extending.

SysEvent nextEvent()

Get the next event which is queued up. This will block.

GlishSysEvent nextGlishEvent()

Get the next Glish event. This blocks until there is an event.

Bool nextGlishEvent(GlishSysEvent &event, Int timeOutInMillisec)

Get the next event. If the event has not occurred in the timeout period, return False, otherwise return True and set event. Timeout of zero means return immediately if there is no pending event, less than zero means to block until there is an event.

Bool waitingEvent()

Check to see if there are any Glish events waiting to be handled.

void processEvent( GlishSysEvent )

Process one Glish event.

Bool connected()

Indicated if the source is still connected to the event stream.

Bool hasInterpreter()

Indicates if the client is connected to a Glish interpreter elsewhere. If False is returned, the client is running stand-alone; if True is returned it the client is connected to a interpreter.

void postEvent(const String &name, const String &value)
void postEvent(const String &name, const Value val)
void postEvent(const String &name, const GlishValue &val)
void postEvent(const String &name, const GlishArray &val)
void postEvent(const String &name, const GlishValue val)
void postEvent(const char name, const char val)
void postEvent(const String &name, const char val)
void postEvent(const char name, const String &val)

This posts an event to the Glish system where the first parameter is the event name, and the second parameter is the event value.

void reply(const GlishValue &val)
void reply(const GlishValue *val)
Bool replyPending() const

Post an event to the Glish system in reply to the last event received.

void unrecognized()

Post an event to indicate that the last event was not understood.

Int addInputMask(fd_set *selectSet)

get the client FDs

void Error( const String &msg )

Called to report that the current event has an error.

Bool canCombine(const SysEventSource &other) const
Bool canCombine(const SysEventSource *other) const

Check to see other can be combined with this event stream.

Bool combine(SysEventSource &other)
Bool combine(SysEventSource *other)

Combine other with this event stream. If this is impossible, False is returned.

Bool addTarget(SysEventTarget &tgt, const String &regx)
Bool addTarget(SysEventTarget tgt, const String &regx, Bool ownTarget=False)
Bool addTarget(SysEventTargetProc tgt, const String &regx, void userData=0)
Bool addTarget(GlishSysEventTargetProc tgt, const String &regx, void *userData=0)

Invoke the specified target whenever the event matches the regular expression (the second parameter). If the target cannot be added False is returned.

Bool setDefault(SysEventTarget &tgt)
Bool setDefault(SysEventTarget tgt, Bool ownTarget=False)
Bool setDefault(SysEventTargetProc tgt, void userData=0)
Bool setDefault(GlishSysEventTargetProc tgt, void *userData=0)

Specifies the default action. This target is invoked whenever none of the other targets apply. If the target cannot be added False is returned.

Bool loop()

loop and deliver events to targets as they arrive. The process will be blocked until an event arrives.

void invokeTarget()

This is for internal use, and is invoked when an event may be available for processing on this event source.

GlishEvent nextPrimitiveEvent(timeval timeout, int &timedout)

Get the next base-level Glish event which is queued up. This will block.

Bool invokeTarget(GlishEvent *ev)

class GlishSysEventTarget : public SysEventTarget

Interface

Public Members

GlishSysEventTarget(Bool (*one)(GlishSysEvent &)) : cb_one(one), cb_two(0)

GlishSysEventTarget(Bool (*two)(GlishSysEvent &, GlishSysEvent &)) : cb_one(0), cb_two(two)

GlishSysEventTarget() : cb_one(0), cb_two(0)

~GlishSysEventTarget()

SysEvent::Group group() const

SysEventTarget *clone() const

virtual Bool handle(SysEvent)

virtual Bool handle(GlishSysEvent &)

virtual Bool handle(GlishSysEvent &, SysEventSource &)

Protected Members

Bool (*cb_one)(GlishSysEvent &)

Bool (*cb_two)(GlishSysEvent &, SysEventSource &)

Description

Review Status

Reviewed By:

pshannon

Date Reviewed:

1994/10/28

Programs:

Demos:

dGlish

Prerequisite

SysGlishEvent
SysGlishEventSource

Etymology

See SysEvent

Synopsis

This class implements a generalized wrapper around Glish event handlers. This allows events of different types to be accepted, and dispatched within the same event loop.

Example

This example simply takes an event, modifies it, i.e. sticks the letters 'MOD' on the front of the event type, and then reposts the event.

     void eventhandler(GlishSysEvent &evt) {
         GlishValue &val = evt.val();
         GlishSysEventSource *s = (GlishSysEventSource *) evt.source();
         String mod("MOD");
         String sval = val.format();

         mod += evt.type();

         s->postEvent(mod,sval);
     }

     main(int argc, char **argv) {
         GlishSysEventSource gsrc(argc,argv);
         GlishSysEventTarget gtgt(eventhandler);
         SysEvent event;

         while (gsrc.connected()) {               // 1
             if (gsrc.waitingEvent()) {           // 2
                 event = gsrc.nextEvent();        // 3
                 event.dispatch(gtgt);            // 4
             }
             // ...                               // 5
         }
     }

If an extra event source were added to this loop, the 'group()' and perhaps the 'type()' of the event could be used to choose among a number of SysEventTargets. Here:

Loop while the event sources are connected. Here there is only a GlishSysEventSource.
Check to see if there is an event waiting from a particular event source.
Get the event.
Dispatch the event. There could be more than one target for a particular SysEventSource, and the 'group()' and the 'type()' of the SysEvent could be used to decide which target should receive the event.
Check any other SysEventSources for waiting events.

Member Description

GlishSysEventTarget(Bool (*one)(GlishSysEvent &)) : cb_one(one), cb_two(0)

Construct an event with a target function which takes an event for handling.

GlishSysEventTarget(Bool (*two)(GlishSysEvent &, GlishSysEvent &)) : cb_one(0), cb_two(two)

Construct an event with a target function which takes an event and a SysEventSource. This is useful when the handling function must know another event source. A case where this happens is when a Glish handler function must post X events. In this case, the XSysEventSource must be available.

GlishSysEventTarget() : cb_one(0), cb_two(0)

Constructs an event target which ignores events.

~GlishSysEventTarget()

SysEvent::Group group() const

Return the group to which this handler belongs.

SysEventTarget *clone() const

virtual Bool handle(SysEvent)
virtual Bool handle(GlishSysEvent &)
virtual Bool handle(GlishSysEvent &, SysEventSource &)

Handle the given event.

Bool (*cb_one)(GlishSysEvent &)

Bool (*cb_two)(GlishSysEvent &, SysEventSource &)

class GlishSysEventProcTargetInfo : protected SysEventTargetInfo

Interface

Public Members

GlishSysEventProcTargetInfo(GlishSysEventTargetProc t, const String &r,void *u=0) : SysEventTargetInfo((SysEventTargetProc) t,r,u)

GlishSysEventProcTargetInfo(GlishSysEventTargetProc t, void *u=0) : SysEventTargetInfo((SysEventTargetProc) t,u)

GlishSysEventProcTargetInfo &operator=(GlishSysEventProcTargetInfo &other)

~GlishSysEventProcTargetInfo()

GlishSysEventTargetProc getGlishTargetProc()

uInt id() const

Description

This class is used as a container of information for dispatching targets. It facilitates invoking targets based on regular expressions.

This class is not intended for external use.