Unsupported utility APIs. More...

Static Public Member Functions
static void	sleep (const struct DDS_Duration_t &durationIn)
	Block the calling thread for the specified duration.

static void	spin (DDS_UnsignedLongLong spinCount)
	Performs the spin operation as many times as indicated.

static DDS_UnsignedLongLong	get_spin_per_microsecond ()
	Returns the number of spin operations to perform to wait 1 microsecond.

static DDS_Boolean	enable_heap_monitoring ()
	Starts monitoring the heap memory used by RTI Connext.

static void	disable_heap_monitoring ()
	Stops monitoring the heap memory used by RTI Connext.

static DDS_Boolean	pause_heap_monitoring ()
	Pauses heap monitoring.

static DDS_Boolean	resume_heap_monitoring ()
	Resumes heap monitoring.

static DDS_Boolean	take_heap_snapshot (const char *filename, DDS_Boolean print_details)
	Saves the current heap memory usage in a file.

Detailed Description

Unsupported utility APIs.

Unsupported APIs used in example code.

The static methods supplied by this class are used by the example code distributed with RTI Connext and generated by nddsgen. These methods are not supported by RTI.

Member Function Documentation

static void NDDSUtility::sleep ( const struct DDS_Duration_t & durationIn )

static

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.

Parameters

durationIn <<in>> Sleep duration.

MT Safety:: safe

Examples:: HelloWorld_publisher.cxx, and HelloWorld_subscriber.cxx.

static void NDDSUtility::spin ( DDS_UnsignedLongLong spinCount )

static

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.

Parameters

spinCount <<in>> Number of spin operations to perform.

static DDS_UnsignedLongLong NDDSUtility::get_spin_per_microsecond ( )

static

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().

Returns: Number of spin operations to wait 1 microsecond.

static DDS_Boolean NDDSUtility::enable_heap_monitoring ( )

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

Use this method only for debugging purposes, as 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: NDDSUtility::disable_heap_monitoring

static void NDDSUtility::disable_heap_monitoring ( )

static

Stops monitoring the heap memory used by RTI Connext.

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

See Also: NDDSUtility::enable_heap_monitoring

static DDS_Boolean NDDSUtility::pause_heap_monitoring ( )

static

Pauses heap monitoring.

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

Returns: DDS_BOOLEAN_TRUE if success. Otherwise, DDS_BOOLEAN_FALSE

See Also: NDDSUtility::resume_heap_monitoring

static DDS_Boolean NDDSUtility::resume_heap_monitoring ( )

static

Resumes heap monitoring.

Returns: DDS_BOOLEAN_TRUE if success. Otherwise, DDS_BOOLEAN_FALSE

See Also: NDDSUtility::pause_heap_monitoring

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

static

Saves the current heap memory usage in a file.

After NDDSUtility::enable_heap_monitoring 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:

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 not 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 NDDSUtility::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 method will print the details of every single outstanding heap allocation done by RTI Connext. For example:

block_id, timestamp, pool_alloc, pool_buffer_size, pool_buffer_count, topic_name, activity, alloc_method_name, type_name
12830, 1492838970, 104, MALLOC, 0, 0, PRESServiceRequest, PRESCstReaderCollator_new, RTIOsapiHeap_allocateStructure, struct REDAFastBufferPool

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.
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.
activity: Activity associated with the allocation or 'n/a' if it is not available.
alloc_method_name: The allocation RTI Connext method name.
type_name: The allocation typename.

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

Static Public Member Functions

Detailed Description

Member Function Documentation