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  */
63 typedef list_t queue_t;
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 /*---------------------------------------------------------------------------*/
79 struct queue {
80  struct queue *next;
81 };
82 /*---------------------------------------------------------------------------*/
83 /**
84  * \brief Initialise a queue
85  * \param queue The queue
86  */
87 static 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  */
98 static inline void
99 queue_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  */
111 static 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  */
122 static 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  */
134 static inline bool
136 {
137  return *queue == NULL ? true : false;
138 }
139 /*---------------------------------------------------------------------------*/
140 #endif /* QUEUE_H_ */
141 /*---------------------------------------------------------------------------*/
142 /**
143  * @}
144  * @}
145  */
static void * queue_peek(queue_t queue)
Returns the front element of the queue, without removing it.
Definition: queue.h:123
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
void ** list_t
The linked list type.
Definition: list.h:136
list_t queue_t
The queue data type.
Definition: queue.h:63
Linked list manipulation routines.
void * list_head(list_t list)
Get a pointer to the first element of a list.
Definition: list.c:82
static bool queue_is_empty(queue_t queue)
Check if a queue is empty.
Definition: queue.h:135
void list_add(list_t list, void *item)
Add an item at the end of a list.
Definition: list.c:142
void list_init(list_t list)
Initialize a list.
Definition: list.c:65
static void queue_init(queue_t queue)
Initialise a queue.
Definition: queue.h:88
void * list_pop(list_t list)
Remove the first object on a list.
Definition: list.c:215