GSegment - EPOCH V3 Global Segment

The GSegment and GVar classes provide a remote client interface to an EPOCH V3 global server.

The official EPOCH implementation of a client interface accesses global variables directly out of shared memory, thus requiring that an EPOCH global server be running on the client's host. When a client needs to access global variables residing on another machine, the local global server communicates with the remote global server in order to provide a mirror image of the remote machine's shared memory segment.

The GSegment/GVar combination takes a different approach: rather than requiring a local global server and shared memory, 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.

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

    #include  <cstdio>			// Standard I/O definitions.
    #include  "GSegment.h"			// GSegment class.
    GSegment  segment ("stream[@host]") ;
    if (segment.Init ()) {
        ... error initializing access to global server ...

A network connection is established with the home global server for the stream's segment and a list of the variables in the segment is downloaded and saved by the GSegment segment.

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. Poll() waits for and reads a single batch of incoming messages; a timeout may be specified to limit how long Poll() waits for input:

    for ( ; ; ) {
        segment.Poll (5.0) ;			// Wait 5 seconds.
        ... do something else ...

In event-driven applications (e.g., those based on the X Toolkit or the ERAL Dispatcher class), the socket connection to the global server, returned by the segment's Fd() method, can be monitored for input by your event dispatcher. The input callback, when invoked, should call Poll() with a 0.0-second timeout to read and process the waiting messages. The IsUp() method can be called to check if the global server connection is still up.

A specific variable can be looked up by name:

    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.]

Access to a global segment is terminated when the segment object is destroyed.

Public Methods

GSegment() - creates an EPOCH global segment.
~GSegment() - destroys a global segment.
Init() - initializes a global segment.
Bind() - binds a callback to a global segment.
Count() - returns the maximum number of variables in a global segment.
Fd() - gets a global segment's socket number.
Find() - looks up a variable by name in a global segment.
Get() - looks up a variable by index in a global segment.
IsUp() - checks if a global segment is active.
Name() - returns a global segment's name.
Poll() - processes pending updates to a global segment.

Private Methods

DecodeDefinitions() - decodes a variable definitions message.
DecodeUpdates() - decodes a variable updates message.
StartUpdates() - requests updates from the global server.
StopUpdates() - cancels updates from the global server.

Source Files


Alex Measday  /  E-mail