op_stat_reg()
Abstract
Returns a handle that can be used to reference a node or module statistic (local or global) from within a process model.
Syntax
op_stat_reg (stat_name, stat_index, type)
| Argument | Type | Description |
|---|---|---|
group_dot_stat_name |
const char* |
group and name of statistic for which a handle is to be obtained, separated by a period. |
stat_index |
int |
numeric index of the statistic-of-interest, or OPC_STAT_INDEX_NONE if the statistic has no dimension. See Table 79 “Statistic Index Symbolic Constants“ on page 24. |
type |
int |
OPC_STAT_GLOBAL for a global statistic or OPC_STAT_LOCAL for a local statistic. See Table 80 “Statistic Type Symbolic Constants“ on page 24. |
Return Type
Stathandle
Statistic handle that can be used to call the KPs op_stat_write() and op_stat_write_t().
Example
/* register HTTP-related statistics. */
app_mgr_state_ptr->HTTP_NUM_PAGES = op_stat_reg("Client Http.Downloaded Pages",
OPC_STAT_INDEX_NONE, OPC_STAT_LOCAL);
app_mgr_state_ptr->HTTP_NUM_OBJECTS = op_stat_reg("Client Http.Downloaded Objects",
OPC_STAT_INDEX_NONE, OPC_STAT_LOCAL);
app_mgr_state_ptr->HTTP_ABORT_ACCOUNT =
op_stat_reg("Client Http.User Cancelled Connections", OPC_STAT_INDEX_NONE,
OPC_STAT_LOCAL);
/* The page response stat has been added recently to measure the time elapsed */
/* in completing the page request and getting its response. Earlier only the */
/* object response time was measured. */
app_mgr_state_ptr->HTTP_PAGE_RESPONSE_TIME =
op_stat_reg("Client Http.Page Response Time(sec)", OPC_STAT_INDEX_NONE,
OPC_STAT_LOCAL);
app_mgr_state_ptr->GLOBAL_HTTP_PAGE_RESP_TIME =
op_stat_reg("Http.Page Response Time (sec)", OPC_STAT_INDEX_NONE,
OPC_STAT_GLOBAL);
Details
This procedure is similar to op_stat_obj_reg(). The primary differences are that this procedure can be used only in a process module context and that it can register both local and global statistics.
The Simulation Kernel centrally administers global and local statistics. A group, name, index, type, and output vector are maintained for each statistic. The user specifies the group, name, index, and type of the statistic when it is first registered with op_stat_reg(). Subsequent calls to this KP with a group and name already registered “rendezvous” with the statistic created during the earlier registration and the same handle is returned. This allows multiple processes to access the same statistic, provided that they have some mechanism to synchronize on the name. Processes located within the same module can rendezvous on the same local statistic. Any process can rendezvous on the same global statistic.
Dimensioned statistics provide a bank of output statistics. A Stathandle refers to the element of the bank specified by the index. Undimensioned statistics require the symbolic constant OPC_STAT_INDEX_NONE to be used for the index value.
A typical example of a global statistic is for all the processes within a model to share one output vector to record the end-to-end delay values they are measuring. This is in contrast to each process recording its own output vector using a local statistic.
Registration of a statistic involves a search by name and group through the set of existing statistics. To improve performance, each user should register a statistic only once and cache the resulting statistic handle (i.e., in a state variable) for later use.
Purpose
Statistic registration provides a mechanism for multiple processes to share a common output vector in which to record simulation metrics. By using registration to obtain access to the statistic, processes need only coordinate on the name of the statistic. This has the particular advantage of easily avoiding conflicts between models that are developed independently. This function returns a statistic handle, which is required to write new values to the statistic with the KPs op_stat_write() and op_stat_write_t().
Errors
- Program Abort: Segmentation violation. (due to an invalid or malformed
stat_nameargument) - Recoverable Error: Unable to register [local|global] stat (
<stat_name>). (due to an undeclared statistic) - Recoverable Error: Unable to register stat (
<stat_name>). (due to a lack of available memory) - Program Abort: KP requires process context.
- Recoverable Error: Statistic index (
<stat_index>) is out-of-range.
Reference
- Use the KP op_stat_obj_reg() to access a statistic for any link, path, module or submodule object
- Use the KP op_stat_write() to write a value to an output statistic, tagged with the current simulation time
- Use the KP op_stat_write_t() to write a value to an output statistic, tagged with a specified simulation time
- Use the KP op_stat_scalar_write() to write a value to a scalar statistic