GVar - EPOCH V3 Global Variable

The GVar class works in conjunction with the GSegment class to provide a remote client interface to an EPOCH global server.

The GSegment class communicates directly with the home global server of the target global segment in order to get information about the variables and to retrieve or store the values of variables. Variables are accessed using the GVar class.

Before accessing individual variables, an application must first initialize access to the global segment(s) containing the variables:

    #include  "GSegment.h"			// GSegment class.
    ...
    GSegment  segment ("stream[@host]") ;
    if (segment.Init ()) {
        ... error initializing access to global server ...
    }

(After the global segment is created, the segment's Poll() method must be called periodically or as necessary in order to receive and process messages from the segment's global server. See GSegment for more information.)

A specific variable can be looked up by name:

    #include  "GVar.h"				// Global variable class.
    ...
    GVar  variable = segment.Find ("name") ;

or the entire list of variables can be scanned by index:

    for (i = 0 ;  i < segment.Count () ;  i++) {
        variable = segment.Get (i) ;
        if (!variable.IsValid ())  continue ;
        ...
    }

[Because there may be gaps in indices caused by temporary variables, Get() may return an invalid variable for a seemingly valid index.] If Find() is passed an invalid variable name or Get() is passed an invalid index, they return an invalid global variable; i.e., the variable's IsValid() method will return false.

Updates to the value of a global variable are automatically initiated when you create the global variable, either with Find() or Get() or with the GVar constructor:

    GVar  variable (segment, "name") ;

You can also bind an update callback to the global variable:

    extern  GVar::UpdateCB  updateCB ;		// Callback function.
    ...
    variable->Bind (updateCB) ;

When update messages for the variable are received from the global server, the application's update callback function is automatically invoked by the segment's Poll() method after the variable's value has been updated.

Since a global variable is a named variable, any of the NVar methods can be applied to the global variable:

    #include  <cstdio>			// Standard I/O definitions.
    ...
    printf ("The value of %s is %s.\n",
            variable->Name (), variable->String ()) ;

Note: The GVar class defines a smart pointer, or handle, to an actual global variable (whose type is _GVar). This implementation has several ramifications for the application programmer:

1. GVar is already a pointer, so there is no need to declare a GVar * pointer or to perform a "new GVar".
2. GVar redefines its -> and unary * operators to pass the references and dereferences on to the _GVar object at which the GVar points. Consequently, a GVar object can access the _GVar and NVar methods of the global variable using these two operators. For example, "(long) *variable" calls the NVar (long) cast operator and returns the variable's value as a long integer.
3. The IsValid() method is a GVar method and must be called using the dot notation: "variable.IsValid ()". This may be somewhat confusing since you will normally be making "variable->XYZ ()" calls.
4. Each GVar handle that is created increments a reference count in the _GVar global variable; each handle that is destroyed decrements the reference count. The _GVar class uses this count to determine when to start updates to the variable's value and when to stop them. Callbacks bound to the global variable override this behavior; i.e., updates will not be discontinued when the reference count drops to zero if there are still callbacks bound to the variable.

Public GVar Methods

GVar() - creates an empty global variable handle.

GVar() - creates a global variable handle.

GVar() - copy constructor.

~GVar() - destroys a global variable handle.

operator=() - assignment operator.

IsValid() - checks if a handle is for an actual global variable.

operator->() - accesses a global variable's methods.

operator*() - accesses a global variable's value.

Public _GVar Methods

(In addition to those inherited from NVar)

_GVar() - creates an EPOCH global variable.

~_GVar() - destroys a global variable.

Flags() - gets a global variable's status flags.

Flags() - sets a global variable's status flags.

Timestamp() - gets a global variable's timestamp.

Timestamp() - sets a global variable's timestamp.

Bind() - binds a callback to a global variable.

Cancel() - cancels a callback.

Refer() - adds a reference to a global variable.

Unrefer() - removes a reference to a global variable.

Private _GVar Methods

InvokeCBs() - invokes the callbacks bound to a global variable.

Source Files

GVar.cpp

GVar.h