NDDSUtilityHeapMonitoring Class Reference

Heap Monitoring APIs. More...

Static Public Member Functions
static DDS_Boolean	enable ()
	Starts monitoring the heap memory used by RTI Connext. More...
static DDS_Boolean	enable (const NDDS_Utility_HeapMonitoringParams_t &params)
	Starts monitoring the heap memory used by RTI Connext. More...
static void	disable ()
	Stops monitoring the heap memory used by RTI Connext. More...
static DDS_Boolean	pause ()
	Pauses heap monitoring. More...
static DDS_Boolean	resume ()
	Resumes heap monitoring. More...
static DDS_Boolean	take_heap_snapshot (const char *filename, DDS_Boolean print_details)
	Saves the current heap memory usage in a file. More...

Detailed Description

Heap Monitoring APIs.

Member Function Documentation

enable() [1/2]

static DDS_Boolean NDDSUtilityHeapMonitoring::enable ( )

static

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 NDDSUtilityHeapMonitoring::take_heap_snapshot.

Use this method only for debugging purposes, since it may introduce a significant performance impact.

MT Safety:

UNSAFE. It is not safe to call this method while another thread may be simultaneously calling another heap-related method, including this one.

Returns

DDS_BOOLEAN_TRUE if success. Otherwise, DDS_BOOLEAN_FALSE

See also

NDDSUtilityHeapMonitoring::disable

enable() [2/2]

static DDS_Boolean NDDSUtilityHeapMonitoring::enable ( const NDDS_Utility_HeapMonitoringParams_t &  params )

static

Starts monitoring the heap memory used by RTI Connext.

Perfoms the same function as NDDSUtilityHeapMonitoring::enable except that it also provides the values in params. Those values will set the format used in the snapshot NDDSUtilityHeapMonitoring::take_heap_snapshot.

Returns

DDS_BOOLEAN_TRUE if success. Otherwise, DDS_BOOLEAN_FALSE

See also

NDDSUtilityHeapMonitoring::disable

disable()

static void NDDSUtilityHeapMonitoring::disable ( )

static

Stops monitoring the heap memory used by RTI Connext.

This method must be the last method called from RTI Connext.

See also

NDDSUtilityHeapMonitoring::enable

pause()

static DDS_Boolean NDDSUtilityHeapMonitoring::pause ( )

static

Pauses heap monitoring.

New memory allocations will not be monitored and they will not appear in the snapshot generated by NDDSUtilityHeapMonitoring::take_heap_snapshot.

Returns

DDS_BOOLEAN_TRUE if success. Otherwise, DDS_BOOLEAN_FALSE

See also

NDDSUtilityHeapMonitoring::resume

resume()

static DDS_Boolean NDDSUtilityHeapMonitoring::resume ( )

static

Resumes heap monitoring.

Returns

DDS_BOOLEAN_TRUE if success. Otherwise, DDS_BOOLEAN_FALSE

See also

NDDSUtilityHeapMonitoring::pause

take_heap_snapshot()

static DDS_Boolean NDDSUtilityHeapMonitoring::take_heap_snapshot ( const char *  filename, DDS_Boolean  print_details  )

static

Saves the current heap memory usage in a file.

After NDDSUtilityHeapMonitoring::enable is called, you may invoke this method 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:

Product Version: NDDSCORE_BUILD_6.0.0.0_20200316T123411Z_RTI_ENG                     Process virtual memory: 2552352768
Process physical memory: 16187392
Current heap usage: 10532131
High watermark: 10532131
Alloc count: 17634
Free count: 3518

• Process virtual memory: The amount of virtual memory in bytes taken by the process. This memory includes RTI Connext and non-RTI Connext memory.
• Process virtual memory: The amount of physical memory in bytes taken by the process.
• Current heap usage: The amount of heap memory in bytes used by the middleware. For Java and .NET APIs, this memory only accounts for unmanaged RTI Connext memory, not memory living in the managed heap.
• High watermark: The maximum amount of heap usage by RTI Connext since NDDSUtilityHeapMonitoring::enable was invoked.
• Alloc count: The number of invocations to malloc, realloc, or calloc operations done by RTI Connext.
• Free count: The number of invocations to the free operation done by RTI Connext.

After the previous summary, and only if you set the parameter print_details to DDS_BOOLEAN_TRUE, the method will print the details of every single outstanding heap allocation done by RTI Connext. For example:

block_id, timestamp, block_size, alloc_method_name, type_name, pool_alloc, pool_buffer_size, pool_buffer_count, topic_name, function_name, activity_context

23087, 1586943520, 16, RTIOsapiHeap_allocateArray, struct RTIEncapsulationInfo, MALLOC, 0, 0, PRESServiceRequest, PRESWriterHistoryDriver_new, "0X101175A,0X76DD63D7,0X984377BC:0X1C1{N=ShapeTypeParticipant,D=110}|CREATE Participant|ENABLE|:0X80000088{E=Pu,D=110}|CREATE Writer WITH TOPIC PRESServiceRequest"

• block_id: Block ID of the allocation. This number increases with every allocation.
• timestamp: Timestamp in UTC seconds corresponding to the time where the allocation was done.
• block_size: The number of bytes allocated.
• alloc_method_name: The allocation RTI Connext method name.
• type_name: The allocation typename.
• pool_alloc: Indicates if the heap allocation is a RTI Connext pool allocation (POOL) or a regular allocation (MALLOC).
• pool_buffer_size: For pool allocations, this number indicates the size of the elements in the pool in number of bytes. block_size is equal to (pool_buffer_size * pool_buffer_count).
• pool_buffer_count: For pool allocations, this number indicates the number of buffers allocated for the pool. block_size is equal to (pool_buffer_size * pool_buffer_count).
• topic_name: The topic name associated with the allocation or 'n/a' if it is not available.
• function_name: function name associated with the allocation or 'n/a' if it is not available.
• activity_context: Activity Context

Parameters

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.

Returns

DDS_BOOLEAN_TRUE if success. Otherwise, DDS_BOOLEAN_FALSE