1/*****************************************************************************
2
3Copyright (c) 2006, 2016, Oracle and/or its affiliates. All Rights Reserved.
4
5This program is free software; you can redistribute it and/or modify it under
6the terms of the GNU General Public License as published by the Free Software
7Foundation; version 2 of the License.
8
9This program is distributed in the hope that it will be useful, but WITHOUT
10ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
11FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
12
13You should have received a copy of the GNU General Public License along with
14this program; if not, write to the Free Software Foundation, Inc.,
1551 Franklin Street, Suite 500, Boston, MA 02110-1335 USA
16
17*****************************************************************************/
18
19/*******************************************************************//**
20@file include/ut0list.h
21A double-linked list
22
23Created 4/26/2006 Osku Salerma
24************************************************************************/
25
26/*******************************************************************//**
27A double-linked list. This differs from the one in ut0lst.h in that in this
28one, each list node contains a pointer to the data, whereas the one in
29ut0lst.h uses a strategy where the list pointers are embedded in the data
30items themselves.
31
32Use this one when you need to store arbitrary data in the list where you
33can't embed the list pointers in the data, if a data item needs to be
34stored in multiple lists, etc.
35
36Note about the memory management: ib_list_t is a fixed-size struct whose
37allocation/deallocation is done through ib_list_create/ib_list_free, but the
38memory for the list nodes is allocated through a user-given memory heap,
39which can either be the same for all nodes or vary per node. Most users will
40probably want to create a memory heap to store the item-specific data, and
41pass in this same heap to the list node creation functions, thus
42automatically freeing the list node when the item's heap is freed.
43
44************************************************************************/
45
46#ifndef IB_LIST_H
47#define IB_LIST_H
48
49#include "mem0mem.h"
50
51struct ib_list_t;
52struct ib_list_node_t;
53
54/****************************************************************//**
55Create a new list using mem_alloc. Lists created with this function must be
56freed with ib_list_free.
57@return list */
58ib_list_t*
59ib_list_create(void);
60/*=================*/
61
62/****************************************************************//**
63Free a list. */
64void
65ib_list_free(
66/*=========*/
67 ib_list_t* list); /*!< in: list */
68
69/****************************************************************//**
70Add the data to the end of the list.
71@return new list node */
72ib_list_node_t*
73ib_list_add_last(
74/*=============*/
75 ib_list_t* list, /*!< in: list */
76 void* data, /*!< in: data */
77 mem_heap_t* heap); /*!< in: memory heap to use */
78
79/****************************************************************//**
80Remove the node from the list. */
81void
82ib_list_remove(
83/*===========*/
84 ib_list_t* list, /*!< in: list */
85 ib_list_node_t* node); /*!< in: node to remove */
86
87/****************************************************************//**
88Get the first node in the list.
89@return first node, or NULL */
90UNIV_INLINE
91ib_list_node_t*
92ib_list_get_first(
93/*==============*/
94 ib_list_t* list); /*!< in: list */
95
96/****************************************************************//**
97Get the last node in the list.
98@return last node, or NULL */
99UNIV_INLINE
100ib_list_node_t*
101ib_list_get_last(
102/*=============*/
103 ib_list_t* list); /*!< in: list */
104
105/********************************************************************
106Check if list is empty. */
107UNIV_INLINE
108ibool
109ib_list_is_empty(
110/*=============*/
111 /* out: TRUE if empty else */
112 const ib_list_t* list); /* in: list */
113
114/********************************************************************
115Get number of items on list.
116@return number of items on list */
117UNIV_INLINE
118ulint
119ib_list_len(
120/*========*/
121 const ib_list_t* list); /*<! in: list */
122
123/* List. */
124struct ib_list_t {
125 ib_list_node_t* first; /*!< first node */
126 ib_list_node_t* last; /*!< last node */
127};
128
129/* A list node. */
130struct ib_list_node_t {
131 ib_list_node_t* prev; /*!< previous node */
132 ib_list_node_t* next; /*!< next node */
133 void* data; /*!< user data */
134};
135
136/* Quite often, the only additional piece of data you need is the per-item
137memory heap, so we have this generic struct available to use in those
138cases. */
139struct ib_list_helper_t {
140 mem_heap_t* heap; /*!< memory heap */
141 void* data; /*!< user data */
142};
143
144#include "ut0list.ic"
145
146#endif
147