Recording session destruction handle API

Collaboration diagram for Recording session destruction handle API:

Data Structures
struct	lttng_destruction_handle
	Recording session destruction handle (opaque type). More...

Enumerations
enum	lttng_destruction_handle_status {   LTTNG_DESTRUCTION_HANDLE_STATUS_OK , LTTNG_DESTRUCTION_HANDLE_STATUS_COMPLETED , LTTNG_DESTRUCTION_HANDLE_STATUS_TIMEOUT , LTTNG_DESTRUCTION_HANDLE_STATUS_INVALID ,   LTTNG_DESTRUCTION_HANDLE_STATUS_ERROR }
	Return type of recording session destruction handle fuctions. More...

Functions
void	lttng_destruction_handle_destroy (struct lttng_destruction_handle *handle)
	Destroys the recording session destruction handle handle.
enum lttng_destruction_handle_status	lttng_destruction_handle_get_archive_location (const struct lttng_destruction_handle *handle, const struct lttng_trace_archive_location **location)
	Sets *location to the location of the final trace chunk archive which the destruction of the recording session identified by handle created.
enum lttng_destruction_handle_status	lttng_destruction_handle_get_result (const struct lttng_destruction_handle *handle, enum lttng_error_code *result)
	Sets *result to the result of the recording session destruction operation identified by handle.
enum lttng_destruction_handle_status	lttng_destruction_handle_get_rotation_state (const struct lttng_destruction_handle *handle, enum lttng_rotation_state *rotation_state)
	Sets *rotation_state to the state of a final rotation operation which the destruction of the recording session identified by handle caused.
enum lttng_destruction_handle_status	lttng_destruction_handle_wait_for_completion (struct lttng_destruction_handle *handle, int timeout_ms)
	Waits for the recording session destruction operation identified by handle to complete.

Detailed Description

A recording session destruction handle represents a recording session destruction operation.

The main purposes of a recording session destruction handle is to:

• Wait for the completion of the recording session destruction operation with lttng_destruction_handle_wait_for_completion() and get whether or not it was successful with lttng_destruction_handle_get_result().
• Get the state of any recording session rotation which the recording session destruction operation caused with lttng_destruction_handle_get_rotation_state(), and the location of its trace chunk archive with lttng_destruction_handle_get_archive_location().

To destroy a recording session:

1. Call lttng_destroy_session_ext(), passing the name of the recording session to destroy.

   This function initiates a destruction operation, returning immediately.

   This function can set a pointer to a destruction handle so that you can wait for the completion of the operation. Without such a handle, you can't know when the destruction operation completes and whether or not it does successfully.

2. Call lttng_destruction_handle_wait_for_completion() to wait for the completion of the destruction operation.
3. Call lttng_destruction_handle_get_result() to get whether or not the destruction operation successfully completed.
4. If LTTng performed at least one rotation of the destroyed recording session, then call lttng_destruction_handle_get_rotation_state() to know whether or not the last rotation was successful and lttng_destruction_handle_get_archive_location() to get the location of its trace chunk archive.
5. Destroy the destruction handle with lttng_destruction_handle_destroy().

Enumeration Type Documentation

lttng_destruction_handle_status

enum lttng_destruction_handle_status

Return type of recording session destruction handle fuctions.

Error status enumerators have a negative value.

Enumerator
LTTNG_DESTRUCTION_HANDLE_STATUS_OK	Success.
LTTNG_DESTRUCTION_HANDLE_STATUS_COMPLETED	Recording session destruction operation completed.
LTTNG_DESTRUCTION_HANDLE_STATUS_TIMEOUT	Timeout reached.
LTTNG_DESTRUCTION_HANDLE_STATUS_INVALID	Unsatisfied precondition.
LTTNG_DESTRUCTION_HANDLE_STATUS_ERROR	Other error.

Function Documentation

lttng_destruction_handle_destroy()

void lttng_destruction_handle_destroy ( struct lttng_destruction_handle *  handle )

extern

Destroys the recording session destruction handle handle.

Parameters

[in]

handle

Recording session destruction handle to destroy. May be NULL.

lttng_destruction_handle_get_archive_location()

enum lttng_destruction_handle_status lttng_destruction_handle_get_archive_location ( const struct lttng_destruction_handle *  handle, const struct lttng_trace_archive_location **  location  )

extern

Sets *location to the location of the final trace chunk archive which the destruction of the recording session identified by handle created.

You must make sure that the destruction of the recording session caused a final, successful rotation with lttng_destruction_handle_get_rotation_state().

This function is only useful if LTTng performed at least one recording session rotation during the lifetime of the destroyed recording session.

Parameters

[in]	handle	Handle of the destruction operation of the recording session of which to get the location of the final trace chunk archive.
[out]	location	On success, this function sets *location to the location of the final trace chunk archive which the recording session destruction operation identified by handle created. *location is owned by handle.

Return values

LTTNG_DESTRUCTION_HANDLE_STATUS_OK	Success: *location is the location of the final trace chunk archive of the destroyed recording session.
LTTNG_DESTRUCTION_HANDLE_STATUS_INVALID	Unsatisfied precondition.
LTTNG_DESTRUCTION_HANDLE_STATUS_ERROR	Other error.

Precondition

• handle is not NULL.
• lttng_destruction_handle_get_rotation_state() set the #LTTNG_ROTATION_STATE_COMPLETED state for handle.
• location is not NULL.

See also

lttng_destruction_handle_get_rotation_state() – Get the state of the final rotation operation which a recording session destruction operation caused.

lttng_destruction_handle_get_result()

enum lttng_destruction_handle_status lttng_destruction_handle_get_result ( const struct lttng_destruction_handle *  handle, enum lttng_error_code *  result  )

extern

Sets *result to the result of the recording session destruction operation identified by handle.

You must successfully wait for the completion of the recording session destruction operation identified by handle with lttng_destruction_handle_wait_for_completion() before you call this function.

On success, *result is LTTNG_OK if the destruction operation was successful.

Parameters

[in]	handle	Handle of the recording session destruction operation of which to get the result.
[out]	result	On success, this function sets *result to the result of the recording session destruction operation identified by handle. *result is LTTNG_OK if the destruction operation was successful.

Return values

LTTNG_DESTRUCTION_HANDLE_STATUS_OK	Success: *result is the result of the recording session destruction operation identified by handle.
LTTNG_DESTRUCTION_HANDLE_STATUS_INVALID	Unsatisfied precondition.
LTTNG_DESTRUCTION_HANDLE_STATUS_ERROR	Other error.

Precondition

• handle is not NULL.
• You successfully waited for the completion of the recording session destruction operation identified by handle with lttng_destruction_handle_wait_for_completion().
• result is not NULL.

See also

lttng_destruction_handle_wait_for_completion() – Waits for a recording session destruction operation to complete.

lttng_destruction_handle_get_rotation_state()

enum lttng_destruction_handle_status lttng_destruction_handle_get_rotation_state ( const struct lttng_destruction_handle *  handle, enum lttng_rotation_state *  rotation_state  )

extern

Sets *rotation_state to the state of a final rotation operation which the destruction of the recording session identified by handle caused.

You must successfully wait for the completion of the recording session destruction operation identified by handle with lttng_destruction_handle_wait_for_completion() before you call this function.

This function is only useful if LTTng performed at least one recording session rotation during the lifetime of the destroyed recording session.

Parameters

[in]	handle	Handle of the destruction operation of the recording session of which to get the state of the final rotation operation.
[out]	rotation_state	On success, this function sets *rotation_state to the state of the final rotation operation which the recording session destruction operation identified by handle caused. *rotation_state is #LTTNG_ROTATION_STATE_NO_ROTATION if LTTng didn't perform any final recording session rotation.

Return values

LTTNG_DESTRUCTION_HANDLE_STATUS_OK	Success: *rotation_state is the state of the final rotation of the destroyed recording session.
LTTNG_DESTRUCTION_HANDLE_STATUS_INVALID	Unsatisfied precondition.
LTTNG_DESTRUCTION_HANDLE_STATUS_ERROR	Other error.

Precondition

• handle is not NULL.
• You successfully waited for the completion of the recording session destruction operation identified by handle with lttng_destruction_handle_wait_for_completion().
• rotation_state is not NULL.

See also

lttng_destruction_handle_get_archive_location() – Get the location of the trace chunk archive which a recording session destruction operation created.

lttng_destruction_handle_wait_for_completion()

enum lttng_destruction_handle_status lttng_destruction_handle_wait_for_completion ( struct lttng_destruction_handle *  handle, int  timeout_ms  )

extern

Waits for the recording session destruction operation identified by handle to complete.

If this function returns LTTNG_DESTRUCTION_HANDLE_STATUS_COMPLETED, then the recording session destruction operation identified by handle completed. This doesn't mean, however, that the destruction operation itself succeeded; use lttng_destruction_handle_get_result() to know this.

Parameters

[in]	handle	Recording session destruction handle which identifies the destruction operation of which to wait for completion.
[in]	timeout_ms	Maximum time (milliseconds) to wait for the completion of the recording session destruction operation identified by handle before returning LTTNG_DESTRUCTION_HANDLE_STATUS_TIMEOUT, or -1 to wait indefinitely.

Return values

LTTNG_DESTRUCTION_HANDLE_STATUS_COMPLETED	The recording session destruction operation identified by handle completed (with or without success).
LTTNG_DESTRUCTION_HANDLE_STATUS_INVALID	Unsatisfied precondition.
LTTNG_DESTRUCTION_HANDLE_STATUS_TIMEOUT	The function waited for the completion of the recording session destruction operation for more than timeout_ms ms.
LTTNG_DESTRUCTION_HANDLE_STATUS_ERROR	Other error.

Precondition

• handle is not NULL.

See also

lttng_destruction_handle_get_result() – Returns whether or not a recording session destruction operation succeeded.