Current File : /home/vacivi36/vittasync.vacivitta.com.br/vittasync/node/deps/cares/src/lib/ares__slist.h
/* MIT License
*
* Copyright (c) 2023 Brad House
*
* Permission is hereby granted, free of charge, to any person obtaining a copy
* of this software and associated documentation files (the "Software"), to deal
* in the Software without restriction, including without limitation the rights
* to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
* copies of the Software, and to permit persons to whom the Software is
* furnished to do so, subject to the following conditions:
*
* The above copyright notice and this permission notice (including the next
* paragraph) shall be included in all copies or substantial portions of the
* Software.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
* FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
* AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
* LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
* OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
* SOFTWARE.
*
* SPDX-License-Identifier: MIT
*/
#ifndef __ARES__SLIST_H
#define __ARES__SLIST_H
/*! \addtogroup ares__slist SkipList Data Structure
*
* This data structure is known as a Skip List, which in essence is a sorted
* linked list with multiple levels of linkage to gain some algorithmic
* advantages. The usage symantecs are almost identical to what you'd expect
* with a linked list.
*
* Average time complexity:
* - Insert: O(log n)
* - Search: O(log n)
* - Delete: O(1) -- delete assumes you hold a node pointer
*
* It should be noted, however, that "effort" involved with an insert or
* remove operation is higher than a normal linked list. For very small
* lists this may be less efficient, but for any list with a moderate number
* of entries this will prove much more efficient.
*
* This data structure is often compared with a Binary Search Tree in
* functionality and usage.
*
* @{
*/
struct ares__slist;
/*! SkipList Object, opaque */
typedef struct ares__slist ares__slist_t;
struct ares__slist_node;
/*! SkipList Node Object, opaque */
typedef struct ares__slist_node ares__slist_node_t;
/*! SkipList Node Value destructor callback
*
* \param[in] data User-defined data to destroy
*/
typedef void (*ares__slist_destructor_t)(void *data);
/*! SkipList comparison function
*
* \param[in] data1 First user-defined data object
* \param[in] data2 Second user-defined data object
* \return < 0 if data1 < data1, > 0 if data1 > data2, 0 if data1 == data2
*/
typedef int (*ares__slist_cmp_t)(const void *data1, const void *data2);
/*! Create SkipList
*
* \param[in] rand_state Initialized ares random state.
* \param[in] cmp SkipList comparison function
* \param[in] destruct SkipList Node Value Destructor. Optional, use NULL.
* \return Initialized SkipList Object or NULL on misuse or ENOMEM
*/
ares__slist_t *ares__slist_create(ares_rand_state *rand_state,
ares__slist_cmp_t cmp,
ares__slist_destructor_t destruct);
/*! Replace SkipList Node Value Destructor
*
* \param[in] list Initialized SkipList Object
* \param[in] destruct Replacement destructor. May be NULL.
*/
void ares__slist_replace_destructor(ares__slist_t *list,
ares__slist_destructor_t destruct);
/*! Insert Value into SkipList
*
* \param[in] list Initialized SkipList Object
* \param[in] val Node Value. Must not be NULL. Function takes ownership
* and will have destructor called.
* \return SkipList Node Object or NULL on misuse or ENOMEM
*/
ares__slist_node_t *ares__slist_insert(ares__slist_t *list, void *val);
/*! Fetch first node in SkipList
*
* \param[in] list Initialized SkipList Object
* \return SkipList Node Object or NULL if none
*/
ares__slist_node_t *ares__slist_node_first(ares__slist_t *list);
/*! Fetch last node in SkipList
*
* \param[in] list Initialized SkipList Object
* \return SkipList Node Object or NULL if none
*/
ares__slist_node_t *ares__slist_node_last(ares__slist_t *list);
/*! Fetch next node in SkipList
*
* \param[in] node SkipList Node Object
* \return SkipList Node Object or NULL if none
*/
ares__slist_node_t *ares__slist_node_next(ares__slist_node_t *node);
/*! Fetch previous node in SkipList
*
* \param[in] node SkipList Node Object
* \return SkipList Node Object or NULL if none
*/
ares__slist_node_t *ares__slist_node_prev(ares__slist_node_t *node);
/*! Fetch SkipList Node Object by Value
*
* \param[in] list Initialized SkipList Object
* \param[in] val Object to use for comparison
* \return SkipList Node Object or NULL if not found
*/
ares__slist_node_t *ares__slist_node_find(ares__slist_t *list, const void *val);
/*! Fetch Node Value
*
* \param[in] node SkipList Node Object
* \return user defined node value
*/
void *ares__slist_node_val(ares__slist_node_t *node);
/*! Fetch number of entries in SkipList Object
*
* \param[in] list Initialized SkipList Object
* \return number of entries
*/
size_t ares__slist_len(const ares__slist_t *list);
/*! Fetch SkipList Object from SkipList Node
*
* \param[in] node SkipList Node Object
* \return SkipList Object
*/
ares__slist_t *ares__slist_node_parent(ares__slist_node_t *node);
/*! Fetch first Node Value in SkipList
*
* \param[in] list Initialized SkipList Object
* \return user defined node value or NULL if none
*/
void *ares__slist_first_val(ares__slist_t *list);
/*! Fetch last Node Value in SkipList
*
* \param[in] list Initialized SkipList Object
* \return user defined node value or NULL if none
*/
void *ares__slist_last_val(ares__slist_t *list);
/*! Take back ownership of Node Value in SkipList, remove from SkipList.
*
* \param[in] node SkipList Node Object
* \return user defined node value
*/
void *ares__slist_node_claim(ares__slist_node_t *node);
/*! The internals of the node have changed, thus its position in the sorted
* list is no longer valid. This function will remove it and re-add it to
* the proper position without needing to perform any memory allocations
* and thus cannot fail.
*
* \param[in] node SkipList Node Object
*/
void ares__slist_node_reinsert(ares__slist_node_t *node);
/*! Remove Node from SkipList, calling destructor for Node Value.
*
* \param[in] node SkipList Node Object
*/
void ares__slist_node_destroy(ares__slist_node_t *node);
/*! Destroy SkipList Object. If there are any nodes, they will be destroyed.
*
* \param[in] list Initialized SkipList Object
*/
void ares__slist_destroy(ares__slist_t *list);
/*! @} */
#endif /* __ARES__SLIST_H */
Mini Shell