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
131