Queue.hpp

Go to the documentation of this file.

/******************************************************************************
* Copyright (c) ATTX INC 2025. All Rights Reserved.
*
* This software and associated documentation (the "Software") are the 
* proprietary and confidential information of ATTX, INC. The Software is 
* furnished under a license agreement between ATTX and the user organization 
* and may be used or copied only in accordance with the terms of the agreement.
* Refer to 'license/attx_license.adoc' for standard license terms.
*
* EXPORT CONTROL NOTICE: THIS SOFTWARE MAY INCLUDE CONTENT CONTROLLED UNDER THE
* INTERNATIONAL TRAFFIC IN ARMS REGULATIONS (ITAR) OR THE EXPORT ADMINISTRATION 
* REGULATIONS (EAR99). No part of the Software may be used, reproduced, or 
* transmitted in any form or by any means, for any purpose, without the express 
* written permission of ATTX, INC.
******************************************************************************/
/*
OSAL header file
 
Author: Alex Reynolds
*/
#ifndef DATA_MANAGEMENT_QUEUE_HPP
#define DATA_MANAGEMENT_QUEUE_HPP
 
#include <stdint.h>
 
#include "types.h"
#include "core/clockwerkerrors.h"
 
namespace clockwerk {

template <typename T, uint32 L>
class Queue {
public:
    // Can't actually do anything in the constructor 
    Queue() {}

    int16 write(const T& instance);
    int16 writeBuffer(const T* buffer, uint32 size);

    int16 read(T& instance);
    int16 readBuffer(T* buffer, uint32 max_vals, uint32& num_vals_read);

    int16 pop();
    int16 popBuffer(uint32 max_vals, uint32& num_vals_popped);

    int16 peek(T& instance);
    int16 peekIndex(uint32 index, T& instance);
    int16 peekBuffer(T* buffer, uint32 max_vals, uint32& num_vals_read);

    void clear();

    uint32 valsAvailable() {return _vals_available;}

    uint32 valsHeld() {return L - _vals_available;}
protected:
    uint32 _write_idx = 0;

    uint32 _read_idx = 0;

    uint32 _vals_available = L;

    T _buffer[L];
};
 
template <typename T, uint32 L>
int16 Queue<T, L>::write(const T& instance) {
    // Check and return if queue is full
    if(!_vals_available) {
        return ERROR_QUEUE_FULL;
    }
    // We have vals available. Add to the queue at write ptr and return
    _buffer[_write_idx] = instance;
    _vals_available--;
 
    // Increment our write pointer. Note that if it reaches the end of our
    // buffer we need to wrap back to zero
    _write_idx++;
    if(_write_idx == L) {
        _write_idx = 0;
    }
 
    return NO_ERROR;
}
 
template <typename T, uint32 L>
int16 Queue<T, L>::writeBuffer(const T* buffer, uint32 size) {
    if(buffer == nullptr) {
        return ERROR_NULLPTR;
    }
 
    // Check and return if queue doesn't have enough space
    if(size > _vals_available) {
        return ERROR_QUEUE_FULL;
    }
    // We have space. Add to the queue in a loop so we can manage the wrap around
    _vals_available -= size;
    for(uint32 i = 0; i < size; i++) {
        // Write value to our buffer
        _buffer[_write_idx] = buffer[i];
 
        // And increment our write pointer while managing the wrap
        _write_idx++;
        if(_write_idx == L) {
            _write_idx = 0;
        }
    }
 
    return NO_ERROR;
}
 
template <typename T, uint32 L>
int16 Queue<T, L>::read(T& instance) {
    // Check if our queue is empty
    if(_vals_available == L) {
        return ERROR_QUEUE_EMPTY;
    }
    // Queue is not empty. Return value
    instance = _buffer[_read_idx];
 
    // And increment our read pointer while managing the wrap
    _read_idx++;
    if(_read_idx == L) {
        _read_idx = 0;
    }
 
    _vals_available++;
    
    return NO_ERROR;
}
 
template <typename T, uint32 L>
int16 Queue<T, L>::readBuffer(T* buffer, uint32 max_vals, uint32& num_vals_read) {
    // Init num_vals_read to 0 in case we exit early
    num_vals_read = 0;
 
    if(buffer == nullptr) {
        return ERROR_NULLPTR;
    }
 
    // Check if our queue is empty
    if(_vals_available == L) {
        return ERROR_QUEUE_EMPTY;
    }
    // Queue is not empty. Identify how many values we can read
    num_vals_read = L - _vals_available;
    if(num_vals_read > max_vals) {
        num_vals_read = max_vals;
    }
 
    // And read that many values
    for(uint32 i = 0; i < num_vals_read; i++) {
        // Write value to our buffer
        *(buffer + i) = _buffer[_read_idx];
 
        // And increment our read pointer while managing the wrap
        _read_idx++;
        if(_read_idx == L) {
            _read_idx = 0;
        }
    }
 
    _vals_available += num_vals_read;
    
    return NO_ERROR;
}
 
template <typename T, uint32 L>
int16 Queue<T, L>::pop() {
    // Check if our queue is empty
    if(_vals_available == L) {
        return ERROR_QUEUE_EMPTY;
    }
 
    // And increment our read pointer while managing the wrap
    _read_idx++;
    if(_read_idx == L) {
        _read_idx = 0;
    }
 
    _vals_available++;
 
    return NO_ERROR;
}
 
template <typename T, uint32 L>
int16 Queue<T, L>::popBuffer(uint32 max_vals, uint32& num_vals_popped) {
    // Init num_vals_popped to 0 in case we exit early
    num_vals_popped = 0;
 
    // Check if our queue is empty
    if(_vals_available == L) {
        return ERROR_QUEUE_EMPTY;
    }
    // Queue is not empty. Identify how many values we can pop
    num_vals_popped = L - _vals_available;
    if(num_vals_popped > max_vals) {
        num_vals_popped = max_vals;
    }
 
    // And pop that many values
    for(uint32 i = 0; i < num_vals_popped; i++) {
        // And increment our read pointer while managing the wrap
        _read_idx++;
        if(_read_idx == L) {
            _read_idx = 0;
        }
    }
 
    _vals_available += num_vals_popped;
 
    return NO_ERROR;
}
 
template <typename T, uint32 L>
int16 Queue<T, L>::peek(T& instance) {
    // Check if our queue is empty
    if(_vals_available == L) {
        return ERROR_QUEUE_EMPTY;
    }
    // Queue is not empty. Return value but do not change increments
    instance = _buffer[_read_idx];
    
    return NO_ERROR;
}
 
template <typename T, uint32 L>
int16 Queue<T, L>::peekIndex(uint32 index, T& instance) {
    // Check if our queue is empty
    if(_vals_available == L) {
        return ERROR_QUEUE_EMPTY;
    }
 
    // Check if our index is valid for the queue
    if(index >= valsHeld()) {
        return ERROR_INVALID_RANGE;
    }
 
    // Loop through values to find index of desired read
    if(_read_idx + index >= L) {
        index = _read_idx + index - L;
    } else {
        index = _read_idx + index;
    }
    instance = _buffer[index];
    
    return NO_ERROR;
}
 
template <typename T, uint32 L>
int16 Queue<T, L>::peekBuffer(T* buffer, uint32 max_vals, uint32& num_vals_read) {
    // Init number of values read to 0
    num_vals_read = 0;
    
    if(buffer == nullptr) {
        return ERROR_NULLPTR;
    }
 
    // Check if our queue is empty
    if(_vals_available == L) {
        return ERROR_QUEUE_EMPTY;
    }
    // Queue is not empty. Identify how many values we can read
    num_vals_read = L - _vals_available;
    if(num_vals_read > max_vals) {
        num_vals_read = max_vals;
    }
 
    // And read that many values
    uint32 tmp_idx = _read_idx;
    for(uint32 i = 0; i < num_vals_read; i++) {
        // Write value to our buffer
        *(buffer + i) = _buffer[_read_idx];
 
        // And increment our read pointer while managing the wrap
        _read_idx++;
        if(_read_idx == L) {
            _read_idx = 0;
        }
    }
    _read_idx = tmp_idx;
    
    return NO_ERROR;
}
 
template <typename T, uint32 L>
void Queue<T, L>::clear() {
    _write_idx = 0;
    _read_idx = 0;
    _vals_available = L;
}
 
}
 
#endif