rring

#pragma once
 
#include <cstring>
#include <mutex>
#include <new>
#include <tuple>
#include <vector>
 
#include <randolf/rring_bam>
 
namespace randolf {
 
  /*======================================================================*//**
  @brief
  Ring buffer implementation for 8-bit bytes that's resizeable and threadsafe,
  and the methods are designed to be efficient in various ways, including by
  supporting the transfer of multiple bytes in variable quantities.
 
  Data is stored internally as a @c char* array, but a few methods are provided
  to also support easy interoperability with @c std::vector objects since there
  are many scenarios where this can be helpful (and from the perspective of
  optimization, this eliminates the cumbersome need to utilize conversions
  between @c std::string and @c std::vector objects since, internally, we use
  direct access to/from @c std::vector objects).
 
  @par Use case
  Occasionally, ring buffers (a.k.a., circular buffers) are useful in specific
  situations because they provide better performance compared to other types of
  buffers, which either results in frequent allocations and deallocations of
  memory for transient-but-ordered portions of data or tracking sections of
  transient-but-ordered portions of data.  A ring buffer relies on a single
  allocation of memory, along with a few variables for tracking top and bottom
  positions plus a few other internals to ensure smooth and accurate usage.
 
  This class handles all of these details gracefully, and provides a thorough
  variety of clearly-documented methods that ensure consistency whilst handling
  the complexity of EoL sequences that may be 1 or 2 characters long and also
  differentiating between blank and NULL lines, all without causing significant
  increases in complexity in code.
 
  @par Conventions
  Lower-case letters "rb" are regularly used in partial example code to
  represent an instantiated rring object.
 
  An ASCIIZ string is a C-string (char* array) that includes a terminating null
  (0) character at the end.
 
  @par History
    - 2024-Nov-25 v1.00 Initial version
    - 2024-Dec-03 v1.00 Added @ref rring_bam structure integration
    - 2024-Dec-03 v1.00 Added @ref data_bam and related methods
  @version 1.00
  @author Randolf Richardson
  *///=========================================================================
  class rring {
    private:
      char*       __buffer;              // Pointer to buffer
      size_t      __size;                // Size of buffer
      size_t      __head        = 0;     // Head (beginning)
      size_t      __tail        = 0;     // Tail (end)
      bool        __wipe_policy = true;  // Destructor memory wipe-out policy
      std::mutex  __mutex;               // Used to add support for multiple threads
 
    public:
      /*======================================================================*//**
      @brief
      Instantiate an empty ring buffer (which can be re-sized or replaced later).
      *///=========================================================================
      rring() noexcept {
        __buffer = nullptr;
        __size   = 0;
      }; // -x- constructor rring -x-
 
      /*======================================================================*//**
      @brief
      Instantiate an empty ring buffer (which can be re-sized later).
      @exception std::bad_alloc When @c malloc() fails to allocate memory
      *///=========================================================================
      rring(
      /// Size of buffer
      const size_t buffer_size) {
        __buffer = (char*)malloc(buffer_size);
        if (__buffer == nullptr) throw std::bad_alloc();
        __size   = buffer_size;
      }; // -x- constructor rring -x-
 
      /*======================================================================*//**
      @brief
      Free internal memory resources, after clearing buffer's memory (if the policy
      indicates that it needs to be cleared).
      *///=========================================================================
      ~rring() noexcept {
        if (__buffer != nullptr) {
 
          // --------------------------------------------------------------------------
          // Overwrite buffer's memory with NULL if policy indicates it.
          // --------------------------------------------------------------------------
          if (__wipe_policy) while (__size > 0) __buffer[--__size] = '\0';
 
          // --------------------------------------------------------------------------
          // Free buffer's memory resource.
          // --------------------------------------------------------------------------
          free(__buffer);
 
        } // -x- if __buffer -x-
      }; // -x- destructor ~rring -x-
 
    private:
      /*======================================================================*//**
      @brief
      Calculate the number of available entries in the ring buffer.
      @returns Number of entries available
      @see get_available
      *///=========================================================================
      size_t __available() noexcept {
        return (__head < __tail) ? __tail - __head
                       : __size - (__head - __tail);
      } // -x- size_t __available -x-
 
      /*======================================================================*//**
      @brief
      Calculate the number of utilized entries in the ring buffer.
      @returns Number of entries utilized
      @see get_utilized
      *///=========================================================================
      size_t __utilized() noexcept {
        return (__head >= __tail) ? __head - __tail
                        : __size - (__tail - __head);
      } // -x- size_t __utilized -x-
 
    public:
      /*======================================================================*//**
      @brief
      Add one character to the unused portion of the internal ring buffer.
      @exception std::overflow_error If the amount of data exceeds the available
                                     free space in the ring buffer
      @returns The same rring object so as to facilitate stacking
      @see c_str
      @see peek
      @see peek_vector
      @see remove
      @see remove_vector
      *///=========================================================================
      rring* append(
      /// Data to add
      const char data) {
 
        // --------------------------------------------------------------------------
        // Add data to ring buffer.  If no data is needed, then skip all the mutex
        // locking overhead, etc., and return the empty string.
        // --------------------------------------------------------------------------
        {
          std::lock_guard<std::mutex> guard(__mutex);
          if (__available() == 0) throw std::overflow_error("Ring buffer if full");
          __buffer[__head] = data;            // Copy entry
          if (++__head >= __size) __head = 0; // Wrap-around
        }
 
        return this;
      } // -x- rring* append -x-
 
      /*======================================================================*//**
      @brief
      Add any number of characters that fit within the unused portion of the
      internal ring buffer.
      @exception std::length_error If data length is -2 or below
      @exception std::overflow_error If the amount of data exceeds the available
                                     free space in the ring buffer
      @returns The same rring object so as to facilitate stacking
      @see c_str
      @see peek
      @see remove
      *///=========================================================================
      rring* append(
      /// Data to add
      const char* data,
      /// Length of data (-1 = treat @c data as an ASCIIZ string)
      int len = -1) {
 
        // --------------------------------------------------------------------------
        // Syntax checks.
        // --------------------------------------------------------------------------
             if (len == -1) len = std::strlen(data);
        else if (len  < -1) throw std::length_error("Unrealistic data length of " + std::to_string(len));
 
        // --------------------------------------------------------------------------
        // Add data to ring buffer.  If no data is needed, then skip all the mutex
        // locking overhead, etc., and return the empty string.
        // --------------------------------------------------------------------------
        if (len > 0) {
          std::lock_guard<std::mutex> guard(__mutex);
          if (__available() < len) throw std::overflow_error("Amount of data (len=" + std::to_string(len) + ") exceeds available free space in ring buffer");
          for (int i = 0; i < len; i++) {
            __buffer[__head] = data[i];         // Copy entry
            if (++__head >= __size) __head = 0; // Wrap-around
          } // -x- for i -x-
        } // -x- if len -x-
 
        return this;
      } // -x- rring* append -x-
 
      /*======================================================================*//**
      @brief
      Add any number of characters that fit within the unused portion of the
      internal ring buffer.
      @exception std::length_error If data length is -2 or below
      @exception std::overflow_error If the amount of data exceeds the available
                                     free space in the ring buffer
      @returns The same rring object so as to facilitate stacking
      @see c_str
      @see peek
      @see remove
      *///=========================================================================
      rring* append(
      /// Data to add
      const std::vector<char> data,
      /// Length of data (-1 = treat @c data as an ASCIIZ string)
      int len = -1) {
 
        // --------------------------------------------------------------------------
        // Syntax checks.
        // --------------------------------------------------------------------------
             if (len == -1) len = data.size();
        else if (len  < -1) throw std::length_error("Unrealistic data length of " + std::to_string(len));
 
        // --------------------------------------------------------------------------
        // Add data to ring buffer.  If no data is needed, then skip all the mutex
        // locking overhead, etc., and return the empty string.
        // --------------------------------------------------------------------------
        if (len > 0) {
          std::lock_guard<std::mutex> guard(__mutex);
          if (__available() < len) throw std::overflow_error("Amount of data (len=" + std::to_string(len) + ") exceeds available free space in ring buffer");
          for (int i = 0; i < len; i++) {
            __buffer[__head] = data[i];         // Copy entry
            if (++__head >= __size) __head = 0; // Wrap-around
          } // -x- for i -x-
        } // -x- if len -x-
 
        return this;
      } // -x- rring* append -x-
 
      /*======================================================================*//**
      @brief
      Add any number of characters that fit within the unused portion of the
      internal ring buffer.
      @exception std::length_error If data length is -2 or below
      @exception std::overflow_error If the amount of data exceeds the available
                                     free space in the ring buffer
      @returns The same rring object so as to facilitate stacking
      @see c_str
      @see peek
      @see remove
      *///=========================================================================
      rring* append(
      /// Data to add
      const std::vector<unsigned char> data,
      /// Length of data (-1 = treat @c data as an ASCIIZ string)
      int len = -1) {
 
        // --------------------------------------------------------------------------
        // Syntax checks.
        // --------------------------------------------------------------------------
             if (len == -1) len = data.size();
        else if (len  < -1) throw std::length_error("Unrealistic data length of " + std::to_string(len));
 
        // --------------------------------------------------------------------------
        // Add data to ring buffer.  If no data is needed, then skip all the mutex
        // locking overhead, etc., and return the empty string.
        // --------------------------------------------------------------------------
        if (len > 0) {
          std::lock_guard<std::mutex> guard(__mutex);
          if (__available() < len) throw std::overflow_error("Amount of data (len=" + std::to_string(len) + ") exceeds available free space in ring buffer");
          for (int i = 0; i < len; i++) {
            __buffer[__head] = data[i];         // Copy entry
            if (++__head >= __size) __head = 0; // Wrap-around
          } // -x- for i -x-
        } // -x- if len -x-
 
        return this;
      } // -x- rring* append -x-
 
      /*======================================================================*//**
      @brief
      Array-style access to the utilized portion of the ring buffer's contents,
      which yields the same result as that of the @ref at() method.
 
      The first element is at index 0.
      @throws std::out_of_range if the index is out-of-range
      @returns char
      @see operator[]
      *///=========================================================================
      char at(
      /// Index of character to access (0 = first element; negative index values
      /// are calculated in reverse, starting with -1 as the final position)
      int index) {
        std::lock_guard<std::mutex> guard(__mutex);
 
        // --------------------------------------------------------------------------
        // Internal variables.
        // --------------------------------------------------------------------------
        int MAX = __utilized();
 
        // --------------------------------------------------------------------------
        // Syntax checks.
        // --------------------------------------------------------------------------
        if (index >= MAX || 0 - index > MAX) throw std::out_of_range("index (position=" + std::to_string(index) + ") falls outside of the utilized portion (length=" + std::to_string(MAX) + ") of the buffer");
 
        // --------------------------------------------------------------------------
        // Calculate character's position.
        // --------------------------------------------------------------------------
        index = index >= 0 ? __tail + index : __head + index;
        if (index >= __size) index -= __size;
 
        return __buffer[index];
      } // -x- char at -x-
 
      /*======================================================================*//**
      @brief
      Return the contents of the ring buffer as an ASCIIZ string.
      @post
      The string returned will need to be `free()`'d after it's no longer needed.
 
      @code{.cpp}
        #include <iostream>      // std::cout, std::cerr, std::endl, etc.
        #include <randolf/rring>
 
        int main(int argc, char *argv[]) {
          randolf::rring rb(1024);
          rb.append("This is an example.");
          char* c = rb.c_str();
          std::cout << "\"" << c << "\"" << std::endl;
          free(c);
          return EXIT_SUCCESS;
        } // -x- int main -x-
      @endcode
 
      @warning
      When using the @ref data parameter in a multi-threaded scenario, the amount
      of the memory needed should be set to the maximum size of this ring buffer to
      prevent unintended under-allocation resulting from a simultaneous increase
      in utilized ring buffer memory (caused by @ref set_size).
      @exception std::bad_alloc When @c malloc() fails to allocate memory
      @returns ASCIIZ string
      @see append
      @see peek
      @see remove
      @see remove_array
      *///=========================================================================
      char* c_str(
      /// Where to store the ASCIIZ string (including terminating zero, so it is
      /// imperative that `utilized() + 1` bytes be pre-allocated)@n
      /// @c nullptr = allocate the needed memory using @c malloc()
      char* data = nullptr) noexcept {
 
        // --------------------------------------------------------------------------
        // Internal variables.
        // --------------------------------------------------------------------------
        size_t len;
 
        // --------------------------------------------------------------------------
        // Generate ASCIIZ string.
        // --------------------------------------------------------------------------
        {
          std::lock_guard<std::mutex> guard(__mutex);
          len = __utilized();
          if (data == nullptr) data = (char*)malloc(len + 1);
          if (data == nullptr) throw std::bad_alloc();
          size_t t = __tail;
          for (int i = 0; i < len; i++) {
            data[i] = __buffer[t];    // Copy entry
            if (++t >= __size) t = 0; // Wrap-around
          } // -x- for i -x-
        }
        data[len] = '\0'; // Not "len - 1" because we already allocated "len + 1"
 
        return data;
      } // -x- char* c_str -x-
 
      /*======================================================================*//**
      @brief
      Returns a pointer to the underlying ring buffer's array.  The beginning of
      the array is not the same as where the data actually begins (and ends) within
      the buffer.
 
      @warning
      This is the live data, which should not be accessed or modified directly; use
      the @ref data_bam() and @ref data_bam_adjust() methods instead when there is
      a need to access or modify the backing array directly.
      @returns Pointer to buffer (not null terminated)
      @see get_available
      @see get_utilized
      @see set_size
      @qualifier ADVANCED
      *///=========================================================================
      char* data() noexcept {
        std::lock_guard<std::mutex> guard(__mutex);
        return __buffer;
      } // -x- char* data -x-
 
      /*======================================================================*//**
      @brief
      Returns the lengths and addresses of available memory.  There may be only one
      block of memory, or two, depending on whether the available memory straddles
      the boundary of the ring buffer.
 
      This is the nearest equivalent of the @ref data() methods provided in classes
      such as @c std::string and @c std::vector, but with the nuance of supporting
      the underpinnings of this ring buffer wherein the utilized portions may be
      stored at both the end and beginning of the buffer memory.
      @note
      The intention of this method is to provide an opportunity to directly update
      the contents of the ring buffer's data section in an efficient manner (e.g.,
      such as by reading file or socket data directly into memory without having to
      perform separate data copying operations, etc.).
      @warning
      Upon updating a portion of the available-data block, the @c head will also
      need to be updated accordingly, for which the @ref data_bam_adjust method is
      provided.
      @exception std::bad_alloc When @c malloc() fails to allocate memory
      @returns Pointer to @ref rring_bam structure
      @see data_bam_adjust
      @see get_available
      @see rring_bam
      @qualifier ADVANCED
      *///=========================================================================
      rring_bam* data_bam(
      /// Pointer to @ref rring_bam structure (that's already been allocated)@n
      /// @c nullptr (default) = allocate memory for this structure with @c malloc
      /// (which will need to be `free`'d when it's no longer needed)
      rring_bam* bam = nullptr) noexcept {
        std::lock_guard<std::mutex> guard(__mutex);
 
        // --------------------------------------------------------------------------
        // Internal variables.
        // --------------------------------------------------------------------------
        if (bam == nullptr) {
          bam = (rring_bam*)malloc(__size);
          if (bam == nullptr) throw std::bad_alloc();
        } // -x- if !bam -x-
 
        // --------------------------------------------------------------------------
        // Configure utilized data block pointer(s) and length(s).
        // --------------------------------------------------------------------------
        bam->block1        = __buffer + __tail;
        if (__head        >= __tail) { // Not wrapped
          bam->block1_size = __head - __tail;
          bam->block2      = nullptr;
          bam->block2_size = 0;
        } else { // Wrapped
          bam->block1_size = __size - __tail;
          bam->block2      = __size - __tail == 0 ? nullptr : __buffer;
          bam->block2_size = __head;
        } // -x- if __head -x-
 
        // --------------------------------------------------------------------------
        // Configure available data block pointer(s) and length(s).
        // --------------------------------------------------------------------------
        bam->avail1        = __buffer + __head;
        if (__head         < __tail) { // Not wrapped
          bam->avail1_size = __tail - __head;
          bam->avail2      = nullptr;
          bam->avail2_size = 0;
        } else { // Wrapped
          bam->avail1_size = __size - __head;
          bam->avail2      = __tail == 0 ? nullptr : __buffer;
          bam->avail2_size = __tail;
        } // -x- if __head -x-
 
        return bam;
      } // -x- rring_bam* data_bam -x-
 
      /*======================================================================*//**
      @brief
      Arbitrarily change the head and tail positions in the ring buffer.  This is
      intended for use in conjunction with appending data directly to the ring
      buffer after the @ref data_bam method.
      @exception std::overflow_error If either adjustment would result in causing
                                     an overflow
      @returns The same rring object so as to facilitate stacking
      @see data_bam
      @see get_available
      @see set_head
      @see set_tail
      @qualifier ADVANCED
      *///=========================================================================
      rring* data_bam_adjust(
      /// New internal head position
      size_t head,
      /// New internal tail position
      size_t tail = 0) {
 
        // --------------------------------------------------------------------------
        // Set new head and tail positions.
        // --------------------------------------------------------------------------
        {
          std::lock_guard<std::mutex> guard(__mutex);
          __head = head;
          __tail = tail;
        }
 
        return this;
      } // -x- rring* data_bam_adjust -x-
 
      /*======================================================================*//**
      @brief
      Reorganizes the utilized memory in the ring buffer memory by moving the tail
      to the beginning.  Defragmentation is completed using a custom-made algorithm
      that requires only a single pass.
      @see data_bam
      @see get_ascii_map
      @see resize
      *///=========================================================================
      rring* defragment(
      /// Whether to defrag when the utilized block isn't straddling the internal
      /// memory buffer boundary@n
      /// TRUE = always defragment (default) @n
      /// FALSE = only defragment if utilized block straddles memory boundary (this
      ///         favours reducing processor overhead if all that's wanted is to
      ///         have one block of memory to contend with in the BAM, hence it's
      ///         also what the @ref resize() method uses for better performance
      ///         overall because resizing most likely occurs when the need for CPU
      ///         cycles are more critical, so we're doing our part by reducing our
      ///         CPU load)
      const bool full = true) {
        {
          std::lock_guard<std::mutex> guard(__mutex);
 
          // --------------------------------------------------------------------------
          // Move data within ring buffer.
          // --------------------------------------------------------------------------
          if (!full && __tail > __head) return this; // No work to be done
          switch (__tail) { // Handle special cases
            case 1: // Buffer is 1 byte
              __buffer[0] = __buffer[__tail];
              __head = 1;
              __tail = 0;
              return this;
            case 0: // Buffer is empty
              __head = 0;
              __tail = 0;
            return this;
          } // -x- switch __tail -x-
 
          // --------------------------------------------------------------------------
          // Internal variables.
          // --------------------------------------------------------------------------
          char carry; // Used in swapping elements
          char last; // Only used if existing
          size_t len = __utilized();
 
          // --------------------------------------------------------------------------
          // Save last entry for remove-and-hold technique so that the array can be
          // treated as having an even quantity of elements.
          // --------------------------------------------------------------------------
          if (len && 1) { // Odd number detected
            last = __buffer[__tail];
            len--; // Adjust down to even number
          } // -x- if odd-len -x-
 
          // --------------------------------------------------------------------------
          // Swap characters.
          // --------------------------------------------------------------------------
          for (int i = 0; i < len; i++) { // i begins with 0 (even-len) or 1 (odd-len)
            carry = __buffer[__head]     ;       // Swap part 1:  Carry head
            __buffer[i] = __buffer[__head]; // Swap part 2:  Copy i into head
            __buffer[__head] = carry;       // Swap part 3:  Un-carry head into i
            if (++__head == __size) __head = 0; // Wrap-around
std::cout << "i=" << i << " __head=" << __head << " carry=" << carry << std::endl;
          } // -x- for i -x-
          __head = len;
          __tail = 0; // Reposition the tail
 
          // --------------------------------------------------------------------------
          // Restore last entry for remove-and-hold technique that makes it possible
          // for the array to be treated as having an even quantity of elements.
          // --------------------------------------------------------------------------
          if (len && 1) { // Odd number detected
            __buffer[__tail] = last;
          } // -x- if odd-len -x-
 
        }
        return this;
      } // -x- rring* defragment -x-
 
/*
56781234 Simple swap (fastest speed)
1   5
 2   6
  3   7
   4   8
12345678
 
5671234 Remove-and-hold last (fastest speed)
456123
1  4
 2  5
  3  6
1234567 Re-instate last
 
5671234 1.5 passes (slowest speed)
1  5
 2  6
  3  7
     47
    46
   45
1234567
 
5671234 Carry (medium speed)
1  4    5
 2  5   6
  3  67
1234567
*/
 
      /*======================================================================*//**
      @brief
      Discard data from the ring buffer.
      @returns Number of bytes of data that was discarded
      @see remove
      *///=========================================================================
      size_t discard(
      /// Number of bytes to discard@n
      /// -1 = all utilized data that remains will be discarded (default)
      int len = -1) noexcept {
        if (len == 0) return 0; // Do nothing
        size_t discarded;
        {
          std::lock_guard<std::mutex> guard(__mutex);
               if (len == -1) len = __size;
          else if (len  < -1) throw std::length_error("Unrealistic data length of " + std::to_string(len));
          discarded = __utilized();
 
          // --------------------------------------------------------------------------
          // Discard everything because len is greater than or equal to the amount of
          // data in the ring buffer.
          // --------------------------------------------------------------------------
          if (len >= discarded) { // Discard everything if len is too large
            __head = 0;
            __tail = 0;
            return len; // Return quantity that was actually discarded
          } // -x- if len -x-
 
          // --------------------------------------------------------------------------
          // Adjust __tail according to amount of data to discard.  Calculating this is
          // enormously faster than looping through the buffer.
          // --------------------------------------------------------------------------
          if (__head >= __tail || __size - __tail < len) { // Not wrapping, so adjustment is easy
            __tail += len;
          } else { // Wrapping, so change tail to discard size minus what's discarded from the end
            __tail = len - (__size - __tail);
          } // -x- if __head -x-
        }
        return discarded - len; // Return quantity that was actually discarded
 
      } // -x- int discard -x-
 
      /*======================================================================*//**
      @brief
      Indicates whether the ring buffer is empty.
      @returns TRUE = empty@nFALSE = not empty
      @see get_available
      @see get_utilized
      @see set_size
      *///=========================================================================
      bool empty() noexcept {
        std::lock_guard<std::mutex> guard(__mutex);
        return __head == __tail;
      } // -x- bool empty -x-
 
      /*======================================================================*//**
      @brief
      Obtains a one-line ASCII depiction of a map of the ring buffer's memory
      usage, wherein the utilized and available portions are represented by the `|`
      (pipe) and '.' (period) characters, respectively (these characters are
      configurable and can include multiple characters, which is particularly
      useful for text-mode console output in a Linux shell in which ANSI codes may
      be used to present these characters in different colours).
      @exception std::length_error If length is -2 or below
      @returns One-line ASCII depiction of ring buffer's memory map
      @see get_available
      @see get_head
      @see get_tail
      @see get_utilized
      *///=========================================================================
      std::string get_ascii_map(
      /// Desired size of ASCII map@n
      /// -1 = Use size of ring buffer
      int len = 65,
      /// Character(s) representing utilized entries
      const std::string u = "|",
      /// Character(s) representing available entries
      const std::string a = ".") noexcept {
 
        // --------------------------------------------------------------------------
        // Internal variables, which will be copied .
        // --------------------------------------------------------------------------
        double head;
        double tail;
        double size;
        {
          std::lock_guard<std::mutex> guard(__mutex);
          head = __head;
          tail = __tail;
          size = __size;
        }
        std::string map;
 
        // --------------------------------------------------------------------------
        // Syntax checks.
        // --------------------------------------------------------------------------
        if (len == -1) len = size;
        if (len ==  0) return map;
        if (len <= -1) throw std::length_error("Unrealistic data length of " + std::to_string(len));
 
        // --------------------------------------------------------------------------
        // Generate output.
        // --------------------------------------------------------------------------
        if (len >= size) {
          head = head * (len / size);
          tail = tail * (len / size);
        } else {        
          head = head / (size / len);
          tail = tail / (size / len);
        } // -x- if len -x-
        map.reserve(len); // Pre-allocate the exact amount of underlying memory needed
        if (head >= tail) for (int i = 0; i < len; i++) map.append(i < tail || i >= head ? a : u); // "a" or "u" could be longer than one character
        else              for (int i = 0; i < len; i++) map.append(i < head || i >= tail ? u : a); // "a" or "u" could be longer than one character
 
        return map;
      } // -x- std::string get_ascii_map -x-
 
      /*======================================================================*//**
      @brief
      Calculate the number of available entries in the ring buffer.
      @returns Number of entries available
      @see get_utilized
      *///=========================================================================
      size_t get_available() noexcept {
        std::lock_guard<std::mutex> guard(__mutex);
        return __available();
      } // -x- size_t get_available -x-
 
      /*======================================================================*//**
      @brief
      Obtains the position of the head in the ring buffer.
      @returns Position of head in ring buffer
      @see get_available
      @see get_tail
      @see get_utilized
      @see set_head
      @see set_tail
      @qualifier ADVANCED
      *///=========================================================================
      size_t get_head() noexcept {
        std::lock_guard<std::mutex> guard(__mutex);
        return __head;
      } // -x- size_t get_head -x-
 
      /*======================================================================*//**
      @brief
      Obtains the total size of the ring buffer, including both its utilized and
      available portions.
      @returns Total size of ring buffer
      @see empty
      @see get_available
      @see get_utilized
      @see set_size
      @qualifier ADVANCED
      *///=========================================================================
      size_t get_size() noexcept {
        std::lock_guard<std::mutex> guard(__mutex);
        return __size;
      } // -x- size_t get_size -x-
 
      /*======================================================================*//**
      @brief
      Obtains the position of the tail in the ring buffer.
      @returns Position of tail in ring buffer
      @see get_available
      @see get_head
      @see get_utilized
      @see set_head
      @see set_tail
      @qualifier ADVANCED
      *///=========================================================================
      size_t get_tail() noexcept {
        std::lock_guard<std::mutex> guard(__mutex);
        return __tail;
      } // -x- size_t get_tail -x-
 
      /*======================================================================*//**
      @brief
      Calculate the number of utilized entries in the ring buffer.
      @returns Number of entries utilized
      @see get_available
      *///=========================================================================
      size_t get_utilized() noexcept {
        std::lock_guard<std::mutex> guard(__mutex);
        return __utilized();
      } // -x- size_t get_utilized -x-
 
      /*======================================================================*//**
      @brief
      Indicate whether internal buffer's memory will be cleared by the destructor
      before de-allocating it (default is @c true upon instantiation).
 
      @note
      This is an important security feature for when the ring buffer may have been
      storing private data because it prevents the leaking of private data to other
      process that coincidentally gain access to the same memory area (e.g., by way
      of future calls to `malloc()`).
      @returns Post-wipe policy (TRUE = clear / FALSE = don't clear)
      @see set_wipe_policy
      @qualifier ADVANCED
      *///=========================================================================
      bool get_wipe_policy() noexcept {
        std::lock_guard<std::mutex> guard(__mutex);
        return __wipe_policy;
      } // -x- bool get_wipe_policy -x-
 
      /*======================================================================*//**
      @brief
      Duplicate a single character from the utilized portion of the internal ring
      buffer, and return it as an @c char primitive.
      @exception std::overflow_error If the amount of data exceeds the amount of
                                     data in the ring buffer
      @returns Data from ring buffer
      @see append
      @see c_str
      @see peek_vector
      @see remove
      @see remove_vector
      *///=========================================================================
      char peek() {
        std::lock_guard<std::mutex> guard(__mutex);
 
        // --------------------------------------------------------------------------
        // Syntax checks.
        // --------------------------------------------------------------------------
        if (__utilized() == 0) throw std::overflow_error("Ring buffer is empty");
 
        // --------------------------------------------------------------------------
        // Duplicate the last byte of data from the ring buffer.
        // --------------------------------------------------------------------------
        return __buffer[__tail]; // Copy entry
 
      } // -x- char peek -x-
 
      /*======================================================================*//**
      @brief
      Duplicate the specified number of characters from the utilized portion of the
      internal ring buffer, and return them as a @c char* array.
      @post
      The string returned will need to be `free()`'d after it's no longer needed.
      @exception std::bad_alloc When @c malloc() fails to allocate memory
      @exception std::overflow_error If the amount of data exceeds the amount of
                                     data in the ring buffer
      @returns Data from ring buffer
      @see append
      @see c_str
      @see remove
      @see remove_array
      @see peek_string
      @see peek_vector
      *///=========================================================================
      char* peek_array(
      /// Amount of data to duplicate
      size_t len,
      /// Where to store the data@n
      /// @c nullptr = allocate the needed memory using @c malloc()
      char* data = nullptr) {
 
        // --------------------------------------------------------------------------
        // Internal variables.
        // --------------------------------------------------------------------------
        if (data == nullptr) data = (char*)malloc(len);
        if (data == nullptr) throw std::bad_alloc();
 
        // --------------------------------------------------------------------------
        // Remove data from ring buffer.
        // --------------------------------------------------------------------------
        {
          std::lock_guard<std::mutex> guard(__mutex);
          size_t t = __tail;
          for (int i = 0; i < len; i++) {
            data[i] = __buffer[t];    // Copy entry
            if (++t >= __size) t = 0; // Wrap-around
          } // -x- for i -x-
        }
 
        return data;
      } // -x- char* peek_array -x-
 
      /*======================================================================*//**
      @brief
      Duplicate the specified number of characters from the utilized portion of the
      internal ring buffer, and return it as an @c std::string object.
      @exception std::length_error If data length is -2 or below
      @exception std::overflow_error If the amount of data exceeds the amount of
                                     data in the ring buffer
      @returns Data from ring buffer
      @see append
      @see c_str
      @see peek_vector
      @see remove
      @see remove_vector
      *///=========================================================================
      std::string peek_string(
      /// Amount of data to duplicate@n
      /// -1 = all data
      int len = -1) {
 
        // --------------------------------------------------------------------------
        // Syntax checks.
        // --------------------------------------------------------------------------
        if (len < -1) throw std::length_error("Unrealistic data length of " + std::to_string(len));
 
        // --------------------------------------------------------------------------
        // Duplicate data from ring buffer.  If no data is needed, then skip all the
        // mutex locking overhead, etc., and return the empty string.
        // --------------------------------------------------------------------------
        std::string data;
        if (len != 0) {
          std::lock_guard<std::mutex> guard(__mutex);
          if (len == -1) len = __utilized();
          if (__utilized() < len) throw std::overflow_error("Amount of data (len=" + std::to_string(len) + ") exceeds utilized space in ring buffer");
          data.resize(len); // Pre-allocate needed memory
          size_t t = __tail;
          for (int i = 0; i < len; i++) {
            data[i] = __buffer[t];    // Copy entry
            if (++t >= __size) t = 0; // Wrap-around
          } // -x- for i -x-
        } // -x- if len -x-
 
        return data;
      } // -x- std::string peek_string -x-
 
      /*======================================================================*//**
      @brief
      Duplicate the specified number of characters from the utilized portion of the
      internal ring buffer, and return it as an @c std::string object.
      @exception std::length_error If data length is -2 or below
      @exception std::overflow_error If the amount of data exceeds the amount of
                                     data in the ring buffer
      @returns Data from ring buffer
      @see append
      @see c_str
      @see peek
      @see remove
      @see remove_vector
      *///=========================================================================
      std::vector<char> peek_vector(
      /// Amount of data to duplicate@n
      /// -1 = all data
      int len = -1) {
 
        // --------------------------------------------------------------------------
        // Syntax checks.
        // --------------------------------------------------------------------------
        if (len < -1) throw std::length_error("Unrealistic data length of " + std::to_string(len));
 
        // --------------------------------------------------------------------------
        // Duplicate data from ring buffer.  If no data is needed, then skip all the
        // mutex locking overhead, etc., and return the empty string.
        // --------------------------------------------------------------------------
        std::vector<char> data;
        if (len != 0) {
          std::lock_guard<std::mutex> guard(__mutex);
          if (len == -1) len = __utilized();
          if (__utilized() < len) throw std::overflow_error("Amount of data (len=" + std::to_string(len) + ") exceeds utilized space in ring buffer");
          data.resize(len); // Pre-allocate needed memory
          size_t t = __tail;
          for (int i = 0; i < len; i++) {
            data[i] = __buffer[t];    // Copy entry
            if (++t >= __size) t = 0; // Wrap-around
          } // -x- for i -x-
        } // -x- if len -x-
 
        return data;
      } // -x- std::vector<char> peek_vector -x-
 
      /*======================================================================*//**
      @brief
      Remove one character from the utilized portion of the internal ring buffer,
      and return it .
      @exception std::overflow_error If the amount of data exceeds the amount of
                                     data in the ring buffer
      @returns Data from ring buffer
      @see append
      @see c_str
      @see peek
      @see remove_array
      @see remove_string
      @see remove_vector
      *///=========================================================================
      char remove() {
 
        // --------------------------------------------------------------------------
        // Remove data from ring buffer.  If no data is needed, then skip all the
        // mutex locking overhead, etc., and return the empty string.
        // --------------------------------------------------------------------------
        char ch;
        {
          std::lock_guard<std::mutex> guard(__mutex);
          if (__utilized() == 0) throw std::overflow_error("Ring buffer is empty");
          ch = __buffer[__tail];              // Copy entry
          if (++__tail >= __size) __tail = 0; // Wrap-around
        }
 
        return ch;
      } // -x- char remove -x-
 
      /*======================================================================*//**
      @brief
      Remove the specified number of characters from the utilized portion of the
      internal ring buffer, and return them as a @c char* array.
      @post
      The string returned will need to be `free()`'d after it's no longer needed.
      @exception std::bad_alloc When @c malloc() fails to allocate memory
      @exception std::overflow_error If the amount of data exceeds the amount of
                                     data in the ring buffer
      @returns Data from ring buffer
      @see append
      @see c_str
      @see peek
      @see remove
      @see remove_string
      @see remove_vector
      *///=========================================================================
      char* remove_array(
      /// Amount of data to remove
      size_t len,
      /// Where to store the data@n
      /// @c nullptr = allocate the needed memory using @c malloc()
      char* data = nullptr) {
 
        // --------------------------------------------------------------------------
        // Internal variables.
        // --------------------------------------------------------------------------
        if (data == nullptr) data = (char*)malloc(len);
        if (data == nullptr) throw std::bad_alloc(); // Throw exception if data is still nullptr
 
        // --------------------------------------------------------------------------
        // Remove data from ring buffer.  If no data is needed, then skip all the
        // mutex locking overhead, etc., and return the empty string.
        // --------------------------------------------------------------------------
        {
          std::lock_guard<std::mutex> guard(__mutex);
          for (int i = 0; i < len; i++) {
            data[i] = __buffer[__tail];         // Copy entry
            if (++__tail >= __size) __tail = 0; // Wrap-around
          } // -x- for i -x-
        }
 
        return data;
      } // -x- char* remove_array -x-
 
      /*======================================================================*//**
      @brief
      Remove the specified number of characters from the utilized portion of the
      internal ring buffer, and return it as an @c std::string object.
      @exception std::length_error If data length is -2 or below
      @exception std::overflow_error If the amount of data exceeds the amount of
                                     data in the ring buffer
      @returns Data from ring buffer
      @see append
      @see c_str
      @see peek
      @see remove
      @see remove_string
      @see remove_vector
      *///=========================================================================
      std::string remove_string(
      /// Amount of data to remove@n
      /// -1 = all data
      int len = -1) {
 
        // --------------------------------------------------------------------------
        // Syntax checks.
        // --------------------------------------------------------------------------
        if (len < -1) throw std::length_error("Unrealistic data length of " + std::to_string(len));
 
        // --------------------------------------------------------------------------
        // Remove data from ring buffer.  If no data is needed, then skip all the
        // mutex locking overhead, etc., and return the empty string.
        // --------------------------------------------------------------------------
        std::string data;
        if (len > 0) {
          std::lock_guard<std::mutex> guard(__mutex);
          if (len == -1) len = __utilized();
          if (__utilized() < len) throw std::overflow_error("Amount of data (len=" + std::to_string(len) + ") exceeds utilized space in ring buffer");
          data.resize(len); // Pre-allocate needed memory
          for (int i = 0; i < len; i++) {
            data[i] = __buffer[__tail];         // Copy entry
            if (++__tail >= __size) __tail = 0; // Wrap-around
          } // -x- for i -x-
        } // -x- if len -x-
 
        return data;
      } // -x- std::string remove_string -x-
 
      /*======================================================================*//**
      @brief
      Remove the specified number of characters from the utilized portion of the
      internal ring buffer, and return it as an @c std::string object.
      @exception std::length_error If data length is -2 or below
      @exception std::overflow_error If the amount of data exceeds the amount of
                                     data in the ring buffer
      @returns Data from ring buffer
      @see append
      @see c_str
      @see peek
      @see remove
      @see remove_array
      @see remove_string
      *///=========================================================================
      std::vector<char> remove_vector(
      /// Amount of data to remove@n
      /// -1 = all data
      int len = -1) {
 
        // --------------------------------------------------------------------------
        // Syntax checks.
        // --------------------------------------------------------------------------
        if (len < -1) throw std::length_error("Unrealistic data length of " + std::to_string(len));
 
        // --------------------------------------------------------------------------
        // Remove data from ring buffer.  If no data is needed, then skip all the
        // mutex locking overhead, etc., and return the empty string.
        // --------------------------------------------------------------------------
        std::vector<char> data;
        if (len > 0) {
          std::lock_guard<std::mutex> guard(__mutex);
          if (len == -1) len = __utilized();
          if (__utilized() < len) throw std::overflow_error("Amount of data (len=" + std::to_string(len) + ") exceeds utilized space in ring buffer");
          data.resize(len); // Pre-allocate needed memory
          for (int i = 0; i < len; i++) {
            data[i] = __buffer[__tail];         // Copy entry
            if (++__tail >= __size) __tail = 0; // Wrap-around
          } // -x- for i -x-
        } // -x- if len -x-
 
        return data;
      } // -x- std::vector<char> remove_vector -x-
 
      /*======================================================================*//**
      @brief
      Alter the position of the internal head position, without changing any of the
      the pre-existing data in the underlying ring buffer.
      @exception std::overflow_error If the new position falls beyond the internal
                                     tail position (or, in other words, it exceeds
                                     the available free space in the ring buffer)
      @returns The same rring object so as to facilitate stacking
      @see get_available
      @see get_head
      @see get_tail
      @see get_utilized
      @see set_tail
      @qualifier ADVANCED
      *///=========================================================================
      rring* set_head(
      /// Position adjustment (may be positive or negative)
      int offset,
      /// Type of adjustment@n
      /// TRUE = absolute (default)@n
      /// FALSE = relative
      bool type = true) {
 
        // --------------------------------------------------------------------------
        // Absolute position.
        // --------------------------------------------------------------------------
        if (type) {
          std::lock_guard<std::mutex> guard(__mutex);
          if (offset <             0) throw std::overflow_error("Head position adjustment of " + std::to_string(offset) + " cannot be negative");
          if (offset > __available()) throw std::overflow_error("Head position adjustment of " + std::to_string(offset) + " exceeds available space in ring buffer");
          __head = (__head + offset) % __size;
 
        // --------------------------------------------------------------------------
        // Relative position.
        // --------------------------------------------------------------------------
        } else {
          if (offset > 0) { // Positive adjustment
            std::lock_guard<std::mutex> guard(__mutex);
            if (offset > __available()) throw std::overflow_error("Head position adjustment of " + std::to_string(offset) + " exceeds available space in ring buffer");
            __head = (__head + offset) % __size;
          } else if (offset < 0) { // Negative adjustment
            std::lock_guard<std::mutex> guard(__mutex);
            if (0 - offset > __utilized()) throw std::overflow_error("Head position adjustment of " + std::to_string(offset) + " exceeds utilized space in ring buffer");
            __head += offset;
            if (__head >= __size) __head += __size;
          } // -x- if offset -x-
        } // -x- if type -x-
 
        return this;
      } // -x- rring* set_head -x-
 
      /*======================================================================*//**
      @brief
      Configure the total size of the ring buffer.  The new size cannot be smaller
      than the amount of data that's already present in the ring buffer (see the
      @ref get_utilized method to find out how much data is present).
      @exception std::overflow_error If the new size exceeds the amount of data
                                     that's already present in the ring buffer
      @returns The same rring object so as to facilitate stacking
      @see get_available
      @see get_size
      @see get_utilized
      *///=========================================================================
      rring* set_size(
      /// New size of ring buffer
      const size_t len) {
        {
          std::lock_guard<std::mutex> guard(__mutex);
          if (__utilized() < len) throw std::overflow_error("New size of ring buffer (len=" + std::to_string(len) + ") exceeds utilized amount");
          // TODO:  Change (increase or decrease) total size of ring buffer, if possible,
          //        which will entail moving data around if it wraps, and also throwing
          //        an exception if the reduction is less than the utilized portion.
          __size = len;
        }
 
        return this;
      } // -x- rring* set_size -x-
 
      /*======================================================================*//**
      @brief
      Alter the position of the internal tail position, without changing any of the
      the pre-existing data in the underlying ring buffer.
      @exception std::overflow_error If the new position falls beyond the internal
                                     head position (or, in other words, it exceeds
                                     the available free space in the ring buffer)
      @returns The same rring object so as to facilitate stacking
      @see get_available
      @see get_head
      @see get_tail
      @see get_utilized
      @see set_head
      @qualifier ADVANCED
      *///=========================================================================
      rring* set_tail(
      /// Position adjustment (may be positive or negative)
      int offset,
      /// Type of adjustment@n
      /// TRUE = absolute (default)@n
      /// FALSE = relative
      bool type = true) {
 
        // --------------------------------------------------------------------------
        // Absolute position.
        // --------------------------------------------------------------------------
        if (type) {
          std::lock_guard<std::mutex> guard(__mutex);
          if (offset <            0) throw std::overflow_error("Tail position adjustment of " + std::to_string(offset) + " cannot be negative");
          if (offset > __utilized()) throw std::overflow_error("Tail position adjustment of " + std::to_string(offset) + " exceeds utilized space in ring buffer");
          __tail = (__tail + offset) % __size;
 
        // --------------------------------------------------------------------------
        // Relative position.
        // --------------------------------------------------------------------------
        } else {
          if (offset > 0) { // Positive position
            std::lock_guard<std::mutex> guard(__mutex);
            if (offset > __utilized()) throw std::overflow_error("Tail position adjustment of " + std::to_string(offset) + " exceeds utilized space in ring buffer");
            __tail = (__tail + offset) % __size;
          } else if (offset < 0) { // Negative adjustment
            std::lock_guard<std::mutex> guard(__mutex);
            if (0 - offset > __available()) throw std::overflow_error("Tail position adjustment of " + std::to_string(offset) + " exceeds available space in ring buffer");
            __tail += offset;
            if (__tail >= __size) __tail += __size;
          } // -x- if offset -x-
        } // -x- if type -x-
 
        return this;
      } // -x- rring* set_tail -x-
 
      /*======================================================================*//**
      @brief
      Specify whether the internal buffer's memory will be cleared by the
      destructor before de-allocating it (default is @c true upon instantiation).
 
      @note
      This is an important security feature for when the ring buffer may have been
      storing private data because it prevents the leaking of private data to other
      process that coincidentally gain access to the same memory area (e.g., by way
      of future calls to `malloc()`).
      @returns The same rring object so as to facilitate stacking
      @see get_wipe_policy
      @qualifier ADVANCED
      *///=========================================================================
      rring* set_wipe_policy(
      /// TRUE = clear buffer memory in destructor@n
      /// FALSE = don't clear buffer memory in destructor
      const bool policy_flag) noexcept {
        {
          std::lock_guard<std::mutex> guard(__mutex);
          __wipe_policy = policy_flag;
        }
 
        return this;
      } // -x- rring* set_wipe_policy -x-
 
      /*======================================================================*//**
      @brief
      Convert the entire contents of this ring buffer to an ASCIIZ string in the
      form of a @c char* array.
      @post
      The string returned will need to be `free()`'d after it's no longer needed.
 
      @code{.cpp}
        #include <iostream>      // std::cout, std::cerr, std::endl, etc.
        #include <randolf/rring>
 
        int main(int argc, char *argv[]) {
          randolf::rring rb(1024);
          rb.append("This is an example.");
          char* c = rb;
          std::cout << "\"" << c << "\"" << std::endl;
          free(c);
          return EXIT_SUCCESS;
        } // -x- int main -x-
      @endcode
 
      @exception std::bad_alloc When @c malloc() fails to allocate memory
      @returns Contents of this ring buffer as an ASCII string as a @c char* array.
      @see c_str
      *///=========================================================================
      operator char*() noexcept { return c_str(); }; // -x- operator char*() -x-
 
      /*======================================================================*//**
      @brief
      Convert the entire contents of this ring buffer to an @c std::string object.
 
      @code{.cpp}
        #include <iostream>      // std::cout, std::cerr, std::endl, etc.
        #include <string>        // std::string
        #include <randolf/rring>
 
        int main(int argc, char *argv[]) {
          randolf::rring rb(1024);
          rb.append("This is an example.");
          std::string s = rb;
          std::cout << "\"" << s << "\"" << std::endl;
          return EXIT_SUCCESS;
        } // -x- int main -x-
      @endcode
 
      @returns Contents of this ring buffer as an std::string object
      @see peek_string
      *///=========================================================================
      operator std::string() noexcept { return peek_string(); }; // -x- operator std::string -x-
 
      /*======================================================================*//**
      @brief
      Convert the entire contents of this ring buffer to an @c std::vector<char>
      object.
 
      @code{.cpp}
        #include <iostream>      // std::cout, std::cerr, std::endl, etc.
        #include <string>        // std::string
        #include <vector>        // std::vector
        #include <randolf/rring>
 
        int main(int argc, char *argv[]) {
          randolf::rring rb(1024);
          rb.append("This is an example.");
          std::vector<char> v = rb;
          std::cout << "\"" << std::string(v.begin(), v.end()) << "\"" << std::endl;
          return EXIT_SUCCESS;
        } // -x- int main -x-
      @endcode
 
      @returns Contents of this ring buffer as an std::vector<char> object
      @see peek_vector
      *///=========================================================================
      operator std::vector<char>() noexcept { return peek_vector(); }; // -x- operator std::vector<char> -x-
 
      /*======================================================================*//**
      @brief
      Support convenient streaming usage with std::cout, std::cerr, and friends.
 
      @code{.cpp}
        #include <iostream>      // std::cout, std::cerr, std::endl, etc.
        #include <string>        // std::string
        #include <randolf/rring>
 
        int main(int argc, char *argv[]) {
          randolf::rring rb(1024);
          rb.append("This is an example.");
          std::cout << "\"" << rb << "\"" << std::endl;
          return EXIT_SUCCESS;
        } // -x- int main -x-
      @endcode
 
      @returns Contents of this ring buffer as an ASCIIZ string (a.k.a., C-string)
      @see c_str
      *///=========================================================================
      friend std::ostream& operator<< (
      /// Output stream (provided automatically by std::cout and std::cerr)
      std::ostream& o,
      /// Object class (matched by compiler)
      rring& c) noexcept { return o << c.c_str(); }; // -x- std::ostream& operator<< -x-
 
      /*======================================================================*//**
      @brief
      Array-style access to the utilized portion of the ring buffer's contents,
      which yields the same result as that of the @ref at() method.
 
      The first element is at index 0.
      @throws std::out_of_range if the index is out-of-range
      @returns char
      @see at
      *///=========================================================================
      char operator[](
      /// Index of character to access (0 = first element; negative index values
      /// are calculated in reverse, starting with -1 as the final position)
      int index) {
        std::lock_guard<std::mutex> guard(__mutex);
 
        // --------------------------------------------------------------------------
        // Internal variables.
        // --------------------------------------------------------------------------
        int MAX = __utilized();
 
        // --------------------------------------------------------------------------
        // Syntax checks.
        // --------------------------------------------------------------------------
        if (index >= MAX || 0 - index > MAX) throw std::out_of_range("index (position=" + std::to_string(index) + ") falls outside of the utilized portion (length=" + std::to_string(MAX) + ") of the buffer");
 
        // --------------------------------------------------------------------------
        // Calculate character's position.
        // --------------------------------------------------------------------------
        index = index >= 0 ? __tail + index : __head + index;
        if (index >= __size) index -= __size;
 
        return __buffer[index];
      }; // -x- char operator[] -x-
 
  }; // -x- class rring -x-
 
}; // -x- namespace randolf -x-