/**
 * \file safe_fifo.h
 * Thread-safe FIFO queue.
 */

#ifndef SAFE_FIFO_H
#define SAFE_FIFO_H

#include "timespec.h"

/**
 * Opaque type describing a thread-safe FIFO queue
 */
typedef struct safe_fifo_t safe_fifo_t;

/**
 * Create a new queue.
 * The new queue will have a reference count of one.
 * Returns NULL in case of allocation errors.
 * @return a new queue
 */
MALLOC safe_fifo_t* safe_fifo_new(void);

/**
 * Increase the reference count on the queue.
 * @param fifo queue, may not be NULL
 */
NONULL void safe_fifo_ref(safe_fifo_t* fifo);

/**
 * Decrease the reference count on the queue and free if it goes down to zero.
 * @param fifo queue, may be NULL
 */
void safe_fifo_unref(safe_fifo_t* fifo);

/**
 * Push an item on the queue.
 * Will never block. In case of allocation errors, new items are ignored.
 * @param fifo queue, may not be NULL
 * @param item pointer to add to queue, may not be NULL
 */
NONULL void safe_fifo_push(safe_fifo_t* fifo, void* item);

/**
 * Pop an item from the queue.
 * Will block until there is an item available.
 * @param fifo queue, may not be NULL
 * @return oldest item pushed onto the queue
 */
NONULL void* safe_fifo_pop(safe_fifo_t* fifo);

/**
 * Try to pop an item from the queue.
 * Will not wait until there is an item available.
 * @param fifo queue, may not be NULL
 * @return oldest item in queue if any otherwise NULL
 */
NONULL void* safe_fifo_trypop(safe_fifo_t* fifo);

/**
 * Try to pop an item from the queue.
 * Waits until abstime has occurred before giving up and returning NULL.
 * Use thread_abstime() to fill out the abstime.
 * @param fifo queue, may not be NULL
 * @param abstime absolute time when to give up
 * @return oldest item in queue if any otherwise NULL
 */
NONULL void* safe_fifo_timedpop(safe_fifo_t* fifo,
                                const struct timespec *abstime);

#endif /* SAFE_FIFO_H */