Commit | Line | Data |
---|---|---|
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 | |
15 | extern "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 |
24 | struct lttng_destruction_handle; |
25 | ||
f16ab844 JG |
26 | /* |
27 | * Negative values indicate errors. Values >= 0 indicate success. | |
28 | */ | |
3e3665b8 | 29 | enum 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 |
46 | extern 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 |
63 | extern enum lttng_destruction_handle_status |
64 | lttng_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 |
82 | extern enum lttng_destruction_handle_status |
83 | lttng_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 |
110 | extern enum lttng_destruction_handle_status |
111 | lttng_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 |
134 | extern enum lttng_destruction_handle_status |
135 | lttng_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 */ |