RTI Connext C API
Version 5.3.1
|
Unsupported APIs used by examples in the RTI Connext distribution as well as in rtiddsgen-generated examples. More...
Data Structures | |
struct | NDDS_Utility |
Unsupported utility APIs. More... | |
Functions | |
void | NDDS_Utility_sleep (const struct DDS_Duration_t *durationIn) |
Block the calling thread for the specified duration. | |
void | NDDS_Utility_spin (DDS_UnsignedLongLong spinCount) |
Performs the spin operation as many times as indicated. | |
DDS_UnsignedLongLong | NDDS_Utility_get_spin_per_microsecond () |
Returns the number of spin operations to perform to wait 1 microsecond. | |
DDS_Boolean | NDDS_Utility_enable_heap_monitoring () |
Starts monitoring the heap memory used by RTI Connext. | |
void | NDDS_Utility_disable_heap_monitoring () |
Stops monitoring the heap memory used by RTI Connext. | |
DDS_Boolean | NDDS_Utility_pause_heap_monitoring () |
Pauses heap monitoring. | |
DDS_Boolean | NDDS_Utility_resume_heap_monitoring () |
Resumes heap monitoring. | |
DDS_Boolean | NDDS_Utility_take_heap_snapshot (const char *filename, DDS_Boolean print_details) |
Saves the current heap memory usage in a file. | |
Unsupported APIs used by examples in the RTI Connext distribution as well as in rtiddsgen-generated examples.
void NDDS_Utility_sleep | ( | const struct DDS_Duration_t * | durationIn | ) |
Block the calling thread for the specified duration.
Note that the achievable resolution of sleep is OS-dependent. That is, do not assume that you can sleep for 1 nanosecond just because you can specify a 1-nanosecond sleep duration via the API. The sleep resolution on most operating systems is usually 10 ms or greater.
durationIn | <<in>> Sleep duration. Cannot be NULL. |
void NDDS_Utility_spin | ( | DDS_UnsignedLongLong | spinCount | ) |
Performs the spin operation as many times as indicated.
Spinning is the action of performing useless operations in a for loop in order to actively wait some time without yielding the CPU. Given that the resolution of sleep is in the order of ms, you can use this utility to wait times in the order of microseconds. To properly use this functionality, it is useful to measure previously the number of spin operations needed to wait the equivalent to 1 microsecond (using the utility get_spin_per_microsecond) and then compute the corresponding spin count desired.
spinCount | <<in>> Number of spin operations to perform. |
DDS_UnsignedLongLong NDDS_Utility_get_spin_per_microsecond | ( | ) |
Returns the number of spin operations to perform to wait 1 microsecond.
This utility can be used to measure how many spin operations must be performed to wait 1 microsecond. Since the time that it takes the CPU to perform 1 spin operation depends on the CPU frequency, it is recommended to use this utility before using spin().
DDS_Boolean NDDS_Utility_enable_heap_monitoring | ( | ) |
Starts monitoring the heap memory used by RTI Connext.
This function must be called before any other function in the RTI Connext library is called.
Once heap monitoring is enabled, you can take heap snapshots by using NDDS_Utility_take_heap_snapshot.
Use this function only for debugging purposes, as it may introduce a significant performance impact.
void NDDS_Utility_disable_heap_monitoring | ( | ) |
Stops monitoring the heap memory used by RTI Connext.
This function must be the last function called from RTI Connext.
DDS_Boolean NDDS_Utility_pause_heap_monitoring | ( | ) |
Pauses heap monitoring.
New memory allocations will not be monitored and they will not appear in the snapshot generated by NDDS_Utility_take_heap_snapshot.
DDS_Boolean NDDS_Utility_resume_heap_monitoring | ( | ) |
Resumes heap monitoring.
DDS_Boolean NDDS_Utility_take_heap_snapshot | ( | const char * | filename, |
DDS_Boolean | print_details | ||
) |
Saves the current heap memory usage in a file.
After NDDS_Utility_enable_heap_monitoring is called, you may invoke this function periodically to save the current heap memory usage to a file.
By comparing two snapshots, you can tell if new memory has been allocated and in many cases where. This is why this operation can be used to debug unexpected memory growth.
The format of a snapshot is as follows:
First, there is a memory usage summary like this:
After the previous summary, and only if you set the parameter print_details to DDS_BOOLEAN_TRUE, the function will print the details of every single outstanding heap allocation done by RTI Connext. For example:
filename | <<in>>. Name of file in which to store the snapshot. |
print_details | <<in>>. Indicates if the snapshot will contain only the memory usage summary or the details of the individual allocations. |