/*****************************************************************************/
/**
 * Description: A simple circular FIFO bounded queue
 * 
 * Author: Fan Hao
 * Date: 2023-02-23 10:29
 * LastEditors: Fan Hao
 * LastEditTime: 2023-02-23 12:53
 * Revisions: Rev 0.0
 * History: 
 * [2023-02-23]: Initial Version.
 * 
 * Copyright(c) 2023 Beijing Institute of Technology.
 * Lab of Communication and Networking
 * NOTE: Forked from https://github.com/chrismerck/rpa_queue.git
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You under the Apache License, Version 2.0
 * (the "License"); you may not use this file except in compliance with
 * the License.  You may obtain a copy of the License at
 *
 *   http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
******************************************************************************/

#ifndef CIRC_QUEUE_H
#define CIRC_QUEUE_H

#include <stdbool.h>
#include <stdint.h>
#include <stddef.h>


/**
 * opaque structure
 */
typedef struct {
  void **data;
  volatile uint32_t nelts; /**< # elements */
  uint32_t in;  /**< next empty location */
  uint32_t out;   /**< next filled location */
  uint32_t bounds;/**< max size of queue */
} CIRC_QUEUE;



/**
 * create a FIFO queue
 * @param queue The new queue
 * @param queue_capacity maximum size of the queue
 * @param a pool to allocate queue from
 */
bool CircQueueCreate(CIRC_QUEUE **queue, uint32_t queue_capacity);

/** free queue memory -- call after destroy 
 * @note we do not free in destroy() to follow pthreads convention
*/
void CircQueueFree(CIRC_QUEUE * queue);

/**
 * Detects when the CIRC_QUEUE is full. This utility function is expected
 * to be called from within critical sections, and is not threadsafe.
 */
bool isCircQueueFull(CIRC_QUEUE *queue);

/**
 * Detects when the CIRC_QUEUE is empty. This utility function is expected
 * to be called from within critical sections, and is not threadsafe.
 */
bool isCircQueueEmpty(CIRC_QUEUE *queue);

/**
 * push/add an object to the queue, blocking if the queue is already full
 *
 * @param queue the queue
 * @param data the data
 * @returns RPA_EINTR the blocking was interrupted (try again)
 * @returns RPA_EOF the queue has been terminated
 * @returns RPA_SUCCESS on a successful push
 */
bool CircQueuePush(CIRC_QUEUE *queue, void *data);


/**
 * pop/get an object from the queue, blocking if the queue is already empty
 *
 * @param queue the queue
 * @param data the data
 * @returns RPA_EINTR the blocking was interrupted (try again)
 * @returns RPA_EOF if the queue has been terminated
 * @returns RPA_SUCCESS on a successful pop
 */
bool CircQueuePop(CIRC_QUEUE *queue, void **data);

/**
 * returns the size of the queue.
 *
 * @warning this is not threadsafe, and is intended for reporting/monitoring
 * of the queue.
 * @param queue the queue
 * @returns the size of the queue
 */
uint32_t CircQueueSize(CIRC_QUEUE *queue);

#endif /* CIRC_QUEUE_H */