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

Classes
struct	rti::util::heap_monitoring::SnapshotOutputFormat_def
	Specify the format of the output of the snapshot. RTI Connext. More...

struct	rti::util::heap_monitoring::SnapshotContentFormat_def
	Bitmap used to decide which information of the snapshot will be displayed. More...

class	rti::util::heap_monitoring::HeapMonitoringParams
	Input parameters for enabling heap monitoring. They will be used for configuring the format of the snapshot. More...

Typedefs
typedef dds::core::safe_enum< SnapshotOutputFormat_def >	rti::util::heap_monitoring::SnapshotOutputFormat
	Specify the format of the output of the snapshot. More...

typedef dds::core::safe_enum< SnapshotContentFormat_def >	rti::util::heap_monitoring::SnapshotContentFormat
	Bitmap used to decide which information of the snapshot will be displayed. More...

Functions
bool	rti::util::heap_monitoring::enable ()
	Starts monitoring the heap memory used by RTI Connext. More...

bool	rti::util::heap_monitoring::enable (const HeapMonitoringParams &params)
	Starts monitoring the heap memory used by RTI Connext with params. More...

void	rti::util::heap_monitoring::disable ()
	Stops monitoring the heap memory used by RTI Connext. More...

bool	rti::util::heap_monitoring::pause ()
	Pauses heap monitoring. More...

bool	rti::util::heap_monitoring::resume ()
	Resumes heap monitoring. More...

bool	rti::util::heap_monitoring::take_snapshot (const std::string &filename, bool print_details=false)
	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 heap_monitoring::enable() is called, you may invoke heap_monitoring::take_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.

Typedef Documentation

◆ SnapshotOutputFormat

typedef dds::core::safe_enum<SnapshotOutputFormat_def> rti::util::heap_monitoring::SnapshotOutputFormat

Specify the format of the output of the snapshot.

See also: SnapshotOutputFormat_def

◆ SnapshotContentFormat

typedef dds::core::safe_enum<SnapshotContentFormat_def> rti::util::heap_monitoring::SnapshotContentFormat

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

See also: SnapshotContentFormat_def

Function Documentation

◆ enable() [1/2]

bool rti::util::heap_monitoring::enable ( )

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 heap_monitoring::take_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: true if success. Otherwise, false

See also: heap_monitoring::disable()

Note: This is a standalone function in the namespace rti::util::heap_monitoring

◆ enable() [2/2]

bool rti::util::heap_monitoring::enable ( const HeapMonitoringParams & params )

Starts monitoring the heap memory used by RTI Connext with params.

Perfoms the same function as heap_monitoring::enable() except that it also provides the values in params. Those values will set the format used in the snapshot heap_monitoring::take_snapshot().

Returns: true if success. Otherwise, false

See also: heap_monitoring::disable()

Note: This is a standalone function in the namespace rti::util::heap_monitoring

◆ disable()

void rti::util::heap_monitoring::disable ( )

Stops monitoring the heap memory used by RTI Connext.

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

See also: heap_monitoring::enable()

Note: This is a standalone function in the namespace rti::util::heap_monitoring

◆ pause()

bool rti::util::heap_monitoring::pause ( )

Pauses heap monitoring.

New memory allocations will not be monitored and they will not appear in the snapshot generated by heap_monitoring::take_snapshot().

Returns: true if success. Otherwise, false

See also: heap_monitoring::resume()

Note: This is a standalone function in the namespace rti::util::heap_monitoring

◆ resume()

bool rti::util::heap_monitoring::resume ( )

Resumes heap monitoring.

Returns: true if success. Otherwise, false

See also: heap_monitoring::pause()

Note: This is a standalone function in the namespace rti::util::heap_monitoring

◆ take_snapshot()

bool rti::util::heap_monitoring::take_snapshot	(	const std::string &	filename,
		bool	print_details = `false`
	)

Saves the current heap memory usage in a file.

After heap_monitoring::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:

<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 heap_monitoring::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 true, the method 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: true if success. Otherwise, false

Note: This is a standalone function in the namespace rti::util::heap_monitoring

Classes

Typedefs

Functions