Heap Monitoring

Monitor memory allocations done by the middleware on the native heap. More...

Data Structures
struct	NDDS_Utility_HeapMonitoringParams_t
	Input parameters for enabling heap monitoring. They will be used for configuring the format of the snapshot. More...

Macros
#define	NDDS_Utility_HeapMonitoringParams_INITIALIZER
	Static initializer for NDDS_Utility_HeapMonitoringParams_t. More...

Typedefs
typedef struct NDDS_Utility_HeapMonitoringParams_t	NDDS_Utility_HeapMonitoringParams_t
	Input parameters for enabling heap monitoring. They will be used for configuring the format of the snapshot. More...

Enumerations
enum	NDDS_Utility_HeapMonitoringSnapshotOutputFormat {   NDDS_UTILITY_HEAP_MONITORING_SNAPSHOT_OUTPUT_FORMAT_STANDARD ,   NDDS_UTILITY_HEAP_MONITORING_SNAPSHOT_OUTPUT_FORMAT_COMPRESSED }
	Specify the format of the output of the snapshot. RTI Connext. More...
enum	NDDS_Utility_HeapMonitoringSnapshotContentFormat {   NDDS_UTILITY_HEAP_MONITORING_SNAPSHOT_CONTENT_BIT_TOPIC ,   NDDS_UTILITY_HEAP_MONITORING_SNAPSHOT_CONTENT_BIT_FUNCTION ,   NDDS_UTILITY_HEAP_MONITORING_SNAPSHOT_CONTENT_BIT_ACTIVITY ,   NDDS_UTILITY_HEAP_MONITORING_SNAPSHOT_CONTENT_DEFAULT ,   NDDS_UTILITY_HEAP_MONITORING_SNAPSHOT_CONTENT_MINIMAL }
	Bitmap used to decide which information of the snapshot will be displayed. More...

Functions
DDS_Boolean	NDDS_Utility_enable_heap_monitoring (void)
	Starts monitoring the heap memory used by RTI Connext. More...
DDS_Boolean	NDDS_Utility_enable_heap_monitoring_w_params (const NDDS_Utility_HeapMonitoringParams_t *params)
	Starts monitoring the heap memory used by RTI Connext. More...
void	NDDS_Utility_disable_heap_monitoring (void)
	Stops monitoring the heap memory used by RTI Connext. More...
DDS_Boolean	NDDS_Utility_pause_heap_monitoring (void)
	Pauses heap monitoring. More...
DDS_Boolean	NDDS_Utility_resume_heap_monitoring (void)
	Resumes heap monitoring. More...
DDS_Boolean	NDDS_Utility_take_heap_snapshot (const char *filename, DDS_Boolean print_details)
	Saves the current heap memory usage in a file. More...

Detailed Description

Monitor memory allocations done by the middleware on the native heap.

RTI Connext allows you to monitor the memory allocations done by the middleware on the native heap. This feature can be used to analyze and debug unexpected memory growth.

After NDDS_Utility_enable_heap_monitoring is called, you may invoke NDDS_Utility_take_heap_snapshot 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.

Macro Definition Documentation

NDDS_Utility_HeapMonitoringParams_INITIALIZER

#define NDDS_Utility_HeapMonitoringParams_INITIALIZER

Static initializer for NDDS_Utility_HeapMonitoringParams_t.

Use this initializer to ensure that new objects do not have uninitialized contents.

struct NDDS_Utility_HeapMonitoringParams_t param = NDDS_Utility_HeapMonitoringParams_INITIALIZER; 

See also

NDDS_Utility_HeapMonitoringParams_t

Typedef Documentation

NDDS_Utility_HeapMonitoringParams_t

typedef struct NDDS_Utility_HeapMonitoringParams_t NDDS_Utility_HeapMonitoringParams_t

Input parameters for enabling heap monitoring. They will be used for configuring the format of the snapshot.

Enumeration Type Documentation

NDDS_Utility_HeapMonitoringSnapshotOutputFormat

enum NDDS_Utility_HeapMonitoringSnapshotOutputFormat

Specify the format of the output of the snapshot. RTI Connext.

Enumerator
NDDS_UTILITY_HEAP_MONITORING_SNAPSHOT_OUTPUT_FORMAT_STANDARD	The output of the snapshot will be in plain text.
NDDS_UTILITY_HEAP_MONITORING_SNAPSHOT_OUTPUT_FORMAT_COMPRESSED	The output of the snapshot will be compressed using Zlib techonology. The file can be uncompressed using zlib-flate.

NDDS_Utility_HeapMonitoringSnapshotContentFormat

enum NDDS_Utility_HeapMonitoringSnapshotContentFormat

Bitmap used to decide which information of the snapshot will be displayed.

Enumerator
NDDS_UTILITY_HEAP_MONITORING_SNAPSHOT_CONTENT_BIT_TOPIC	Add the topic to the snapshot of heap monitoring.
NDDS_UTILITY_HEAP_MONITORING_SNAPSHOT_CONTENT_BIT_FUNCTION	Add the function name to the snapshot of heap monitoring.
NDDS_UTILITY_HEAP_MONITORING_SNAPSHOT_CONTENT_BIT_ACTIVITY	Add the activity context to the snapshot of heap monitoring. The user can select the information that will be part of the activity context by using the API NDDS_Config_ActivityContext_set_attribute_mask.
NDDS_UTILITY_HEAP_MONITORING_SNAPSHOT_CONTENT_DEFAULT	Add all the optional attributes to the snapshot of heap monitoring.
NDDS_UTILITY_HEAP_MONITORING_SNAPSHOT_CONTENT_MINIMAL	Not add any optional attribute to the snapshot of heap monitoring.

Function Documentation

NDDS_Utility_enable_heap_monitoring()

DDS_Boolean NDDS_Utility_enable_heap_monitoring

(

void

)

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, since it may introduce a significant performance impact.

MT Safety:

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

Returns

DDS_BOOLEAN_TRUE if success. Otherwise, DDS_BOOLEAN_FALSE

See also

NDDS_Utility_disable_heap_monitoring

NDDS_Utility_enable_heap_monitoring_w_params()

DDS_Boolean NDDS_Utility_enable_heap_monitoring_w_params

(

const NDDS_Utility_HeapMonitoringParams_t *

params

)

Starts monitoring the heap memory used by RTI Connext.

Perfoms the same function as NDDS_Utility_enable_heap_monitoring except that it also provides the values in params. Those values will set the format used in the snapshot NDDS_Utility_take_heap_snapshot.

Returns

DDS_BOOLEAN_TRUE if success. Otherwise, DDS_BOOLEAN_FALSE

See also

NDDS_Utility_disable_heap_monitoring

NDDS_Utility_disable_heap_monitoring()

void NDDS_Utility_disable_heap_monitoring

(

void

)

Stops monitoring the heap memory used by RTI Connext.

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

See also

NDDS_Utility_enable_heap_monitoring

NDDS_Utility_pause_heap_monitoring()

DDS_Boolean NDDS_Utility_pause_heap_monitoring

(

void

)

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.

Returns

DDS_BOOLEAN_TRUE if success. Otherwise, DDS_BOOLEAN_FALSE

See also

NDDS_Utility_resume_heap_monitoring

NDDS_Utility_resume_heap_monitoring()

DDS_Boolean NDDS_Utility_resume_heap_monitoring

(

void

)

Resumes heap monitoring.

Returns

DDS_BOOLEAN_TRUE if success. Otherwise, DDS_BOOLEAN_FALSE

See also

NDDS_Utility_pause_heap_monitoring

NDDS_Utility_take_heap_snapshot()

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:

<P> 
                    Product Version: NDDSCORE_BUILD_6.0.0.0_20200316T123411Z_RTI_ENG 
                    Process virtual memory: 2552352768 
                    Process physical memory: 16187392 
                    Current application heap usage: 10532131 
                    Approximate total heap usage: 203331110 
                    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 application 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. This value does not include overhead memory allocations that are used by the Heap Monitoring utility. It therefore provides the heap usage that is used when Heap Monitoring is disabled and does not reflect the actual amount of memory that has been allocated by the middleware. That value is accounted for in 'Approximate total heap usage'.
• Approximate total heap usage: The amount of heap memory in bytes used by the middleware, including overhead allocations from the Heap Monitoring utility. When the Heap Monitoring utility is enabled, every allocation has an additional overhead number of bytes allocated so that the middleware can keep track of the meta-data that is output in the heap snapshots. This overhead is not accounted for in the 'Current application heap usage' summary field, but is included in this field. 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 NDDS_Utility_enable_heap_monitoring 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 function will print the details of every single outstanding heap allocation done by RTI Connext. For example:

<P> 
                    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{Name=ShapeTypeParticipant,Domain=110}|CREATE Participant|ENABLE|:0X80000088{Entity=Pu,Domain=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