include/lttng/destruction-handle.h

   1 /*
   2  * Copyright (C) 2019 Jérémie Galarneau <jeremie.galarneau@efficios.com>
   3  *
   4  * SPDX-License-Identifier: LGPL-2.1-only
   5  *
   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
  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  */
  24 struct lttng_destruction_handle;
  25
  26 /*
  27  * Negative values indicate errors. Values >= 0 indicate success.
  28  */
  29 enum lttng_destruction_handle_status {
  30         /* Generic error. */
  31         LTTNG_DESTRUCTION_HANDLE_STATUS_ERROR = -2,
  32         /* Invalid parameters provided */
  33         LTTNG_DESTRUCTION_HANDLE_STATUS_INVALID = -1,
  34         /* Success. */
  35         LTTNG_DESTRUCTION_HANDLE_STATUS_OK = 0,
  36         /* Destruction operation completed successfully. */
  37         LTTNG_DESTRUCTION_HANDLE_STATUS_COMPLETED = 1,
  38         /* Operation timed out. */
  39         LTTNG_DESTRUCTION_HANDLE_STATUS_TIMEOUT = 2,
  40 };
  41
  42 /*
  43  * Destroy an lttng_destruction_session handle.
  44  * The handle should be discarded after this call.
  45  */
  46 extern void lttng_destruction_handle_destroy(
  47                 struct lttng_destruction_handle *handle);
  48
  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  */
  63 extern enum lttng_destruction_handle_status
  64 lttng_destruction_handle_wait_for_completion(
  65                 struct lttng_destruction_handle *handle, int timeout_ms);
  66
  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  */
  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
  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  */
 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
 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  */
 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
 139 #ifdef __cplusplus
 140 }
 141 #endif
 142
 143 #endif /* LTTNG_DESTRUCTION_HANDLE_H */