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 <cstdint>
21 #include <memory>
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 of each individual Buffer.
40   size_t BufferSize;
41 
42   // We use a bool to indicate whether the Buffer has been used in this
43   // freelist implementation.
44   std::unique_ptr<std::tuple<Buffer, bool>[]> Buffers;
45   size_t BufferCount;
46 
47   __sanitizer::SpinMutex Mutex;
48   __sanitizer::atomic_uint8_t Finalizing;
49 
50   // Pointers to buffers managed/owned by the BufferQueue.
51   std::unique_ptr<void *[]> OwnedBuffers;
52 
53   // Pointer to the next buffer to be handed out.
54   std::tuple<Buffer, bool> *Next;
55 
56   // Pointer to the entry in the array where the next released buffer will be
57   // placed.
58   std::tuple<Buffer, bool> *First;
59 
60   // Count of buffers that have been handed out through 'getBuffer'.
61   size_t LiveBuffers;
62 
63 public:
64   enum class ErrorCode : unsigned {
65     Ok,
66     NotEnoughMemory,
67     QueueFinalizing,
68     UnrecognizedBuffer,
69     AlreadyFinalized,
70   };
71 
72   static const char *getErrorString(ErrorCode E) {
73     switch (E) {
74     case ErrorCode::Ok:
75       return "(none)";
76     case ErrorCode::NotEnoughMemory:
77       return "no available buffers in the queue";
78     case ErrorCode::QueueFinalizing:
79       return "queue already finalizing";
80     case ErrorCode::UnrecognizedBuffer:
81       return "buffer being returned not owned by buffer queue";
82     case ErrorCode::AlreadyFinalized:
83       return "queue already finalized";
84     }
85     return "unknown error";
86   }
87 
88   /// Initialise a queue of size |N| with buffers of size |B|. We report success
89   /// through |Success|.
90   BufferQueue(size_t B, size_t N, bool &Success);
91 
92   /// Updates |Buf| to contain the pointer to an appropriate buffer. Returns an
93   /// error in case there are no available buffers to return when we will run
94   /// over the upper bound for the total buffers.
95   ///
96   /// Requirements:
97   ///   - BufferQueue is not finalising.
98   ///
99   /// Returns:
100   ///   - ErrorCode::NotEnoughMemory on exceeding MaxSize.
101   ///   - ErrorCode::Ok when we find a Buffer.
102   ///   - ErrorCode::QueueFinalizing or ErrorCode::AlreadyFinalized on
103   ///     a finalizing/finalized BufferQueue.
104   ErrorCode getBuffer(Buffer &Buf);
105 
106   /// Updates |Buf| to point to nullptr, with size 0.
107   ///
108   /// Returns:
109   ///   - ErrorCode::Ok when we successfully release the buffer.
110   ///   - ErrorCode::UnrecognizedBuffer for when this BufferQueue does not own
111   ///     the buffer being released.
112   ErrorCode releaseBuffer(Buffer &Buf);
113 
114   bool finalizing() const {
115     return __sanitizer::atomic_load(&Finalizing,
116                                     __sanitizer::memory_order_acquire);
117   }
118 
119   /// Returns the configured size of the buffers in the buffer queue.
120   size_t ConfiguredBufferSize() const { return BufferSize; }
121 
122   /// Sets the state of the BufferQueue to finalizing, which ensures that:
123   ///
124   ///   - All subsequent attempts to retrieve a Buffer will fail.
125   ///   - All releaseBuffer operations will not fail.
126   ///
127   /// After a call to finalize succeeds, all subsequent calls to finalize will
128   /// fail with ErrorCode::QueueFinalizing.
129   ErrorCode finalize();
130 
131   /// Applies the provided function F to each Buffer in the queue, only if the
132   /// Buffer is marked 'used' (i.e. has been the result of getBuffer(...) and a
133   /// releaseBuffer(...) operation).
134   template <class F> void apply(F Fn) {
135     __sanitizer::SpinMutexLock G(&Mutex);
136     for (auto I = Buffers.get(), E = Buffers.get() + BufferCount; I != E; ++I) {
137       const auto &T = *I;
138       if (std::get<1>(T))
139         Fn(std::get<0>(T));
140     }
141   }
142 
143   // Cleans up allocated buffers.
144   ~BufferQueue();
145 };
146 
147 } // namespace __xray
148 
149 #endif // XRAY_BUFFER_QUEUE_H
150