Argument Data Types
The Syntax and Return Type sections of KP descriptions present the calling syntax of a KP. Each argument of the procedure is separately listed, as well as the procedure’s return type. Argument listings include the name, C/C++ data type, and description text; the return type is similar, except it lacks a name. The purpose of these two sections is to clearly define the calling interface of a KP, and to avoid incorrect interpretation of the return value or argument data types.
Many arguments and return values of KPs are standard C/C++ data types, such as int, double, and char*.
Besides the basic C/C++ data types, arguments and return values are often declared to be special Riverbed data types. These data types are derived from simulation data structures via the typedef statement of the C/C++ language. Although users are involved in manipulating Riverbed data types via KPs, and they become familiar with the basic contents of each data type, the exact internal structure of the data type need not be of concern. In fact, the contents of simulation data structures may change in new releases of the software, so it is good practice to not depend on undocumented internal fields of the data structures. Each of the special data types are introduced in the following sections.
- Animation Entities
- Booleans
- Compcodes
- Distributions
- Event Handles
- Statistic Handles
- ICIs
- Lists
- Object IDs
- Packets
- Memory Object Types
- Log Handles
- Procedures
- Process Handles
- SAR Buffer Handles
Animation Entities
The Anim (Animation) package relies on numeric “serial numbers” (IDs) to refer to specific animation entities involved in operations. Integer IDs are used instead of C/C++ pointers because the IDs are communicated beyond the scope of the simulation, to the animation viewer program, op_vuanim. Even though the IDs are simply integer values, and may be stored in regular C/C++ integer variables, specific data types have been declared to precisely tag ID arguments and variables. The three animation entities referenced by IDs are viewers, macros, and drawings; their respective data types are listed below.
| Base Data Type | Anvid (viewer ID) |
|---|---|
| Example Declaration | Anvid vid; |
| Base Data Type | Anmid (macro ID) |
|---|---|
| Example Declaration | Anmid mid; |
| Base Data Type | Andid (drawing ID) |
|---|---|
| Example Declaration | Andid did; |
Booleans
Booleans are values returned by many Kernel Procedures to indicate a true or false result. The value of a Boolean can be compared to the symbolic constants OPC_TRUE and OPC_FALSE.
| Base Data Type | Boolean |
|---|---|
| Example Declaration | Boolean bool; |
Compcodes
Compcodes are values returned by many Kernel Procedures that indicate whether an operation completed successfully. The value of a Compcode may be compared to the symbolic constants OPC_COMPCODE_SUCCESS and OPC_COMPCODE_FAILURE.
| Base Data Type | Compcode |
|---|---|
| Example Declaration | Compcode comp_status; |
Distributions
Distributions are data structures that describe the mapping of a random number into a specific numeric outcome, consistent with a probability density function (PDF). The distribution can include a numeric table which encodes the mapping, or it can point to an algorithm which will perform the mapping. For table-based distributions, the contents data is read in from a PDF model file which has been prepared using the PDF Editor. These structures are manipulated by the Dist package KPs.
| Base Data Type | Distribution |
|---|---|
| Example Declaration | Distribution* dist_ptr; |
Event Handles
Event handles are data structures which uniquely identify a pending simulation event (interrupt). These structures are used by Intrpt Package KPs, so that scheduled interrupts can be manipulated through their handle. Note that event handles are actually data structures, and not integers or pointers. Therefore, they should not be cast into or stored in integer or pointer variables.
| Base Data Type | Evhandle |
|---|---|
| Example Declaration | Evhandle evh; |
Statistic Handles
Statistic handles are data structures used to identify global and local statistics that are created dynamically. The data type provided for these handles is Stathandle and the only way to obtain such a handle is by “registering” a statistic via a KP dedicated to this purpose in the Stat package. A statistic has a unique name that is specified at registration, and also an output vector used to store its values over time. Local statistics are used within a specific processor or queue. Global statistics are typically shared by several different entities in a simulation model, and each of these entities contributes to the output vector in a distributed manner.
| Base Data Type | Stathandle |
|---|---|
| Example Declaration | Stathandle stat_handle; |
ICIs
ICIs (Interface Control Information) are collections of structured data associated with simulation interrupts. They serve as an inter-process communication mechanism, specialized for conveying information which controls layered protocol interfaces. These structures are manipulated by Ici package KPs.
| Base Data Type | Ici |
|---|---|
| Example Declaration | Ici* ici_ptr; |
Lists
Lists are ordered collections of data elements, stored in a doubly-linked chain. Elements in lists can range from simple C/C++ data types to complex data structures. Lists can be heterogeneous, containing collections of varied elements, but they typically are not. Lists can grow arbitrarily large; elements can be inserted into or removed from any specified position. Lists are often used to temporarily store groups of related data structures. These structures are manipulated by the List sub-package of the Prg package.
| Base Data Type | List |
|---|---|
| Example Declaration | List* list_ptr; |
Object IDs
An object ID is a numeric “serial number” that uniquely identifies a single simulation object. The Objid data type is used to declare these identifiers. Objids are used by the Id, Ima, Topo and Pk packages.
| Base Data Type | Objid |
|---|---|
| Example Declaration | Objid objid; |
Packets
Packets are the fundamental simulation entity for modeling encapsulation and transmission of data. These structures are manipulated by Pk package KPs.
| Base Data Type | Packet |
|---|---|
| Example Declaration | Packet* pkptr; |
Memory Object Types
Some modeling applications may require memory to be allocated on a dynamic basis in order to provide storage for variable amounts of information. When new data items are created and destroyed on a recurring basis and groups of items of the same physical size (in terms of bytes) can be identified, it is often most efficient to use the Pooled Memory facility provided by the Simulation Kernel. Each group of equally sized data items is referred to as a pool, and the Kernel is able to simultaneously allocate large numbers of items at once for each pool in order to improve efficiency over the standard memory allocator. Each pooled memory object type must be created by calling the KP op_prg_pmo_define(), which returns a Pooled Memory Object Handle that identifies the pool. The data type provided for these handles is Pmohandle. A pooled memory object type has a unique name that is specified when it is created. Each pooled memory object type is typically shared by multiple entities in a simulation model.
| Base Data Type | Pmohandle |
|---|---|
| Example Declaration | Pmohandle pmh; |
Log Handles
When creating simulation logs to aid in simulation debugging or results analysis, a log handle is necessary for each category of log entry.
| Base Data Type | Log_Handle |
|---|---|
| Example Declaration | Log_Handle config_log_hndl; |
Procedures
Several KPs take C/C++ function pointers as arguments. Instead of declaring these arguments as pointers to functions which return integers, a special data type has been defined for use in the declarations, called Procedure.
| Base Data Type | Procedure |
|---|---|
| Example Declaration | Procedure proc; |
Process Handles
Process handles are data structures which uniquely identify an active process within a simulation. These structures are used by Pro package KPs, so that operations can be performed on processes. Process handles are actually data structures, and not integers or pointers. Therefore, they should not be cast into or stored in integer or pointer variables.
| Base Data Type | Prohandle |
|---|---|
| Example Declaration | Prohandle proh; |
SAR Buffer Handles
A Sar Buffer Handle is a data structure that uniquely identifies a Sar (Segmentation & Reassembly) buffer, an object that buffers sequences of packets, and can either split packets into segments, or reassemble the segments into packets. Sar buffers are created by a KP in the Sar package, which returns a Sar buffer handle for accessing the new buffer. Sar buffer handles are passed to most Sar package KPs, so that the KPs can operate on the identified Sar buffer. As with other handle data structures, Sar buffer handles should not be cast into, or assigned to, integers or pointers.
| Base Data Type | Sbhandle |
|---|---|
| Example Declaration | Sbhandle sbh; |