Docs: document the session destruction handle API
[lttng-tools.git] / include / lttng / destruction-handle.h
CommitLineData
3e3665b8
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
25extern "C" {
26#endif
27
f16ab844
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 */
3e3665b8
JG
34struct lttng_destruction_handle;
35
f16ab844
JG
36/*
37 * Negative values indicate errors. Values >= 0 indicate success.
38 */
3e3665b8 39enum lttng_destruction_handle_status {
f16ab844 40 /* Generic error. */
3e3665b8 41 LTTNG_DESTRUCTION_HANDLE_STATUS_ERROR = -2,
f16ab844 42 /* Invalid parameters provided */
3e3665b8 43 LTTNG_DESTRUCTION_HANDLE_STATUS_INVALID = -1,
f16ab844 44 /* Success. */
3e3665b8 45 LTTNG_DESTRUCTION_HANDLE_STATUS_OK = 0,
f16ab844 46 /* Destruction operation completed successfully. */
3e3665b8 47 LTTNG_DESTRUCTION_HANDLE_STATUS_COMPLETED = 1,
f16ab844 48 /* Operation timed out. */
3e3665b8
JG
49 LTTNG_DESTRUCTION_HANDLE_STATUS_TIMEOUT = 2,
50};
51
f16ab844
JG
52/*
53 * Destroy an lttng_destruction_session handle.
54 * The handle should be discarded after this call.
55 */
3e3665b8
JG
56extern void lttng_destruction_handle_destroy(
57 struct lttng_destruction_handle *handle);
58
f16ab844
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 */
3e3665b8
JG
73extern enum lttng_destruction_handle_status
74lttng_destruction_handle_wait_for_completion(
75 struct lttng_destruction_handle *handle, int timeout_ms);
76
f16ab844
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 */
3e3665b8
JG
92extern enum lttng_destruction_handle_status
93lttng_destruction_handle_get_result(
94 const struct lttng_destruction_handle *handle,
95 enum lttng_error_code *result);
96
f16ab844
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 */
3e3665b8
JG
120extern enum lttng_destruction_handle_status
121lttng_destruction_handle_get_rotation_state(
122 const struct lttng_destruction_handle *handle,
123 enum lttng_rotation_state *rotation_state);
124
f16ab844
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 */
3e3665b8
JG
144extern enum lttng_destruction_handle_status
145lttng_destruction_handle_get_archive_location(
146 const struct lttng_destruction_handle *handle,
147 const struct lttng_trace_archive_location **location);
148
4da7eebd
JG
149#ifdef __cplusplus
150}
151#endif
152
3e3665b8 153#endif /* LTTNG_DESTRUCTION_HANDLE_H */
This page took 0.040429 seconds and 4 git commands to generate.