Contiki-NG
stack.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 stack-data-structure Stack library
38 *
39 * This library provides functions for the creation and manipulation of
40 * stacks. The library is implemented as a wrapper around the list library.
41 *
42 * A stack is declared using the STACK macro. Stack 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 stack. 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 STACK_H_
53#define STACK_H_
54/*---------------------------------------------------------------------------*/
55#include "contiki.h"
56#include "lib/list.h"
57
58#include <stdbool.h>
59/*---------------------------------------------------------------------------*/
60/**
61 * \brief The stack data type
62 */
64/*---------------------------------------------------------------------------*/
65/**
66 * \brief Define a stack.
67 *
68 * This macro defines a stack.
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 stack.
76 */
77#define STACK(name) LIST(name)
78/*---------------------------------------------------------------------------*/
79struct stack {
80 struct stack *next;
81};
82/*---------------------------------------------------------------------------*/
83/**
84 * \brief Initialise a stack
85 * \param stack The stack
86 */
87static inline void
89{
90 list_init(stack);
91}
92/*---------------------------------------------------------------------------*/
93/**
94 * \brief Adds an element to the top of the stack
95 * \param stack The stack
96 * \param element A pointer to the element to be added
97 */
98static inline void
99stack_push(stack_t stack, void *element)
100{
101 list_push(stack, element);
102}
103/*---------------------------------------------------------------------------*/
104/**
105 * \brief Removes the top element from the stack
106 * \param stack The stack
107 * \return A pointer to the element popped
108 *
109 * If this function returns NULL if the stack was empty (stack underflow)
110 */
111static inline void *
113{
114 return list_pop(stack);
115}
116/*---------------------------------------------------------------------------*/
117/**
118 * \brief Returns the top element of the stack, without popping it
119 * \param stack The stack
120 * \return A pointer to the element at the top of the stack
121 */
122static inline void *
124{
125 return list_head(stack);
126}
127/*---------------------------------------------------------------------------*/
128/**
129 * \brief Check if a stack is empty
130 * \param stack The stack
131 * \retval true The stack is empty
132 * \retval false The stack has at least one element
133 */
134static inline bool
136{
137 return *stack == NULL ? true : false;
138}
139/*---------------------------------------------------------------------------*/
140#endif /* STACK_H_ */
141/*---------------------------------------------------------------------------*/
142/**
143 * @}
144 * @}
145 */
void list_init(list_t list)
Initialize a list.
Definition: list.c:57
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_push(list_t list, void *item)
Add an item to the start of the list.
Definition: list.c:108
void * list_head(const_list_t list)
Get a pointer to the first element of a list.
Definition: list.c:63
static void stack_push(stack_t stack, void *element)
Adds an element to the top of the stack.
Definition: stack.h:99
static void stack_init(stack_t stack)
Initialise a stack.
Definition: stack.h:88
static void * stack_peek(stack_t stack)
Returns the top element of the stack, without popping it.
Definition: stack.h:123
static void * stack_pop(stack_t stack)
Removes the top element from the stack.
Definition: stack.h:112
static bool stack_is_empty(stack_t stack)
Check if a stack is empty.
Definition: stack.h:135
list_t stack_t
The stack data type.
Definition: stack.h:63
Linked list manipulation routines.