Using Client State to Specialize Graphs for a Problem Domain

The fundamental graphs in this package are generic constructs, so any specialized information for a problem domain (e.g., a communications network) must be provided by adding domain-specific information to the edges and vertices that make up the graph. Prg_Graph provides mechanisms to introduce state into the various supported objects. The concept is similar to what is provided by a number of other OPNET Development Kit packages, wherein arbitrary data structures can be attached to the package objects, and then queried or replaced when desired. The structures are exchanged by the client and Prg_Graph as generic memory addresses and declared as void *.

Rather than simply allow the client to attach one structure of state information to edges and vertices, Prg_Graph provides a sophisticated mechanism that supports parallel “planes” of information on each of these objects. These planes typically correspond to multiple clients who are sharing the same graph and wish to manage their state independently.

To accomplish independent state storage on the same objects, the clients leverage a concept called “namespaces”. A namespace defines a family of clients and stores certain key information specific to each client. The namespace is essentially a central registry that several interested clients can “contact”, and receive a unique ID. The ID can then be used to identify the client with respect to all other clients using the same namespace. The unique ID is then used to separate data structures that are attached to each object—in this case, vertices and edges.

Each graph has a namespace. This namespace may be separate from that of other graphs or it can be shared if the graphs manage identical families of client-state. Namespace uniqueness is determined by the names that are given to them when they are created. With Prg_Graph, namespaces are created explicitly by calling prg_graph_state_handler_register(). If the name of the namespace is new (no namespace with the same name has been created yet), the namespace is implicitly created.

For example, imagine two clients in the same application, Visualizer and Routing_Engine, who wish to add state information to the same network graph and to keep that state separately from each other. They can perform the following sequence of actions:

  1. Visualizer registers itself in a namespace called “network operations”, and implicitly creates this namespace through this action, since it is the first one to register. This is accomplished by calling prg_graph_state_handler_register() and specifying the namespace name. In this same call, Visualizer, specifies its own “state name” as “Visualizer”. This will distinguish it from other clients in the “network operations” namespace. Also, at the same time, Visualizer passes in a destroy procedure and a copy procedure, which can be used by the graph package to copy and destroy the Visualizer-specific state when a graph is copied or destroyed. The function returns a state ID (data type PrgT_Graph_State_ID) that will be needed later to select the Visualizer’s state as opposed to the Routing_Engine’s state.
  2. Routing Engine registers itself in the same way as Visualizer. It specifies the same namespace name, “network operations”. However, it specifies its own state name as “Routing Engine” and provides different copy and destroy procedures, appropriate to handle its type of state data structure. It receives a different state ID and stores it in a variable it can reuse later in the program execution. Note that the order of steps 1 and 2 is arbitrary— either client could have registered first.
  3. One of the two clients creates a graph object by calling prg_graph_create() and passing the namespace name “network operations”. It is only necessary that the namespace be created prior to doing this, so technically, this could be step 2. A handle of type PrgT_Graph* is returned to the client and stored in a variable for later use.
  4. Visualizer sets its specific state information on the graph object by calling prg_graph_client_state_set(). It passes in the state ID it received earlier to separate its state from any other potential clients. Note that it does not need to know about the other clients. Note also that in this example, we are setting state on the graph, but the same concepts apply to setting state on edges and vertices
  5. Routing_Engine does the same as Visualizer in step 4, but uses its own state ID. The two states are now separately maintained on the graph.
  6. When either client wishes to retrieve its specific state pointer from the graph object, it calls prg_graph_client_state_get() and passes in its own state ID.

Despite seeming complicated at first, this procedure is generally quite simple, because in most cases only one namespace is needed. First each client registers, then the graph is created. Using the state ID obtained in registration, the clients place state information on each object of interest (e.g., vertices). From there forward, the client simply uses the state ID to retrieve its state pointer whenever it needs to read/write to its private data structure associated with each object of interest.

In cases, where only one client is desired, which is quite common, the same procedure must be followed, but the name of the namespace and the name of the client become insignificant. Any name can be used in order to obtain a state ID.