include/lttng/destruction-handle.h

   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
  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  */
  34 struct lttng_destruction_handle;
  35
  36 /*
  37  * Negative values indicate errors. Values >= 0 indicate success.
  38  */
  39 enum lttng_destruction_handle_status {
  40         /* Generic error. */
  41         LTTNG_DESTRUCTION_HANDLE_STATUS_ERROR = -2,
  42         /* Invalid parameters provided */
  43         LTTNG_DESTRUCTION_HANDLE_STATUS_INVALID = -1,
  44         /* Success. */
  45         LTTNG_DESTRUCTION_HANDLE_STATUS_OK = 0,
  46         /* Destruction operation completed successfully. */
  47         LTTNG_DESTRUCTION_HANDLE_STATUS_COMPLETED = 1,
  48         /* Operation timed out. */
  49         LTTNG_DESTRUCTION_HANDLE_STATUS_TIMEOUT = 2,
  50 };
  51
  52 /*
  53  * Destroy an lttng_destruction_session handle.
  54  * The handle should be discarded after this call.
  55  */
  56 extern void lttng_destruction_handle_destroy(
  57                 struct lttng_destruction_handle *handle);
  58
  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  */
  73 extern enum lttng_destruction_handle_status
  74 lttng_destruction_handle_wait_for_completion(
  75                 struct lttng_destruction_handle *handle, int timeout_ms);
  76
  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  */
  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
  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  */
 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
 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  */
 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
 149 #ifdef __cplusplus
 150 }
 151 #endif
 152
 153 #endif /* LTTNG_DESTRUCTION_HANDLE_H */