From e87e3850c453d57c62e708f1f2bf1aff7cc4aee4 Mon Sep 17 00:00:00 2001 From: George Oikonomou Date: Sun, 10 Dec 2017 23:12:07 +0000 Subject: [PATCH] Add circular, doubly-linked list library --- os/lib/dbl-circ-list.c | 227 +++++++++++++++++++++++++++++++++++++++++ os/lib/dbl-circ-list.h | 193 +++++++++++++++++++++++++++++++++++ 2 files changed, 420 insertions(+) create mode 100644 os/lib/dbl-circ-list.c create mode 100644 os/lib/dbl-circ-list.h diff --git a/os/lib/dbl-circ-list.c b/os/lib/dbl-circ-list.c new file mode 100644 index 000000000..35b33a801 --- /dev/null +++ b/os/lib/dbl-circ-list.c @@ -0,0 +1,227 @@ +/* + * Copyright (c) 2017, George Oikonomou - http://www.spd.gr + * Copyright (c) 2017, James Pope + * All rights reserved. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions + * are met: + * + * 1. Redistributions of source code must retain the above copyright + * notice, this list of conditions and the following disclaimer. + * 2. Redistributions in binary form must reproduce the above copyright + * notice, this list of conditions and the following disclaimer in the + * documentation and/or other materials provided with the distribution. + * 3. Neither the name of the copyright holder nor the names of its + * contributors may be used to endorse or promote products derived + * from this software without specific prior written permission. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS + * ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT + * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS + * FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE + * COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, + * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES + * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR + * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) + * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, + * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED + * OF THE POSSIBILITY OF SUCH DAMAGE. + */ +/*---------------------------------------------------------------------------*/ +/** + * \addtogroup doubly-linked-circular-list + * @{ + * + * \file + * Implementation of circular, doubly-linked lists + */ +/*---------------------------------------------------------------------------*/ +#include "contiki.h" +#include "lib/dbl-circ-list.h" + +#include +#include +#include +/*---------------------------------------------------------------------------*/ +struct dblcl { + struct dblcl *next; + struct dblcl *previous; +}; +/*---------------------------------------------------------------------------*/ +void +dbl_circ_list_init(dbl_circ_list_t dblcl) +{ + *dblcl = NULL; +} +/*---------------------------------------------------------------------------*/ +void * +dbl_circ_list_head(dbl_circ_list_t dblcl) +{ + return *dblcl; +} +/*---------------------------------------------------------------------------*/ +void * +dbl_circ_list_tail(dbl_circ_list_t dblcl) +{ + struct dblcl *this; + + if(*dblcl == NULL) { + return NULL; + } + + for(this = *dblcl; this->next != *dblcl; this = this->next); + + return this; +} +/*---------------------------------------------------------------------------*/ +void +dbl_circ_list_remove(dbl_circ_list_t dblcl, void *element) +{ + struct dblcl *this; + + if(*dblcl == NULL || element == NULL) { + return; + } + + this = *dblcl; + + do { + if(this == element) { + this->previous->next = this->next; + this->next->previous = this->previous; + + /* We need to update the head of the list if we removed the head */ + if(*dblcl == element) { + *dblcl = this->next == this ? NULL : this->next; + } + + this->next = NULL; + this->previous = NULL; + + return; + } + + this = this->next; + } while(this != *dblcl); +} +/*---------------------------------------------------------------------------*/ +void +dbl_circ_list_add_head(dbl_circ_list_t dblcl, void *element) +{ + struct dblcl *head; + + if(element == NULL) { + return; + } + + /* Don't add twice */ + dbl_circ_list_remove(dblcl, element); + + head = dbl_circ_list_head(dblcl); + + if(head == NULL) { + /* If the list was empty */ + ((struct dblcl *)element)->next = element; + ((struct dblcl *)element)->previous = element; + } else { + /* If the list was not empty */ + ((struct dblcl *)element)->next = head; + ((struct dblcl *)element)->previous = head->previous; + head->previous->next = element; + head->previous = element; + } + + *dblcl = element; +} +/*---------------------------------------------------------------------------*/ +void +dbl_circ_list_add_tail(dbl_circ_list_t dblcl, void *element) +{ + struct dblcl *tail; + + if(element == NULL) { + return; + } + + /* Don't add twice */ + dbl_circ_list_remove(dblcl, element); + + tail = dbl_circ_list_tail(dblcl); + + if(tail == NULL) { + /* If the list was empty */ + ((struct dblcl *)element)->next = element; + ((struct dblcl *)element)->previous = element; + *dblcl = element; + } else { + /* If the list was not empty */ + ((struct dblcl *)element)->next = *dblcl; + ((struct dblcl *)element)->previous = tail; + tail->next->previous = element; + tail->next = element; + } +} +/*---------------------------------------------------------------------------*/ +void +dbl_circ_list_add_after(dbl_circ_list_t dblcl, void *existing, void *element) +{ + if(element == NULL || existing == NULL) { + return; + } + + /* Don't add twice */ + dbl_circ_list_remove(dblcl, element); + + ((struct dblcl *)element)->next = ((struct dblcl *)existing)->next; + ((struct dblcl *)element)->previous = existing; + ((struct dblcl *)existing)->next->previous = element; + ((struct dblcl *)existing)->next = element; +} +/*---------------------------------------------------------------------------*/ +void +dbl_circ_list_add_before(dbl_circ_list_t dblcl, void *existing, void *element) +{ + if(element == NULL || existing == NULL) { + return; + } + + /* Don't add twice */ + dbl_circ_list_remove(dblcl, element); + + ((struct dblcl *)element)->next = existing; + ((struct dblcl *)element)->previous = ((struct dblcl *)existing)->previous; + ((struct dblcl *)existing)->previous->next = element; + ((struct dblcl *)existing)->previous = element; + + /* If we added before the list's head, we must update the head */ + if(*dblcl == existing) { + *dblcl = element; + } +} +/*---------------------------------------------------------------------------*/ +unsigned long +dbl_circ_list_length(dbl_circ_list_t dblcl) +{ + unsigned long len = 1; + struct dblcl *this; + + if(*dblcl == NULL) { + return 0; + } + + for(this = *dblcl; this->next != *dblcl; this = this->next) { + len++; + } + + return len; +} +/*---------------------------------------------------------------------------*/ +bool +dbl_circ_list_is_empty(dbl_circ_list_t dblcl) +{ + return *dblcl == NULL ? true : false; +} +/*---------------------------------------------------------------------------*/ +/** @} */ diff --git a/os/lib/dbl-circ-list.h b/os/lib/dbl-circ-list.h new file mode 100644 index 000000000..08eba8188 --- /dev/null +++ b/os/lib/dbl-circ-list.h @@ -0,0 +1,193 @@ +/* + * Copyright (c) 2017, George Oikonomou - http://www.spd.gr + * Copyright (c) 2017, James Pope + * All rights reserved. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions + * are met: + * + * 1. Redistributions of source code must retain the above copyright + * notice, this list of conditions and the following disclaimer. + * 2. Redistributions in binary form must reproduce the above copyright + * notice, this list of conditions and the following disclaimer in the + * documentation and/or other materials provided with the distribution. + * 3. Neither the name of the copyright holder nor the names of its + * contributors may be used to endorse or promote products derived + * from this software without specific prior written permission. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS + * ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT + * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS + * FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE + * COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, + * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES + * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR + * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) + * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, + * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED + * OF THE POSSIBILITY OF SUCH DAMAGE. + */ +/*---------------------------------------------------------------------------*/ +/** \addtogroup data + * @{ + * + * \defgroup doubly-linked-circular-list Circular, doubly-linked list + * + * This library provides functions for the creation and manipulation of + * circular, doubly-linked lists. + * + * A circular, doubly-linked list is declared using the DBL_CIRC_LIST macro. + * Elements must be allocated by the calling code and must be of a C struct + * datatype. In this struct, the first field must be a pointer called \e next. + * The second field must be a pointer called \e previous. + * These fields will be used by the library to maintain the list. Application + * code must not modify these fields directly. + * + * Functions that modify the list (add / remove) will, in the general case, + * update the list's head and item order. If you call one of these functions + * as part of a list traversal, it is advised to stop / restart traversing + * after the respective function returns. + * @{ + */ +/*---------------------------------------------------------------------------*/ +#ifndef DBL_CIRC_LIST_H_ +#define DBL_CIRC_LIST_H_ +/*---------------------------------------------------------------------------*/ +#include "contiki.h" + +#include +#include +#include +/*---------------------------------------------------------------------------*/ +/** + * \brief Define a circular, doubly-linked list. + * + * This macro defines a circular, doubly-linked list. + * + * The datatype for elements must be a C struct. + * The struct's first member must be a pointer called \e next. + * The second field must be a pointer called \e previous. + * These fields will be used by the library to maintain the list. Application + * code must not modify these fields directly. + * + * \param name The name of the circular, doubly-linked list. + */ +#define DBL_CIRC_LIST(name) \ + static void *name##_dbl_circ_list = NULL; \ + static dbl_list_t name = (dbl_circ_list_t)&name##_dbl_circ_list +/*---------------------------------------------------------------------------*/ +/** + * \brief The doubly-linked list datatype + */ +typedef void **dbl_circ_list_t; +/*---------------------------------------------------------------------------*/ +/** + * \brief Initialise a circular, doubly-linked list. + * \param dblcl The circular, doubly-linked list. + */ +void dbl_circ_list_init(dbl_circ_list_t dblcl); + +/** + * \brief Return the tail of a circular, doubly-linked list. + * \param dblcl The circular, doubly-linked list. + * \return A pointer to the list's head, or NULL if the list is empty + */ +void *dbl_circ_list_head(dbl_circ_list_t dblcl); + +/** + * \brief Return the tail of a circular, doubly-linked list. + * \param dblcl The circular, doubly-linked list. + * \return A pointer to the list's tail, or NULL if the list is empty + */ +void *dbl_circ_list_tail(dbl_circ_list_t dblcl); + +/** + * \brief Add an element to the head of a circular, doubly-linked list. + * \param dblcl The circular, doubly-linked list. + * \param element A pointer to the element to be added. + * + * Calling this function will update the list's head and item order. If you + * call this function as part of a list traversal, it is advised to stop + * traversing after this function returns. + */ +void dbl_circ_list_add_head(dbl_circ_list_t dblcl, void *element); + +/** + * \brief Add an element to the tail of a circular, doubly-linked list. + * \param dblcl The circular, doubly-linked list. + * \param element A pointer to the element to be added. + * + * Calling this function will update the list's head and item order. If you + * call this function as part of a list traversal, it is advised to stop + * traversing after this function returns. + */ +void dbl_circ_list_add_tail(dbl_circ_list_t dblcl, void *element); + +/** + * \brief Add an element to a circular, doubly linked list after an existing element. + * \param dblcl The circular, doubly-linked list. + * \param existing A pointer to the existing element. + * \param element A pointer to the element to be added. + * + * This function will add \e element after \e existing + * + * The function will not verify that \e existing is already part of the list. + * + * Calling this function will update the list's head and item order. If you + * call this function as part of a list traversal, it is advised to stop + * traversing after this function returns. + */ +void dbl_circ_list_add_after(dbl_circ_list_t dblcl, void *existing, + void *element); + +/** + * \brief Add an element to a circular, doubly linked list before an existing element. + * \param dblcl The circular, doubly-linked list. + * \param existing A pointer to the existing element. + * \param element A pointer to the element to be added. + * + * This function will add \e element before \e existing + * + * The function will not verify that \e existing is already part of the list. + * + * Calling this function will update the list's head and item order. If you + * call this function as part of a list traversal, it is advised to stop + * traversing after this function returns. + */ +void dbl_circ_list_add_before(dbl_circ_list_t dblcl, void *existing, + void *element); + +/** + * \brief Remove an element from a circular, doubly-linked list. + * \param dblcl The circular, doubly-linked list. + * \param element A pointer to the element to be removed. + * + * Calling this function will update the list's head and item order. If you + * call this function as part of a list traversal, it is advised to stop + * traversing after this function returns. + */ +void dbl_circ_list_remove(dbl_circ_list_t dblcl, void *element); + +/** + * \brief Get the length of a circular, doubly-linked list. + * \param dblcl The circular, doubly-linked list. + * \return The number of elements in the list + */ +unsigned long dbl_circ_list_length(dbl_circ_list_t dblcl); + +/** + * \brief Determine whether a circular, doubly-linked list is empty. + * \param dblcl The circular, doubly-linked list. + * \retval true The list is empty + * \retval false The list is not empty + */ +bool dbl_circ_list_is_empty(dbl_circ_list_t dblcl); +/*---------------------------------------------------------------------------*/ +#endif /* DBL_CIRC_LIST_H_ */ +/*---------------------------------------------------------------------------*/ +/** + * @} + * @} + */