Collaboration diagram for Memory reclaim:

Data Structures
struct	lttng_reclaim_handle
	Event record channel memory reclaim operation handle (opaque type). More...

Enumerations
enum	lttng_reclaim_channel_memory_status { LTTNG_RECLAIM_CHANNEL_MEMORY_STATUS_OK , LTTNG_RECLAIM_CHANNEL_MEMORY_STATUS_ERROR , LTTNG_RECLAIM_CHANNEL_MEMORY_STATUS_INVALID_PARAMETER , LTTNG_RECLAIM_CHANNEL_MEMORY_STATUS_RECLAMATION_IN_PROGRESS , LTTNG_RECLAIM_CHANNEL_MEMORY_STATUS_NOT_SUPPORTED , LTTNG_RECLAIM_CHANNEL_MEMORY_STATUS_SESSION_NOT_FOUND , LTTNG_RECLAIM_CHANNEL_MEMORY_STATUS_CHANNEL_NOT_FOUND }
	Return type of lttng_reclaim_channel_memory(). More...

enum	lttng_reclaim_handle_status { LTTNG_RECLAIM_HANDLE_STATUS_OK , LTTNG_RECLAIM_HANDLE_STATUS_COMPLETED , LTTNG_RECLAIM_HANDLE_STATUS_TIMEOUT , LTTNG_RECLAIM_HANDLE_STATUS_INVALID , LTTNG_RECLAIM_HANDLE_STATUS_ERROR }
	Return type of event record channel memory reclaim handle functions. More...

Functions
enum lttng_reclaim_channel_memory_status	lttng_reclaim_channel_memory (const char session_name, const char channel_name, enum lttng_domain_type domain, uint64_t older_than_us, struct lttng_reclaim_handle **handle)
	Initiates an immediate memory reclaim operation for the event record channel named `channel_name` within the recording session named `session_name` and the tracing domain `domain`.

void	lttng_reclaim_handle_destroy (struct lttng_reclaim_handle *handle)
	Destroys the event record channel memory reclaim operation handle `handle`.

enum lttng_reclaim_handle_status	lttng_reclaim_handle_get_pending_subbuffer_count (const struct lttng_reclaim_handle handle, uint64_t count)
	Sets `*count` to the total number of sub-buffers pending reclamation from the event record channel memory reclaim operation identified by `handle`.

enum lttng_reclaim_handle_status	lttng_reclaim_handle_get_reclaimed_subbuffer_count (const struct lttng_reclaim_handle handle, uint64_t count)
	Sets `*count` to the total number of sub-buffers successfully reclaimed by the event record channel memory reclaim operation identified by `handle`.

enum lttng_reclaim_handle_status	lttng_reclaim_handle_wait_for_completion (struct lttng_reclaim_handle *handle, int timeout_ms)
	Waits for the event record channel memory reclaim operation identified by `handle` to complete.

Detailed Description

An event record channel memory reclaim operation makes it possible to free memory which the eligible sub-buffers of a user space event record channel use.

Reclaim of event record channel sub-buffers older than 40 seconds.

The event record channel memory reclaim operation behaviour depends on the configured event record loss mode of the event record channel:

Discard mode

Only reclaim sub-buffers that have been both delivered (completed and ready to be consumed) and consumed, since unconsumed data would be lost forever.

Overwrite mode

Reclaim any delivered sub-buffer, since old data will be overwritten anyway: no need to wait for consumption.

There are two ways to reclaim event record channel memory:

Immediate reclaim

Call lttng_reclaim_channel_memory() to initiate an immediate memory reclaim operation.

This function returns a memory reclaim operation handle (lttng_reclaim_handle).
Wait for the completion of the memory reclaim operation with lttng_reclaim_handle_wait_for_completion() and get its results with lttng_reclaim_handle_get_result().
Query the amount of reclaimed memory with lttng_reclaim_result_get_memory_size_bytes().
Destroy the memory reclaim operation handle with lttng_reclaim_handle_destroy().

Automatic reclaim

Use lttng_channel_set_automatic_memory_reclamation_policy() before creating the event record channel to enable an automatic memory reclaim.

See Automatic memory reclaim policy to learn more.

In both cases, you may specify a sub-buffer age threshold: only sub-buffers of which the age of the closing time is older than the threshold are eligible for a memory reclaim. Moreover, with some age threshold T:

If T > last stream activity age

The sub-buffers of which the age, at the moment of closing them, is greater than T are eligible for a memory reclaim.

If T < last stream activity age

All the sub-buffers are eligible.

The LTTng tracers flush for the targeted event record channel so that any open sub-buffer gets closed to become eligible.

You might want to use this feature in conjunction with the LTTNG_CHANNEL_PREALLOCATION_POLICY_ON_DEMAND buffer preallocation policy of the event record channel to also minimize initial memory usage.

See also: lttng-reclaim-memory(1); lttng-enable-channel(1)

Enumeration Type Documentation

◆ lttng_reclaim_channel_memory_status

enum lttng_reclaim_channel_memory_status

Return type of lttng_reclaim_channel_memory().

Error status enumerators have a negative value.

Enumerator
LTTNG_RECLAIM_CHANNEL_MEMORY_STATUS_OK	Success.
LTTNG_RECLAIM_CHANNEL_MEMORY_STATUS_ERROR	Error.
LTTNG_RECLAIM_CHANNEL_MEMORY_STATUS_INVALID_PARAMETER	Unsatisfied precondition.
LTTNG_RECLAIM_CHANNEL_MEMORY_STATUS_RECLAMATION_IN_PROGRESS	A memory reclamation request is already in progress for this event record channel.
LTTNG_RECLAIM_CHANNEL_MEMORY_STATUS_NOT_SUPPORTED	Memory reclamation is not supported for this event record channel.
LTTNG_RECLAIM_CHANNEL_MEMORY_STATUS_SESSION_NOT_FOUND	Session not found.
LTTNG_RECLAIM_CHANNEL_MEMORY_STATUS_CHANNEL_NOT_FOUND	Event record channel not found.

◆ lttng_reclaim_handle_status

enum lttng_reclaim_handle_status

Return type of event record channel memory reclaim handle functions.

Error status enumerators have a negative value.

Enumerator
LTTNG_RECLAIM_HANDLE_STATUS_OK	Success.
LTTNG_RECLAIM_HANDLE_STATUS_COMPLETED	Reclamation operation completed.
LTTNG_RECLAIM_HANDLE_STATUS_TIMEOUT	Timeout reached.
LTTNG_RECLAIM_HANDLE_STATUS_INVALID	Unsatisfied precondition.
LTTNG_RECLAIM_HANDLE_STATUS_ERROR	Other error.

Function Documentation

◆ lttng_reclaim_channel_memory()

enum lttng_reclaim_channel_memory_status lttng_reclaim_channel_memory	(	const char *	session_name,
		const char *	channel_name,
		enum lttng_domain_type	domain,
		uint64_t	older_than_us,
		struct lttng_reclaim_handle **	handle
	)

extern

Initiates an immediate memory reclaim operation for the event record channel named channel_name within the recording session named session_name and the tracing domain domain.

This function requests LTTng to immediately reclaim memory which the buffers of the targeted event record channel use in order to free space.

This function only works with a user space event record channel.

Use *handle to wait for the completion of the memory reclaim operation and to fetch its result.

Parameters

[in]	session_name	Name of the recording session which contains the targeted event record channel.
[in]	channel_name	Name of the targeted event record channel within `session_name` from which to reclaim memory.
[in]	domain	Tracing domain of the targeted event record channel.
[in]	older_than_us	Minimum age (µs) of buffered data to consider to reclaim memory. Set to 0 for no age constraint.
[out]	handle	On success, this function sets `handle` to a handle identifying this memory reclaim operation. May be `NULL`. Wait for the completion of this operation with lttng_reclaim_handle_wait_for_completion(). Destroy `handle` with lttng_reclaim_handle_destroy().

Return values

LTTNG_RECLAIM_CHANNEL_MEMORY_STATUS_OK	Success.
LTTNG_RECLAIM_CHANNEL_MEMORY_STATUS_ERROR	Error.
LTTNG_RECLAIM_CHANNEL_MEMORY_STATUS_INVALID_PARAMETER	Unsatisfied precondition.

Precondition

liblttng-ctl can connect to a session daemon.
session_name is not NULL.
session_name names an accessible recording session within the connected session daemon.
channel_name is not NULL.
domain is LTTNG_DOMAIN_UST, LTTNG_DOMAIN_JUL, LTTNG_DOMAIN_LOG4J, LTTNG_DOMAIN_LOG4J2, or LTTNG_DOMAIN_PYTHON.

◆ lttng_reclaim_handle_destroy()

void lttng_reclaim_handle_destroy ( struct lttng_reclaim_handle * handle )

extern

Destroys the event record channel memory reclaim operation handle handle.

Parameters

[in]

handle

Event record channel memory reclaim operation handle to destroy.

May be NULL.

◆ lttng_reclaim_handle_get_pending_subbuffer_count()

enum lttng_reclaim_handle_status lttng_reclaim_handle_get_pending_subbuffer_count	(	const struct lttng_reclaim_handle *	handle,
		uint64_t *	count
	)

extern

Sets *count to the total number of sub-buffers pending reclamation from the event record channel memory reclaim operation identified by handle.

Pending sub-buffers are sub-buffers that met the reclamation criteria but could not be immediately reclaimed because their data has not yet been consumed. These sub-buffers will be automatically reclaimed as they are consumed.

The pending sub-buffer count is available immediately after lttng_reclaim_channel_memory() returns successfully.

Parameters

[in]	handle	Handle of the event record channel memory reclaim operation from which to get the number of pending sub-buffers.
[out]	count	On success, this function sets `*count` to the number of sub-buffers pending reclamation.

Return values

LTTNG_RECLAIM_HANDLE_STATUS_OK	Success.
LTTNG_RECLAIM_HANDLE_STATUS_INVALID	Unsatisfied precondition.

Precondition

handle is not NULL.
count is not NULL.

◆ lttng_reclaim_handle_get_reclaimed_subbuffer_count()

enum lttng_reclaim_handle_status lttng_reclaim_handle_get_reclaimed_subbuffer_count	(	const struct lttng_reclaim_handle *	handle,
		uint64_t *	count
	)

extern

Sets *count to the total number of sub-buffers successfully reclaimed by the event record channel memory reclaim operation identified by handle.

The reclaimed sub-buffer count is available immediately after lttng_reclaim_channel_memory() returns successfully.

Parameters

[in]	handle	Handle of the event record channel memory reclaim operation from which to get the number of reclaimed sub-buffers.
[out]	count	On success, this function sets `*count` to the number of sub-buffers successfully reclaimed.

Return values

LTTNG_RECLAIM_HANDLE_STATUS_OK	Success.
LTTNG_RECLAIM_HANDLE_STATUS_INVALID	Unsatisfied precondition.

Precondition

handle is not NULL.
count is not NULL.

◆ lttng_reclaim_handle_wait_for_completion()

enum lttng_reclaim_handle_status lttng_reclaim_handle_wait_for_completion	(	struct lttng_reclaim_handle *	handle,
		int	timeout_ms
	)

extern

Waits for the event record channel memory reclaim operation identified by handle to complete.

If this function returns LTTNG_RECLAIM_HANDLE_STATUS_COMPLETED, then the memory reclaim operation identified by handle completed. This does not indicate whether the memory reclaim operation itself succeeded; use lttng_reclaim_handle_get_reclaimed_subbuffer_count() to get the reclaimed count.

Parameters

[in]	handle	Event record channel memory reclaim operation handle of which to wait for completion.
[in]	timeout_ms	Maximum time (milliseconds) to wait for the completion of the memory reclaim operation identified by `handle` before returning LTTNG_RECLAIM_HANDLE_STATUS_TIMEOUT, or `-1` to wait indefinitely.

Return values

LTTNG_RECLAIM_HANDLE_STATUS_COMPLETED	The memory reclaim operation identified by `handle` completed (with or without success).
LTTNG_RECLAIM_HANDLE_STATUS_INVALID	Unsatisfied precondition.
LTTNG_RECLAIM_HANDLE_STATUS_TIMEOUT	The function waited for the completion of the memory reclaim operation more than `timeout_ms` ms.
LTTNG_RECLAIM_HANDLE_STATUS_ERROR	Other error.

Precondition

handle is not NULL.

See also: lttng_reclaim_handle_get_reclaimed_subbuffer_count() – Returns the number of sub-buffers reclaimed.

Data Structures

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

◆ lttng_reclaim_channel_memory_status

◆ lttng_reclaim_handle_status

Function Documentation

◆ lttng_reclaim_channel_memory()

◆ lttng_reclaim_handle_destroy()

◆ lttng_reclaim_handle_get_pending_subbuffer_count()

◆ lttng_reclaim_handle_get_reclaimed_subbuffer_count()

◆ lttng_reclaim_handle_wait_for_completion()