contrib/compiler-rt/lib/xray/xray_buffer_queue.h

   1 //===-- xray_buffer_queue.h ------------------------------------*- C++ -*-===//
   2 //
   3 //                     The LLVM Compiler Infrastructure
   4 //
   5 // This file is distributed under the University of Illinois Open Source
   6 // License. See LICENSE.TXT for details.
   7 //
   8 //===----------------------------------------------------------------------===//
   9 //
  10 // This file is a part of XRay, a dynamic runtime instrumentation system.
  11 //
  12 // Defines the interface for a buffer queue implementation.
  13 //
  14 //===----------------------------------------------------------------------===//
  15 #ifndef XRAY_BUFFER_QUEUE_H
  16 #define XRAY_BUFFER_QUEUE_H
  17
  18 #include "sanitizer_common/sanitizer_atomic.h"
  19 #include "sanitizer_common/sanitizer_mutex.h"
  20 #include <deque>
  21 #include <unordered_set>
  22 #include <utility>
  23
  24 namespace __xray {
  25
  26 /// BufferQueue implements a circular queue of fixed sized buffers (much like a
  27 /// freelist) but is concerned mostly with making it really quick to initialise,
  28 /// finalise, and get/return buffers to the queue. This is one key component of
  29 /// the "flight data recorder" (FDR) mode to support ongoing XRay function call
  30 /// trace collection.
  31 class BufferQueue {
  32 public:
  33   struct Buffer {
  34     void *Buffer = nullptr;
  35     size_t Size = 0;
  36   };
  37
  38 private:
  39   size_t BufferSize;
  40
  41   // We use a bool to indicate whether the Buffer has been used in this
  42   // freelist implementation.
  43   std::deque<std::tuple<Buffer, bool>> Buffers;
  44   __sanitizer::BlockingMutex Mutex;
  45   std::unordered_set<void *> OwnedBuffers;
  46   __sanitizer::atomic_uint8_t Finalizing;
  47
  48 public:
  49   enum class ErrorCode : unsigned {
  50     Ok,
  51     NotEnoughMemory,
  52     QueueFinalizing,
  53     UnrecognizedBuffer,
  54     AlreadyFinalized,
  55   };
  56
  57   static const char *getErrorString(ErrorCode E) {
  58     switch (E) {
  59     case ErrorCode::Ok:
  60       return "(none)";
  61     case ErrorCode::NotEnoughMemory:
  62       return "no available buffers in the queue";
  63     case ErrorCode::QueueFinalizing:
  64       return "queue already finalizing";
  65     case ErrorCode::UnrecognizedBuffer:
  66       return "buffer being returned not owned by buffer queue";
  67     case ErrorCode::AlreadyFinalized:
  68       return "queue already finalized";
  69     }
  70     return "unknown error";
  71   }
  72
  73   /// Initialise a queue of size |N| with buffers of size |B|. We report success
  74   /// through |Success|.
  75   BufferQueue(size_t B, size_t N, bool &Success);
  76
  77   /// Updates |Buf| to contain the pointer to an appropriate buffer. Returns an
  78   /// error in case there are no available buffers to return when we will run
  79   /// over the upper bound for the total buffers.
  80   ///
  81   /// Requirements:
  82   ///   - BufferQueue is not finalising.
  83   ///
  84   /// Returns:
  85   ///   - std::errc::not_enough_memory on exceeding MaxSize.
  86   ///   - no error when we find a Buffer.
  87   ///   - std::errc::state_not_recoverable on finalising BufferQueue.
  88   ErrorCode getBuffer(Buffer &Buf);
  89
  90   /// Updates |Buf| to point to nullptr, with size 0.
  91   ///
  92   /// Returns:
  93   ///   - ...
  94   ErrorCode releaseBuffer(Buffer &Buf);
  95
  96   bool finalizing() const {
  97     return __sanitizer::atomic_load(&Finalizing,
  98                                     __sanitizer::memory_order_acquire);
  99   }
 100
 101   /// Returns the configured size of the buffers in the buffer queue.
 102   size_t ConfiguredBufferSize() const { return BufferSize; }
 103
 104   /// Sets the state of the BufferQueue to finalizing, which ensures that:
 105   ///
 106   ///   - All subsequent attempts to retrieve a Buffer will fail.
 107   ///   - All releaseBuffer operations will not fail.
 108   ///
 109   /// After a call to finalize succeeds, all subsequent calls to finalize will
 110   /// fail with std::errc::state_not_recoverable.
 111   ErrorCode finalize();
 112
 113   /// Applies the provided function F to each Buffer in the queue, only if the
 114   /// Buffer is marked 'used' (i.e. has been the result of getBuffer(...) and a
 115   /// releaseBuffer(...) operation.
 116   template <class F> void apply(F Fn) {
 117     __sanitizer::BlockingMutexLock G(&Mutex);
 118     for (const auto &T : Buffers) {
 119       if (std::get<1>(T))
 120         Fn(std::get<0>(T));
 121     }
 122   }
 123
 124   // Cleans up allocated buffers.
 125   ~BufferQueue();
 126 };
 127
 128 } // namespace __xray
 129
 130 #endif // XRAY_BUFFER_QUEUE_H