Returns either the first SpmiStatVals structure in a set of statistics or the next SpmiStatVals structure in a set of statistics and a decoded value based on the type of data value extracted from the data field of an SpmiStatVals structure.
SPMI Library (libSpmi.a)
struct SpmiStatVals*SpmiNextValue( StatSet, StatVal, value) struct SpmiStatSet *StatSet; struct SpmiStatVals *StatVal; float *value;
Instead of issuing subroutine calls to SpmiFirstVals Subroutine / SpmiNextVals Subroutine (to get the first or next SpmiStatVals structure) followed by calls to SpmiGetValue (to get the decoded value from the SpmiStatVals structure), the SpmiNextValue subroutine returns both in one call. This subroutine call returns a pointer to the first SpmiStatVals structure belonging to the StatSet parameter if the StatVal parameter is NULL. If the StatVal parameter is not NULL, the next SpmiStatVals structure is returned, taking the structure identified by the StatVal parameter as the current structure. The data value corresponding to the returned SpmiStatVals structure is decoded and returned in the field pointed to by the value argument. In decoding the data value, the subroutine does the following:
Note: This subroutine call should only be issued after an SpmiGetStatSet Subroutine has been issued against the statset.
Specifies a pointer to a valid structure of type SpmiStatSet as created by the SpmiCreateStatSet Subroutine call.
Specifies either a NULL pointer or a pointer to a valid structure of type SpmiStatVals as created by the SpmiPathAddSetStat Subroutine call or returned by a previous SpmiNextValue subroutine call. If StatVal is NULL, then the first SpmiStatVals pointer belonging to the set of statistics pointed to by StatSet is returned.
valueA pointer used to return a decoded value based on the type of data value extracted from the data field of the returned SpmiStatVals structure.
The SpmiNextValue subroutine returns a pointer to a SpmiStatVals structure if successful. If unsuccessful, the subroutine returns a NULL value.
If the StatVal parameter is:
The first SpmiStatVals structure belonging to the StatSet parameter is returned.
The next SpmiStatVals structure after the structure identified by the StatVal parameter is returned and the value parameter is used to return a decoded value based on the type of data value extracted from the data field of the returned SpmiStatVals structure.
All SPMI subroutines use external variables to provide error information. To access these variables, an application program must define the following external variables:
If the subroutine returns without an error, the SpmiErrno variable is set to 0 and the SpmiErrmsg character array is empty. If an error is detected, the SpmiErrno variable returns an error code, as defined in the sys/Spmidef.h file, and the SpmiErrmsg variable contains text, in English, explaining the cause of the error. See the List of SPMI Error Codes for more information.
The SpmiNextValue subroutine maintains internal state information so that retrieval of the next data value from a statset can be done without traversing linked lists of data structures. The stats information is kept separate for each process, but is shared by all threads of a process.
If the subroutine is accessed from multiple threads, the state information is useless and the performance advantage is lost. The same is true if the program is simultaneously accessing two or more statsets. To benefit from the performance advantage of the SpmiNextValue subroutine, a program should retrieve all values in order from one stat set before retrieving values from the next statset.
The implementation of the subroutine allows a program to retrieve data values beginning at any point in the statset if the SpmiStatVals pointer is known. Doing so will cause a linked list traversal. If subsequent invocations of SpmiNextValue uses the value returned from the first and following invocation as their second argument, the traversal of the link list can be avoided.
It should be noted that the value returned by a successful SpmiNextValue invocation is always the pointer to the SpmiStatVals structure whose data value is decoded and returned in the value argument.
|/usr/include/sys/Spmidef.h||Declares the subroutines, data structures, handles, and macros that an application program can use to access the SPMI.|
For related information, see: