Memory reclaim

Collaboration diagram for Memory reclaim:

Data Structures
struct	lttng_reclaim_handle
	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 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 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 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 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 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 channel memory reclaim operation identified by handle to complete.

Detailed Description

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

Reclaim of channel sub-buffers older than 40 seconds.

The channel memory reclaim operation behaviour depends on the configured event record loss mode of the 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 channel memory:

Immediate reclaim

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

   This function returns a memory reclaim operation handle (lttng_reclaim_handle).

2. 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().
3. Query the amount of reclaimed memory with lttng_reclaim_result_get_memory_size_bytes().
4. Destroy the memory reclaim operation handle with lttng_reclaim_handle_destroy().

Automatic reclaim

Use lttng_channel_set_automatic_memory_reclamation_policy() before creating the 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 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 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 channel.
LTTNG_RECLAIM_CHANNEL_MEMORY_STATUS_NOT_SUPPORTED	Memory reclamation is not supported for this channel.
LTTNG_RECLAIM_CHANNEL_MEMORY_STATUS_SESSION_NOT_FOUND	Session not found.
LTTNG_RECLAIM_CHANNEL_MEMORY_STATUS_CHANNEL_NOT_FOUND	Channel not found.

lttng_reclaim_handle_status

enum lttng_reclaim_handle_status

Return type of 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 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 channel use in order to free space.

This function only works with a user space 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 channel.
[in]	channel_name	Name of the targeted channel within session_name from which to reclaim memory.
[in]	domain	Tracing domain of the targeted 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 channel memory reclaim operation handle handle.

Parameters

[in]

handle

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