Commit | Line | Data |
---|---|---|
823a1989 JG |
1 | /* |
2 | * Copyright (C) 2019 - Jérémie Galarneau <jeremie.galarneau@efficios.com> | |
3 | * | |
4 | * This library is free software; you can redistribute it and/or modify it | |
5 | * under the terms of the GNU Lesser General Public License, version 2.1 only, | |
6 | * as published by the Free Software Foundation. | |
7 | * | |
8 | * This library is distributed in the hope that it will be useful, but WITHOUT | |
9 | * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or | |
10 | * FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License | |
11 | * for more details. | |
12 | * | |
13 | * You should have received a copy of the GNU Lesser General Public License | |
14 | * along with this library; if not, write to the Free Software Foundation, | |
15 | * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA | |
16 | */ | |
17 | ||
18 | #ifndef LTTNG_DESTRUCTION_HANDLE_H | |
19 | #define LTTNG_DESTRUCTION_HANDLE_H | |
20 | ||
21 | #include <lttng/rotation.h> | |
22 | #include <lttng/lttng-error.h> | |
23 | ||
24 | #ifdef __cplusplus | |
25 | extern "C" { | |
26 | #endif | |
27 | ||
77d772ea JG |
28 | /* |
29 | * Handle used to represent a specific instance of session destruction | |
30 | * operation. | |
31 | * | |
32 | * See lttng_destroy_session_ext() in lttng/session.h. | |
33 | */ | |
823a1989 JG |
34 | struct lttng_destruction_handle; |
35 | ||
77d772ea JG |
36 | /* |
37 | * Negative values indicate errors. Values >= 0 indicate success. | |
38 | */ | |
823a1989 | 39 | enum lttng_destruction_handle_status { |
77d772ea | 40 | /* Generic error. */ |
823a1989 | 41 | LTTNG_DESTRUCTION_HANDLE_STATUS_ERROR = -2, |
77d772ea | 42 | /* Invalid parameters provided */ |
823a1989 | 43 | LTTNG_DESTRUCTION_HANDLE_STATUS_INVALID = -1, |
77d772ea | 44 | /* Success. */ |
823a1989 | 45 | LTTNG_DESTRUCTION_HANDLE_STATUS_OK = 0, |
77d772ea | 46 | /* Destruction operation completed successfully. */ |
823a1989 | 47 | LTTNG_DESTRUCTION_HANDLE_STATUS_COMPLETED = 1, |
77d772ea | 48 | /* Operation timed out. */ |
823a1989 JG |
49 | LTTNG_DESTRUCTION_HANDLE_STATUS_TIMEOUT = 2, |
50 | }; | |
51 | ||
77d772ea JG |
52 | /* |
53 | * Destroy an lttng_destruction_session handle. | |
54 | * The handle should be discarded after this call. | |
55 | */ | |
823a1989 JG |
56 | extern void lttng_destruction_handle_destroy( |
57 | struct lttng_destruction_handle *handle); | |
58 | ||
77d772ea JG |
59 | /* |
60 | * Wait for the destruction of a session to complete. | |
61 | * | |
62 | * A negative timeout_ms value can be used to wait indefinitely. | |
63 | * | |
64 | * Returns LTTNG_DESTRUCTION_HANDLE_STATUS_COMPLETED if the session destruction | |
65 | * operation was completed. LTTNG_DESTRUCTION_HANDLE_STATUS_TIMEOUT is returned | |
66 | * to indicate that the wait timed out. | |
67 | * On error, one of the negative lttng_destruction_handle_status is returned. | |
68 | * | |
69 | * Note: This function returning a success status does not mean that | |
70 | * the destruction operation itself succeeded; it indicates that the _wait_ | |
71 | * operation completed successfully. | |
72 | */ | |
823a1989 JG |
73 | extern enum lttng_destruction_handle_status |
74 | lttng_destruction_handle_wait_for_completion( | |
75 | struct lttng_destruction_handle *handle, int timeout_ms); | |
76 | ||
77d772ea JG |
77 | /* |
78 | * Get the result of a session destruction operation. | |
79 | * | |
80 | * This function must be used on a session destruction handle which was | |
81 | * successfully waited on. | |
82 | * | |
83 | * Returns LTTNG_DESTRUCTION_HANDLE_STATUS_OK if the result of the session | |
84 | * destruction operation could be obtained. Check the value of 'result' to | |
85 | * determine if the destruction of the session completed successfully or not. | |
86 | * | |
87 | * On error, one of the negative lttng_destruction_handle_status is returned. | |
88 | * Returns LTTNG_DESTRUCTION_HANDLE_STATUS_INVALID if the session destruction | |
89 | * was not waited-on using the handle or if the arguments of the function are | |
90 | * invalid (e.g. NULL). | |
91 | */ | |
823a1989 JG |
92 | extern enum lttng_destruction_handle_status |
93 | lttng_destruction_handle_get_result( | |
94 | const struct lttng_destruction_handle *handle, | |
95 | enum lttng_error_code *result); | |
96 | ||
77d772ea JG |
97 | /* |
98 | * Get the status of the session rotation performed as part of the session's | |
99 | * destruction. | |
100 | * | |
101 | * A session will perform a final rotation if it was ever rotated over its | |
102 | * lifetime. If this happens, this function returns the state of the rotation | |
103 | * that was performed. | |
104 | * | |
105 | * This function must be used on a session destruction handle which was | |
106 | * successfully waited on. | |
107 | * | |
108 | * Returns LTTNG_DESTRUCTION_HANDLE_STATUS_OK if the state of the session | |
109 | * rotation could be obtained. Check the value of 'rotation_state' to | |
110 | * determine if the rotation of the session completed successfully or not. | |
111 | * | |
112 | * On error, one of the negative lttng_destruction_handle_status is returned. | |
113 | * Returns LTTNG_DESTRUCTION_HANDLE_STATUS_INVALID if the session destruction | |
114 | * was not waited-on using the handle or if the arguments of the function are | |
115 | * invalid (e.g. NULL). | |
116 | * | |
117 | * Note that if no rotation was performed, rotation_state will be set to | |
118 | * LTTNG_ROTATION_STATE_NO_ROTATION. | |
119 | */ | |
823a1989 JG |
120 | extern enum lttng_destruction_handle_status |
121 | lttng_destruction_handle_get_rotation_state( | |
122 | const struct lttng_destruction_handle *handle, | |
123 | enum lttng_rotation_state *rotation_state); | |
124 | ||
77d772ea JG |
125 | /* |
126 | * Get the location of the archive resulting from the rotation performed during | |
127 | * the session's destruction. | |
128 | * | |
129 | * This function must be used on a session destruction handle which was | |
130 | * successfully waited on and a session rotation must have been be completed | |
131 | * successfully in order for this call to succeed. | |
132 | * | |
133 | * The location returned remains owned by the session destruction handle. | |
134 | * | |
135 | * Returns LTTNG_DESTRUCTION_HANDLE_STATUS_OK if the location of the archive | |
136 | * resulting from the session rotation could be obtained. | |
137 | * | |
138 | * On error, one of the negative lttng_destruction_handle_status is returned. | |
139 | * Returns LTTNG_DESTRUCTION_HANDLE_STATUS_INVALID if the session destruction | |
140 | * was not waited-on using the handle, if no session rotation occurred as part | |
141 | * of the session's destruction, or if the arguments of the function are | |
142 | * invalid (e.g. NULL). | |
143 | */ | |
823a1989 JG |
144 | extern enum lttng_destruction_handle_status |
145 | lttng_destruction_handle_get_archive_location( | |
146 | const struct lttng_destruction_handle *handle, | |
147 | const struct lttng_trace_archive_location **location); | |
148 | ||
e7ccd6a0 JG |
149 | #ifdef __cplusplus |
150 | } | |
151 | #endif | |
152 | ||
823a1989 | 153 | #endif /* LTTNG_DESTRUCTION_HANDLE_H */ |