1/* 2 * Copyright 2022 Haiku, Inc. All rights reserved. 3 * Distributed under the terms of the MIT License. 4 * 5 * Authors: 6 * Leorize, leorize+oss@disroot.org 7 * 8 * Corresponds to: 9 * headers/private/shared/MemoryRingIO.h hrev54369 10 * src/kits/shared/MemoryRingIO.cpp hrev54369 11 */ 12 13 14/*! 15 \file MemoryRingIO.h 16 \ingroup support 17 \ingroup libshared 18 \brief Provides the BMemoryRingIO class. 19*/ 20 21 22/*! 23 \class BMemoryRingIO 24 \ingroup support 25 \ingroup libshared 26 \brief An implementation of a ring buffer with a BDataIO interface. 27 28 \since Haiku R1 29*/ 30 31 32/*! 33 \fn BMemoryRingIO::BMemoryRingIO(size_t size) 34 \brief Creates a new BMemoryRingIO object with the given buffer size. 35 36 Call InitCheck() to verify that the buffer has been successfully created. 37 38 \param size The initial size of the buffer. 39 40 \since Haiku R1 41 42 \sa SetSize() 43*/ 44 45 46/*! 47 \fn BMemoryRingIO::~BMemoryRingIO() 48 \brief Free up resources held by the object. 49 50 \since Haiku R1 51*/ 52 53 54/*! 55 \fn status_t BMemoryRingIO::InitCheck() const 56 \brief Whether the object has been initialized correctly. 57 58 \retval B_OK Everything is initialized. 59 \retval B_NO_INIT The internal buffer couldn't be created or the buffer 60 capacity is \c 0. 61 62 \since Haiku R1 63*/ 64 65 66/*! 67 \fn virtual ssize_t BMemoryRingIO::Read(void* buffer, size_t size) 68 \brief Reads data from the object into a buffer. 69 70 If the ring buffer is empty, this method blocks until some data is made 71 available. \c 0 is returned if \c size is \c 0 or the buffer is empty 72 and was set to have write disabled. 73 74 \return The amount of bytes read. 75 76 \retval B_BAD_VALUE \c buffer is \c NULL 77 78 \since Haiku R1 79 80 \sa SetWriteDisabled() 81*/ 82 83 84/*! 85 \fn virtual ssize_t BMemoryRingIO::Write(const void* buffer, size_t size) 86 \brief Writes data from a buffer to the object. 87 88 If the ring buffer is full, this method blocks until some space is made 89 available. 90 91 \return The amount of bytes written. If the ring buffer is filled or 92 \c size is \c 0, \c 0 will be returned. 93 94 \retval B_BAD_VALUE \c buffer is \c NULL 95 \retval B_READ_ONLY_DEVICE Writes to the buffer has been disabled. 96 97 \since Haiku R1 98 99 \sa SetWriteDisabled() 100*/ 101 102 103/*! 104 \fn status_t BMemoryRingIO::SetSize(size_t size) 105 \brief Change the ring buffer capacity. 106 107 \param size The new capacity for the ring buffer. This value will be 108 rounded up to the nearest power of two. The new capacity must be larger 109 or equal to BytesAvailable(). If set to \c 0 when there are no the bytes 110 available to be read, the buffer will be freed. 111 112 \retval B_OK The operation was successful. 113 \retval B_BAD_VALUE The new capacity is smaller than BytesAvailable(). 114 \retval B_NO_MEMORY Memory couldn't be allocated to grow/create the buffer. 115 The buffer remains unchanged. 116 117 \since Haiku R1 118 119 \sa BytesAvailable() for the amount of data to be read. 120*/ 121 122 123/*! 124 \fn void BMemoryRingIO::Clear() 125 \brief Discard all data in the object. 126 127 This method will discard all data within the buffer. However it does not 128 free the memory held by the buffer. If this is desired, use in combination 129 with SetSize() with \c 0 as the new capacity. 130 131 \since Haiku R1 132 133 \sa SetSize() for freeing memory held by the buffer, 134 or for growing the buffer's size. 135*/ 136 137 138/*! 139 \fn size_t BMemoryRingIO::BytesAvailable() 140 \brief Get the amount of data stored in the object. 141 142 \return The amount of bytes ready to be read from the object. 143 144 \since Haiku R1 145 146 \sa BufferSize() for the total buffer size. 147 \sa SpaceAvailable() for the amount of space left for writing in the object. 148*/ 149 150 151/*! 152 \fn size_t BMemoryRingIO::SpaceAvailable() 153 \brief Get the amount of space left in the object. 154 155 \return The remaining storage capacity of the object in bytes. 156 157 \since Haiku R1 158 159 \sa BufferSize() for the total buffer size. 160 \sa BytesAvailable() for the amount of data ready to be read. 161*/ 162 163 164/*! 165 \fn size_t BMemoryRingIO::BufferSize() 166 \brief Get the total capacity of the object. 167 168 \return The total capacity of the object in bytes. 169 170 \since Haiku R1 171 172 \sa SpaceAvailable() for the amount of space left for writing in the object. 173 \sa BytesAvailable() for the amount of data ready to be read. 174*/ 175 176 177/*! 178 \fn status_t BMemoryRingIO::WaitForRead(bigtime_t timeout = B_INFINITE_TIMEOUT) 179 \brief Wait for data to be available for reading. 180 181 This method will block the current thread until there's data ready to be 182 Read() from the object or until timeout has been reached. 183 184 \param timeout The minimum amount of time to wait in microseconds. If the 185 value is \c B_INFINITE_TIMEOUT, this method will not return until 186 data can be read from the object. 187 188 \retval B_OK There's data ready to be read. 189 \retval B_TIMED_OUT Timeout reached but no data has been made available. 190 \retval B_READ_ONLY_DEVICE The buffer has write disabled. 191 192 \sa Read() 193 \sa SetWriteDisabled() 194*/ 195 196 197/*! 198 \fn status_t BMemoryRingIO::WaitForWrite(bigtime_t timeout = B_INFINITE_TIMEOUT) 199 \brief Wait for space to be available for writing. 200 201 This method will block the current thread until there are storage space 202 available for a Write() operation or until timeout has been reached. 203 204 \param timeout The minimum amount of time to wait in microseconds. If the 205 value is \c B_INFINITE_TIMEOUT, this method will not return until 206 data can be written into the object. 207 208 \retval B_OK There's storage space to write to. 209 \retval B_TIMED_OUT Timeout reached but no additional storage space has 210 been made available. 211 \retval B_READ_ONLY_DEVICE The buffer has write disabled. 212 213 \sa Write() 214 \sa SetWriteDisabled() 215*/ 216 217 218/*! 219 \fn void BMemoryRingIO::SetWriteDisabled(bool disabled) 220 \brief Set whether writes to the ring buffer is disabled. 221 222 This method controls whether further writes to the ring buffer is allowed. 223 If writing is disabled, any further writes will error with 224 \c B_READ_ONLY_DEVICE, and read will no longer block on an empty buffer and 225 instead return \c 0. In addition, WaitForRead() and WaitForWrite() will 226 return \c B_READ_ONLY_DEVICE. 227 228 This method is usually used to notify the writer/reader of the pipe to not 229 write more and/or to wait for more data. 230 231 \param disabled Whether writes should be disabled. 232 233 \sa WriteDisabled() to see whether writes to the ring buffer is currently disabled. 234*/ 235 236 237/*! 238 \fn bool BMemoryRingIO::WriteDisabled() 239 \brief Indicates whether writes to the ring buffer is disabled. 240 241 This method indicates whether further writes to the ring buffer is allowed. 242 See SetWriteDisabled() for more information. 243 244 \sa SetWriteDisabled() to control whether writes to the ring buffer is disabled. 245 246 \return \c true if writes to the ring buffer is disabled, \c false if not. 247*/ 248