Execution Details
This section describes the behavior of an HLA simulation using the Federate Ambassador created by the HLA_Interface node.
HLA initialization, which includes creating and joining the federation, establishing time management, and delivering the initialization callback to the esys module, occurs immediately before the execution of the simulation event. If you are using the ODB, the HLA initialization event occurs after you execute the first odb> prompt.
During the course of the simulation, the HLA-PM uses RTI services and Modeler Simulation Kernel procedures. The HLA-PM:
- Reads in the class mapping file referenced by the HLA Class Mapping File simulation attribute and performs appropriate RTI initializations.
- Receives HLA events from other federates and contributes to time advance based on Modeler actions.
- Receives HLA attribute updates, updates the corresponding Modeler attributes, and informs other nodes of these updates if requested.
- Receives HLA interactions, converts the interactions to packets, and forwards the packets to the appropriate process model.
- Publishes (to the RTI) changes to Modeler attributes if the object changed is mapped to an HLA object.
- Provides other nodes with the ability to send out HLA interactions to the RTI.
Joining the Federation
After initialization, the HLA-PM either initiates the federation itself or joins a federation initiated by another federate.
To make Modeler initiate the federation, set the HLA Create Federation and HLA Federation Name simulation attributes appropriately. The HLA-PM ignores attempts to create an existing federation. See “HLA-PM Attributes” on page 12 for details.
If the Riverbed federate is not the initiator, it attempts to join the federation specified in the HLA Federation Name simulation attribute. If it fails, the Modeler simulation terminates.
If joining succeeds, the HLA-PM then:
-
Indicates its time management mode (time-constrained and time-regulating) to the RTI.
-
Initiates time management (see “Managing and Advancing Time” on page 8).
-
Reads in the class mapping file.
-
Traverses the network model to catalog the Modeler objects that may map to HLA objects, creating the appropriate HLA objects if specified in the mapping file.
-
Registers and updates the HLA objects that should be created.
Other parts of the network model might attempt to register for interaction handling (see Delivering Interactions) or might generate interactions or attribute updates (see Generating Outgoing Data) before the HLA-PM can finish its initialization. These requests will be delayed until initialization is complete.
Creating Objects
Each object in a federation is represented at least twice: once as an Modeler object, once as an HLA object. One and only one federate creates the HLA representation; the other federates simply discover the newly-created object and (usually) create their own internal representations of it.
The RTI associates a unique HLA ID with each created object. The other federates learn of the creation by a discovery callback which provides them with the class and ID of the new object.
Because Modeler does not dynamically create objects at the network or module level, all necessary Modeler representations must be created when the simulation starts. This means that Modeler needs to know:
- Which HLA objects to create.
- How to map discovered HLA objects to Modeler objects.
Creating HLA Objects
If the <CreateMode> rule of the class mapping file includes the creation mode “create”, the HLA-PM, during the initialization phase, creates an HLA object for each Modeler object that matches that rule (see Object and Attribute Mappings for details of this rule). The name of the HLA object is generated using the attribute specified in the <CreateMode> rule.
If the <CreateMode> rule of the class mapping file includes the creation mode “dynamic”, process models can dynamically request the mapping of an Modeler object to an HLA object, using the op_hla_obj_create_notify() Kernel Procedure. The RTI creates the appropriate HLA object, if possible. The HLA object attributes are then updated.
Mapping Discovered Objects
If the <CreateMode> rule of the class mapping file includes the creation mode “discover”, then discovered objects must be uniquely matched, HLA object to Modeler object and vice versa.
On discovery, the HLA-PM receives the discovered object’s class, ID, and name.
- If name_match has been specified, then matching is performed immediately.
- If attr_match has been specified, matching is delayed until the first set of attribute updates is received. These are the attributes that Modeler subscribed to in the class mapping file by placing an “S” in the
<PS>rule. See Object and Attribute Mappings for details of the name_match and attr_match rules.
If the HLA-PM cannot map a discovered object, it discards any further updates for that object and writes a warning to the console.
If mapping is successful, the HLA-PM will try to take ownership of any attribute of the discovered object that is marked as published.
Destroying an Object
RTI objects can be destroyed during a simulation. The destruction can occur in another federate or in the Modeler simulation itself.
- If the destruction occurs in another federate, the event is reported to the HLA-PM, which removes the appropriate mapping from its class mapping file. The Modeler object itself still exists and executes.
- If the destruction occurs in the Modeler simulation, the process model requests the destruction of the RTI object using
op_hla_obj_destroy_notify(). The Modeler object itself still exists and executes.
Sending Notifications
When an HLA object is discovered or created, the object is mapped to an Modeler object. Similarly, when an HLA object is destroyed, the Modeler object is unmapped. The kernel procedure op_hla_obj_notification_enable() requests that the invoking process model be informed when either event occurs.
A remote interrupt with a specified event code will be generated when the mapping or unmapping occurs.
Other process models can query the HLA-PM for ID mapping between Modeler and HLA, using op_hla_obj_info_get() and op_hla_id_hla_to_opnet_map().
Handling Incoming Data
There are two forms of incoming data:
- attribute updates
- interactions
By default, the DES engine acts as a time-constrained federate. As a result, Modeler time advances only when the federation time does. Updates or interactions are processed only when their timestamps match Modeler time. You can change this behavior via simulation attributes (see “HLA-PM Attributes” on page 12).
Updating Attributes
When an attribute of an HLA object is modified by one federate, all federates that subscribe to that attribute receive an update with the new value. In the Riverbed federate, updates are received by the HLA-PM. On receipt, the HLA-PM:
- Identifies which Modeler object should either receive the update or establish a mapping. An attribute update can cause a mapping event if the attr_match rule is used to map objects (see Mapping Discovered Objects).
- Updates the mapped Modeler attributes.
- If requested, the HLA-PM informs registered process models that an attribute update has been performed, using a remote interrupt with the list of updated attributes.
The following table lists Kernel Procedures related to attribute updates. See “Project Editor” on page 89 in the Editors Reference manual for details.
Table 6: Attribute Update KPs
| Purpose | Kernel Procedure Name |
|---|---|
| Request notification of attribute updates | op_hla_obj_notification_enable() on page 33 |
| Cancel notification of attribute updates | op_hla_obj_notification_disable() on page 31 |
| Retrieve the list of modified attributes for a mapped object | op_hla_attr_update_list_get() on page 8 |
For a description of the format used to pack attribute values, see Representing Attribute and Parameter Values.
Delivering Interactions
An interaction is provided from a federate to the RTI, which in turns delivers it to each federate that registered for that class of interaction. In the Riverbed federate, the HLA-PM receives the interaction. Modeler registers for an interaction if at least one process model (other than the HLA-PM) has requested the interaction.
After receiving the interaction, the HLA-PM determines which process models are registered to handle the particular type of interaction. The HLA-PM then converts the interaction to the appropriate Modeler packet format using the mapping described in Interaction/Parameter Mappings. Any “tag” value received with the interaction is placed in the packet if the interaction mapping includes an entry mapping the special name <tag> to a field of the packet.
The HLA-PM converts only the parameters corresponding to integer or floating-point data types with a cardinality of 1. The data corresponding to the other parameters is simply copied into a local data block (allocated using the op_prg_mem_alloc() Kernel Procedure) and the pointer to that block placed in the field of the packet (which would be defined as Structure). The data block and its size are obtained using op_hla_interaction_pk_struct_get(). The recipient is responsible for extracting the data actually stored in that data block and freeing the data block after use with op_prg_mem_free(). An interaction handler module is responsible for disposing of the converted packet it received, using op_pk_destroy().
The converted data structure is delivered to all registered process models via stream interrupts scheduled for the interaction time.
The following table lists HLA Kernel Procedures related to interactions. See “Project Editor” on page 89 in the Editors Reference manual for details.
Table 7: Interaction KPs
| Purpose | Kernel Procedure |
|---|---|
| Used by the process model instance to register its interest in a specific packet type with the HLA-PM | op_hla_interaction_pk_register() |
| Used by the process model instance to cancel an existing registration with the HLA-PM | op_hla_interaction_pk_deregister() |
For a description of the format used to pack parameter values, see Representing Attribute and Parameter Values.
Generating Outgoing Data
By default, the DES engine acts as a time-regulating federate. This means that the attribute updates and interactions the Riverbed federate publishes have a time-stamp of the current federate time plus the lookahead (see “Managing and Advancing Time” on page 8).
Updating Attributes
The Riverbed federate must notify other federates about changes to published attributes of any Modeler object. To meet this responsibility, the HLA-PM keeps a copy of the published attributes and regularly checks the appropriate objects to determine if their attribute values have changed. When it detects a change, the HLA-PM generates attribute updates.
You specify the time interval between checks in the HLA Update Check Interval simulation attribute. See “HLA-PM Attributes” on page 12 for details.
Process models can also inform the HLA-PM that some attributes have been updated and that the RTI should be informed immediately. A specific attribute change is indicated by using op_hla_obj_attr_set() instead of op_ima_obj_attr_set(). This HLA-specific function informs the HLA-PM of the attribute change.
The kernel procedure op_hla_attr_change_notify() notifies the HLA-PM that all published attributes of the object should be checked for changes.
Generating Interactions
Process models mimic HLA interactions by creating a corresponding packet and forwarding it to the HLA-PM via a procedure call interrupt. The HLA-PM converts the packet to an interaction and passes it to the RTI, which delivers it to all interested federates.
The process occurs as follows. In the steps below, the process model mimicking the interaction is called the “source process model” to distinguish it from the HLA-PM. You must write code that implements these steps in the source process model. Code to perform the HLA-PM step is already included in the HLA-PM.
-
The source process model creates a packet.
-
The source process model uses
op_pk_nfd_set()to assign integer and floating-point values to the packet. -
The source process model uses
op_prg_mem_alloc()to allocate memory for the Structure fields, if any. It usesop_hla_interaction_pk_struct_set()to assign structure fields (using the block of bytes already allocated) and transfer ownership of the data block to the HLA-PM. -
The source process model uses
op_hla_interaction_pk_send()to deliver the packet to the HLA-PM. This KP specifies the time at which the interaction should be delivered (which could be immediately). The tag value is placed in the packet if the mapping file includes a mapping between the special HLA name<tag>and some field of the packet format (see Interaction/Parameter Mappings).Packet fields of type Structure should contain pointers to blocks of data allocated with
op_prg_mem_alloc()and filled using the packing conventions described in Representing Attribute and Parameter Values. -
The HLA-PM converts the packet to an RTI structure and then destroys the packet, freeing structure blocks with
op_prg_mem_free().
Note: Although the RTI delivers interactions between federates, it does not deliver interactions back to the originating federate. This means that if you want other process models in the originating federate to receive the packet, you must write explicit code for that task, using standard
op_pkKPs such asop_pk_deliver().
Sending HLA Events to the RTI
Outgoing attribute updates and interactions are queued for transfer to the RTI when the HLA-PM resumes execution.
Representing Attribute and Parameter Values
The HLA Object Model Template document you prepared defines the binary representations of most of the various data types used for attribute and parameter values. The HLA-PM performs the following data conversions:
- Between the Modeler representation of object attributes (as data types) and the HLA representation of attributes (as packed data blocks).
- Between the Modeler representation of packet fields (as integer and double data types) and the HLA representation of parameters (as integer and floating-point data types).
The HLA-PM does not convert structure packet types. The encoding of data inside these types is done by the process models receiving the interactions.
The table below shows the binary representations of various HLA types as used by the HLA-PM. Multi-byte numerical values are stored in network order.
Table 8: Binary Representations of HLA Data Types
| HLA type | Binary Representation |
|---|---|
| float | IEEE single-precision floating-point number, 32 bits |
| double | IEEE double-precision floating-point number, 64 bits |
| short | 16 bits |
| unsigned short | 16 bits |
| long | 32 bits |
| unsigned long | 32 bits |
| long long | 64 bits |
| unsigned long long | 64 bits |
| char | 8 bits, unsigned |
| boolean | 1 bit, stored as 8 bits with the value located in the least significant bit |
| octet | 8 bits, unsigned |
| string | NULL-terminated sequence of characters |
| complex | Sequence of rows, each composed of sequence of field values (cardinality imposed by Modeler variable) |
The HLA-PM uses the type definition provided in the mapping file to encode or decode HLA attribute and parameter values.
Modeler supports symbol maps, which allow you to map a value to a character string. The encoding/decoding scheme does not support symbol maps, so the value, not the string, is passed. Do not define symbol maps for Modeler attributes that will be mapped to HLA attributes.
Note: The binary representations listed in the table above are not used with tag values. A tag value is simply a null-terminated string.
Packing and Unpacking Data
The HLA-PM code includes a set of classes and operators to perform data packing and unpacking, based on the representations in the Binary Representations of HLA Data Types table. Sim_Hla_Ostream packs data in network order. Sim_Hla_Istream extracts data in host order.
Operators are provided for all types in the table except complex. Additional operators can be created.
Ownership of Data
An HLA attribute can be modified by a federate only if that federate owns the corresponding attribute. Usually, ownership of an attribute can be passed from federate to federate, with the RTI requesting that the current federate owner relinquish ownership. In this release, the Riverbed federate never relinquishes ownership. This means that attributes owned by the Riverbed federate cannot be modified by any other federate.
Concluding the Simulation
When the Modeler simulation completes, the Riverbed federate resigns from the federation. If the HLA Destroy Federation simulation attribute is enabled, the HLA-PM will attempt to destroy the federation. If other federates are still part of it, this attempt will fail.
For more information, see “HLA-PM Attributes” on page 12.
Debugging Information
Debugging information is available from the HLA-PM and its associated functions for use with Simulation Debugger (ODB) and the ltrace and proldiag commands.