Contiki-NG
queue.h
1/*
2 * Copyright (c) 2017, George Oikonomou - http://www.spd.gr
3 * Copyright (c) 2017, James Pope
4 * All rights reserved.
5 *
6 * Redistribution and use in source and binary forms, with or without
7 * modification, are permitted provided that the following conditions
8 * are met:
9 *
10 * 1. Redistributions of source code must retain the above copyright
11 * notice, this list of conditions and the following disclaimer.
12 * 2. Redistributions in binary form must reproduce the above copyright
13 * notice, this list of conditions and the following disclaimer in the
14 * documentation and/or other materials provided with the distribution.
15 * 3. Neither the name of the copyright holder nor the names of its
16 * contributors may be used to endorse or promote products derived
17 * from this software without specific prior written permission.
18 *
19 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
20 * ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
21 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
22 * FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
23 * COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
24 * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
25 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
26 * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
27 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
28 * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
29 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
30 * OF THE POSSIBILITY OF SUCH DAMAGE.
31 */
32/*---------------------------------------------------------------------------*/
33/**
34 * \addtogroup data
35 * @{
36 *
37 * \defgroup queue Queue library
38 *
39 * This library provides functions for the creation and manipulation of
40 * queues. The library is implemented as a wrapper around the list library.
41 *
42 * A queue is declared using the QUEUE macro. Queue elements must be
43 * allocated by the calling code and must be of a C struct datatype. In this
44 * struct, the first field must be a pointer called \e next. This field will
45 * be used by the library to maintain the queue. Application code must not
46 * modify this field directly.
47 *
48 * This library is not safe to be used within an interrupt context.
49 * @{
50 */
51/*---------------------------------------------------------------------------*/
52#ifndef QUEUE_H_
53#define QUEUE_H_
54/*---------------------------------------------------------------------------*/
55#include "contiki.h"
56#include "lib/list.h"
57
58#include <stdbool.h>
59/*---------------------------------------------------------------------------*/
60/**
61 * \brief The queue data type
62 */
64/*---------------------------------------------------------------------------*/
65/**
66 * \brief Define a queue.
67 *
68 * This macro defines a queue.
69 *
70 * The datatype for elements must be a C struct. The struct's first member must
71 * be a pointer called \e next. This is used internally by the library to
72 * maintain data structure integrity and must not be modified directly by
73 * application code.
74 *
75 * \param name The name of the queue.
76 */
77#define QUEUE(name) LIST(name)
78/*---------------------------------------------------------------------------*/
79struct queue {
80 struct queue *next;
81};
82/*---------------------------------------------------------------------------*/
83/**
84 * \brief Initialise a queue
85 * \param queue The queue
86 */
87static inline void
89{
90 list_init(queue);
91}
92/*---------------------------------------------------------------------------*/
93/**
94 * \brief Adds an element to the tail of the queue
95 * \param queue The queue
96 * \param element A pointer to the element to be added
97 */
98static inline void
99queue_enqueue(queue_t queue, void *element)
100{
101 list_add(queue, element);
102}
103/*---------------------------------------------------------------------------*/
104/**
105 * \brief Removes the element at the front of the queue
106 * \param queue The queue
107 * \return A pointer to the element removed
108 *
109 * If this function returns NULL if the queue was empty (queue underflow)
110 */
111static inline void *
113{
114 return list_pop(queue);
115}
116/*---------------------------------------------------------------------------*/
117/**
118 * \brief Returns the front element of the queue, without removing it
119 * \param queue The queue
120 * \return A pointer to the element at the front of the queue
121 */
122static inline void *
124{
125 return list_head(queue);
126}
127/*---------------------------------------------------------------------------*/
128/**
129 * \brief Check if a queue is empty
130 * \param queue The queue
131 * \retval true The queue is empty
132 * \retval false The queue has at least one element
133 */
134static inline bool
136{
137 return *queue == NULL ? true : false;
138}
139/*---------------------------------------------------------------------------*/
140#endif /* QUEUE_H_ */
141/*---------------------------------------------------------------------------*/
142/**
143 * @}
144 * @}
145 */
void list_init(list_t list)
Initialize a list.
Definition: list.c:57
void list_add(list_t list, void *item)
Add an item at the end of a list.
Definition: list.c:89
void * list_pop(list_t list)
Remove the first object on a list.
Definition: list.c:140
void ** list_t
The linked list type.
Definition: list.h:135
void * list_head(const_list_t list)
Get a pointer to the first element of a list.
Definition: list.c:63
list_t queue_t
The queue data type.
Definition: queue.h:63
static void * queue_peek(queue_t queue)
Returns the front element of the queue, without removing it.
Definition: queue.h:123
static void queue_init(queue_t queue)
Initialise a queue.
Definition: queue.h:88
static void queue_enqueue(queue_t queue, void *element)
Adds an element to the tail of the queue.
Definition: queue.h:99
static void * queue_dequeue(queue_t queue)
Removes the element at the front of the queue.
Definition: queue.h:112
static bool queue_is_empty(queue_t queue)
Check if a queue is empty.
Definition: queue.h:135
Linked list manipulation routines.