1 //===-- xray_buffer_queue.h ------------------------------------*- C++ -*-===//
3 // The LLVM Compiler Infrastructure
5 // This file is distributed under the University of Illinois Open Source
6 // License. See LICENSE.TXT for details.
8 //===----------------------------------------------------------------------===//
10 // This file is a part of XRay, a dynamic runtime instrumentation system.
12 // Defines the interface for a buffer queue implementation.
14 //===----------------------------------------------------------------------===//
15 #ifndef XRAY_BUFFER_QUEUE_H
16 #define XRAY_BUFFER_QUEUE_H
19 #include "sanitizer_common/sanitizer_atomic.h"
20 #include "sanitizer_common/sanitizer_mutex.h"
24 /// BufferQueue implements a circular queue of fixed sized buffers (much like a
25 /// freelist) but is concerned mostly with making it really quick to initialise,
26 /// finalise, and get/return buffers to the queue. This is one key component of
27 /// the "flight data recorder" (FDR) mode to support ongoing XRay function call
31 struct alignas(64) BufferExtents {
32 __sanitizer::atomic_uint64_t Size;
36 void *Buffer = nullptr;
38 BufferExtents* Extents;
43 // The managed buffer.
46 // This is true if the buffer has been returned to the available queue, and
47 // is considered "used" by another thread.
51 // Size of each individual Buffer.
57 __sanitizer::SpinMutex Mutex;
58 __sanitizer::atomic_uint8_t Finalizing;
60 // Pointers to buffers managed/owned by the BufferQueue.
63 // Pointer to the next buffer to be handed out.
66 // Pointer to the entry in the array where the next released buffer will be
70 // Count of buffers that have been handed out through 'getBuffer'.
74 enum class ErrorCode : unsigned {
82 static const char *getErrorString(ErrorCode E) {
86 case ErrorCode::NotEnoughMemory:
87 return "no available buffers in the queue";
88 case ErrorCode::QueueFinalizing:
89 return "queue already finalizing";
90 case ErrorCode::UnrecognizedBuffer:
91 return "buffer being returned not owned by buffer queue";
92 case ErrorCode::AlreadyFinalized:
93 return "queue already finalized";
95 return "unknown error";
98 /// Initialise a queue of size |N| with buffers of size |B|. We report success
99 /// through |Success|.
100 BufferQueue(size_t B, size_t N, bool &Success);
102 /// Updates |Buf| to contain the pointer to an appropriate buffer. Returns an
103 /// error in case there are no available buffers to return when we will run
104 /// over the upper bound for the total buffers.
107 /// - BufferQueue is not finalising.
110 /// - ErrorCode::NotEnoughMemory on exceeding MaxSize.
111 /// - ErrorCode::Ok when we find a Buffer.
112 /// - ErrorCode::QueueFinalizing or ErrorCode::AlreadyFinalized on
113 /// a finalizing/finalized BufferQueue.
114 ErrorCode getBuffer(Buffer &Buf);
116 /// Updates |Buf| to point to nullptr, with size 0.
119 /// - ErrorCode::Ok when we successfully release the buffer.
120 /// - ErrorCode::UnrecognizedBuffer for when this BufferQueue does not own
121 /// the buffer being released.
122 ErrorCode releaseBuffer(Buffer &Buf);
124 bool finalizing() const {
125 return __sanitizer::atomic_load(&Finalizing,
126 __sanitizer::memory_order_acquire);
129 /// Returns the configured size of the buffers in the buffer queue.
130 size_t ConfiguredBufferSize() const { return BufferSize; }
132 /// Sets the state of the BufferQueue to finalizing, which ensures that:
134 /// - All subsequent attempts to retrieve a Buffer will fail.
135 /// - All releaseBuffer operations will not fail.
137 /// After a call to finalize succeeds, all subsequent calls to finalize will
138 /// fail with ErrorCode::QueueFinalizing.
139 ErrorCode finalize();
141 /// Applies the provided function F to each Buffer in the queue, only if the
142 /// Buffer is marked 'used' (i.e. has been the result of getBuffer(...) and a
143 /// releaseBuffer(...) operation).
146 __sanitizer::SpinMutexLock G(&Mutex);
147 for (auto I = Buffers, E = Buffers + BufferCount; I != E; ++I) {
149 if (T.Used) Fn(T.Buff);
153 // Cleans up allocated buffers.
157 } // namespace __xray
159 #endif // XRAY_BUFFER_QUEUE_H