#ifndef __REQUEST_QUEUE_H__
#define __REQUEST_QUEUE_H__

#include <stdbool.h>

/**
 * A request sent to a game server. A request consists of the user
 * making the request and the position they are requesting a
 * response to.
 *
 * @param user a string, non-NULL
 * @param position a string, non-NULL
 */
typedef struct _request
{
  char *user;
  char *position;
} request;

/**
 * A FIFO queue of requests.
 */
struct _rqueue;
typedef struct _rqueue rqueue;

/**
 * Creates and returns an empty queue with the given maximum capacity.
 * If there is an error allocating the queue then the returned value
 * is NULL.
 *
 * @param max a positive integer
 * @return a pointer to the new queue
 */
rqueue *rqueue_create(int max);

/**
 * Destroys the given queue.  The queue is invalid after it has been
 * destroyed.
 *
 * @param q a pointer to a valid queue, non-NULL
 */
void rqueue_destroy(rqueue *q);

/**
 * Returns the size of the given queue.
 *
 * @param q a pointer to a valid queue, non-NULL
 * @return the size of that queue
 */
int rqueue_size(const rqueue *q);

/**
 * Adds a deep copy of the given request to the given queue
 * (a "deep" copy is one that copies not just the struct, but the
 * data inside the struct, which in this case is the user and
 * position strings).  The return value is false if there was an
 * error allocating space for the new copy and in that case
 * the queue is not changed.
 *
 * @param q a pointer to a valid queue, non-NULL
 * @param a pointer to a valid request, non-NULL
 * @return true if and only if the request was added
 */
bool rqueue_add(rqueue *q, const request *r);

/**
 * Removes from the given queue the request remaining on that queue
 * that has been on the queue the longest (FIFO: first-in, first-out).
 * The removed request is saved in the request pointed to by the
 * pointer passed in and it is the responsibility of the caller
 * to free the user and position returned.  If the request pointer
 * passed in is NULL, then the request is removed but not returned.
 *
 * @param q a pointer to a valid queue, non-NULL
 * @param r a pointer to a valid request, or NULL
 */
void rqueue_remove(rqueue *q, request *r);

#endif