event-rule: lttng_event_rule base object
[lttng-tools.git] / include / lttng / destruction-handle.h
CommitLineData
3e3665b8 1/*
ab5be9fa 2 * Copyright (C) 2019 Jérémie Galarneau <jeremie.galarneau@efficios.com>
3e3665b8 3 *
ab5be9fa 4 * SPDX-License-Identifier: LGPL-2.1-only
3e3665b8 5 *
3e3665b8
JG
6 */
7
8#ifndef LTTNG_DESTRUCTION_HANDLE_H
9#define LTTNG_DESTRUCTION_HANDLE_H
10
11#include <lttng/rotation.h>
12#include <lttng/lttng-error.h>
13
14#ifdef __cplusplus
15extern "C" {
16#endif
17
f16ab844
JG
18/*
19 * Handle used to represent a specific instance of session destruction
20 * operation.
21 *
22 * See lttng_destroy_session_ext() in lttng/session.h.
23 */
3e3665b8
JG
24struct lttng_destruction_handle;
25
f16ab844
JG
26/*
27 * Negative values indicate errors. Values >= 0 indicate success.
28 */
3e3665b8 29enum lttng_destruction_handle_status {
f16ab844 30 /* Generic error. */
3e3665b8 31 LTTNG_DESTRUCTION_HANDLE_STATUS_ERROR = -2,
f16ab844 32 /* Invalid parameters provided */
3e3665b8 33 LTTNG_DESTRUCTION_HANDLE_STATUS_INVALID = -1,
f16ab844 34 /* Success. */
3e3665b8 35 LTTNG_DESTRUCTION_HANDLE_STATUS_OK = 0,
f16ab844 36 /* Destruction operation completed successfully. */
3e3665b8 37 LTTNG_DESTRUCTION_HANDLE_STATUS_COMPLETED = 1,
f16ab844 38 /* Operation timed out. */
3e3665b8
JG
39 LTTNG_DESTRUCTION_HANDLE_STATUS_TIMEOUT = 2,
40};
41
f16ab844
JG
42/*
43 * Destroy an lttng_destruction_session handle.
44 * The handle should be discarded after this call.
45 */
3e3665b8
JG
46extern void lttng_destruction_handle_destroy(
47 struct lttng_destruction_handle *handle);
48
f16ab844
JG
49/*
50 * Wait for the destruction of a session to complete.
51 *
52 * A negative timeout_ms value can be used to wait indefinitely.
53 *
54 * Returns LTTNG_DESTRUCTION_HANDLE_STATUS_COMPLETED if the session destruction
55 * operation was completed. LTTNG_DESTRUCTION_HANDLE_STATUS_TIMEOUT is returned
56 * to indicate that the wait timed out.
57 * On error, one of the negative lttng_destruction_handle_status is returned.
58 *
59 * Note: This function returning a success status does not mean that
60 * the destruction operation itself succeeded; it indicates that the _wait_
61 * operation completed successfully.
62 */
3e3665b8
JG
63extern enum lttng_destruction_handle_status
64lttng_destruction_handle_wait_for_completion(
65 struct lttng_destruction_handle *handle, int timeout_ms);
66
f16ab844
JG
67/*
68 * Get the result of a session destruction operation.
69 *
70 * This function must be used on a session destruction handle which was
71 * successfully waited on.
72 *
73 * Returns LTTNG_DESTRUCTION_HANDLE_STATUS_OK if the result of the session
74 * destruction operation could be obtained. Check the value of 'result' to
75 * determine if the destruction of the session completed successfully or not.
76 *
77 * On error, one of the negative lttng_destruction_handle_status is returned.
78 * Returns LTTNG_DESTRUCTION_HANDLE_STATUS_INVALID if the session destruction
79 * was not waited-on using the handle or if the arguments of the function are
80 * invalid (e.g. NULL).
81 */
3e3665b8
JG
82extern enum lttng_destruction_handle_status
83lttng_destruction_handle_get_result(
84 const struct lttng_destruction_handle *handle,
85 enum lttng_error_code *result);
86
f16ab844
JG
87/*
88 * Get the status of the session rotation performed as part of the session's
89 * destruction.
90 *
91 * A session will perform a final rotation if it was ever rotated over its
92 * lifetime. If this happens, this function returns the state of the rotation
93 * that was performed.
94 *
95 * This function must be used on a session destruction handle which was
96 * successfully waited on.
97 *
98 * Returns LTTNG_DESTRUCTION_HANDLE_STATUS_OK if the state of the session
99 * rotation could be obtained. Check the value of 'rotation_state' to
100 * determine if the rotation of the session completed successfully or not.
101 *
102 * On error, one of the negative lttng_destruction_handle_status is returned.
103 * Returns LTTNG_DESTRUCTION_HANDLE_STATUS_INVALID if the session destruction
104 * was not waited-on using the handle or if the arguments of the function are
105 * invalid (e.g. NULL).
106 *
107 * Note that if no rotation was performed, rotation_state will be set to
108 * LTTNG_ROTATION_STATE_NO_ROTATION.
109 */
3e3665b8
JG
110extern enum lttng_destruction_handle_status
111lttng_destruction_handle_get_rotation_state(
112 const struct lttng_destruction_handle *handle,
113 enum lttng_rotation_state *rotation_state);
114
f16ab844
JG
115/*
116 * Get the location of the archive resulting from the rotation performed during
117 * the session's destruction.
118 *
119 * This function must be used on a session destruction handle which was
120 * successfully waited on and a session rotation must have been be completed
121 * successfully in order for this call to succeed.
122 *
123 * The location returned remains owned by the session destruction handle.
124 *
125 * Returns LTTNG_DESTRUCTION_HANDLE_STATUS_OK if the location of the archive
126 * resulting from the session rotation could be obtained.
127 *
128 * On error, one of the negative lttng_destruction_handle_status is returned.
129 * Returns LTTNG_DESTRUCTION_HANDLE_STATUS_INVALID if the session destruction
130 * was not waited-on using the handle, if no session rotation occurred as part
131 * of the session's destruction, or if the arguments of the function are
132 * invalid (e.g. NULL).
133 */
3e3665b8
JG
134extern enum lttng_destruction_handle_status
135lttng_destruction_handle_get_archive_location(
136 const struct lttng_destruction_handle *handle,
137 const struct lttng_trace_archive_location **location);
138
4da7eebd
JG
139#ifdef __cplusplus
140}
141#endif
142
3e3665b8 143#endif /* LTTNG_DESTRUCTION_HANDLE_H */
This page took 0.043117 seconds and 5 git commands to generate.