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   ///   - ErrorCode::NotEnoughMemory on exceeding MaxSize.
86   ///   - ErrorCode::Ok when we find a Buffer.
87   ///   - ErrorCode::QueueFinalizing or ErrorCode::AlreadyFinalized on
88   ///     a finalizing/finalized BufferQueue.
89   ErrorCode getBuffer(Buffer &Buf);
90 
91   /// Updates |Buf| to point to nullptr, with size 0.
92   ///
93   /// Returns:
94   ///   - ErrorCode::Ok when we successfully release the buffer.
95   ///   - ErrorCode::UnrecognizedBuffer for when this BufferQueue does not own
96   ///     the buffer being released.
97   ErrorCode releaseBuffer(Buffer &Buf);
98 
99   bool finalizing() const {
100     return __sanitizer::atomic_load(&Finalizing,
101                                     __sanitizer::memory_order_acquire);
102   }
103 
104   /// Returns the configured size of the buffers in the buffer queue.
105   size_t ConfiguredBufferSize() const { return BufferSize; }
106 
107   /// Sets the state of the BufferQueue to finalizing, which ensures that:
108   ///
109   ///   - All subsequent attempts to retrieve a Buffer will fail.
110   ///   - All releaseBuffer operations will not fail.
111   ///
112   /// After a call to finalize succeeds, all subsequent calls to finalize will
113   /// fail with ErrorCode::QueueFinalizing.
114   ErrorCode finalize();
115 
116   /// Applies the provided function F to each Buffer in the queue, only if the
117   /// Buffer is marked 'used' (i.e. has been the result of getBuffer(...) and a
118   /// releaseBuffer(...) operation).
119   template <class F> void apply(F Fn) {
120     __sanitizer::BlockingMutexLock G(&Mutex);
121     for (const auto &T : Buffers) {
122       if (std::get<1>(T))
123         Fn(std::get<0>(T));
124     }
125   }
126 
127   // Cleans up allocated buffers.
128   ~BufferQueue();
129 };
130 
131 } // namespace __xray
132 
133 #endif // XRAY_BUFFER_QUEUE_H
134