Objects

Each of the objects within an NRAC network maintains certain information to support the NRAC services. Table 2 lists a summary of the objects and the information that is relevant for each.

Table 2: NRAC Network Objects

Object Description Maintained Information
Network Container for all other types of objects. Provides a context, separate from other networks. Name: free form text
Name of the unit for resource measurement (e.g., "Mbps")
Client state pointer: pointer to user-defined memory to be associated with this object.
All of the resources, consumers, and events that are created within this network
Resource Infrastructure building block; something that can be used by one or more consumers. Name: free form text
Capacity: size of the resource
Client state pointer (see above)
Consumer Infrastructure user; something that consumes resources. Name: free form text
Load: amount of resource consumed
Client state pointer (see above)
Event A condition or circumstance that affects how resources are consumed. Description: free form text
Client state pointer (see above)
Conditional Consumer An object returned by NRAC for certain queries; represents the pairing of a consumer and an event. Consumer: consumer of interest
Event: event required for the consumer to actually use the resource

NRAC objects are managed by API clients via "handles". In a nutshell, handles are references to the objects of interest. To operate on an object via the APIs, the handles are used. Handles are much like pointers, but allow the programmer to maintain a more abstract view of the object, without having to think of it as a "block of memory". The handles for NRAC package objects are listed in Table 3. Each handle has its own data type used for function arguments and variables.

Table 3: NRAC Object Handles

NRAC Object Handle Data Type
Network Nrac_Net_Handle
Resource Nrac_Resource_Handle
Consumer Nrac_Consumer_Handle
Event Nrac_Event_Handle
Conditional Consumer Nrac_Conditional_Consumer_Handle

Several important remarks and references to functions will clarify how to use these objects:

  • The relationship between resources and consumers is "many-to-many". In other words, a single resource may be utilized by multiple consumers. This makes sense in the context of "oversubscription" of a resource, and specifically because the relationships may be dependent upon an event. Thus, multiple consumers may share a resource, and never conflict with each other if their use of the resource is dependent upon mutually exclusive events. This is well-matched to the concept of shared protection in network capacity planning.
  • Resource-consumer relationships are put in place by calling nrac_resource_consumer_add(). There are several ways to "undo" such relationships, each with different scope:
  • Queries can be performed to examine the state of the system from the perspective of resources or consumers. The NRAC package provides the service of tallying all relationships you have set up. This relieves you of the burden to do so. Use nrac_resource_consumers_get() to find the consumers that use a specific resource. Use nrac_consumer_resources_get() to find all of the resources that are used by a given consumer (e.g., all of the links traversed by an end-to-end connection). Use nrac_resource_load_get() to obtain the load placed on a given resource by the various consumers in the network.
  • Conditional consumers are objects returned by nrac_resource_consumers_get(). More precisely, a list (List * from the Prg package) is returned which contains zero or more conditional consumer objects. Each conditional consumer object expresses that the resource of interest is used by the consumer, but only under the condition of a specific event. The consumer and event for each such object can be obtained by calling nrac_conditional_consumer_consumer_get() and nrac_conditional_consumer_event_get(), respectively.
  • Many of the functions that allow you to specify a specific event or a consumer also allow you to substitute, for that information, a special constant indicating "any event" (NRAC_ANY_EVENT), or "any consumer" (NRAC_ANY_CONSUMER). This wildcard feature allows you to request, for example, the list of consumers that use a specific resource, under any condition, as opposed to when a specific event occurs. Similarly, you can remove all of the consumers from a resource, by specifying NRAC_ANY_CONSUMER for the consumer you wish to remove when calling nrac_consumer_remove_from_resource().
  • Each of the objects mentioned in the table above allows you to access the basic information it maintains by calling the appropriate "get" function. For example, nrac_event_desc_get() allows you to obtain the description of an event object. See the detailed function listings in this chapter for a comprehensive explanation of the analogous "get" functions.
  • The concept of "client state pointers" is supported by each of the principal object types. The purpose of these pointers is to allow you to efficiently relate NRAC objects to objects or structures within your application. As an example, when you call nrac_consumer_resources_get(), you will obtain a list of resource handles. These resource objects may have names if you set them when creating the resource objects. However, using names to look up the corresponding objects in your network may be inefficient. To solve this problem, you can embed a pointer to a link object (for example) in your network into each resource within an NRAC network model. Client state pointers are optional—if you wish not to use them for some or all of the objects, simply pass in the NIL pointer when creating the objects.