git/list.h

208 lines
5.6 KiB
C
Raw Normal View History

/*
* Copyright (C) 2002 Free Software Foundation, Inc.
* (originally part of the GNU C Library and Userspace RCU)
* Contributed by Ulrich Drepper <drepper@redhat.com>, 2002.
*
* Copyright (C) 2009 Pierre-Marc Fournier
* Conversion to RCU list.
* Copyright (C) 2010 Mathieu Desnoyers <mathieu.desnoyers@efficios.com>
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
* License as published by the Free Software Foundation; either
* version 2.1 of the License, or (at your option) any later version.
*
* This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public
* License along with this library; if not, see
* <https://www.gnu.org/licenses/>.
*/
#ifndef LIST_H
#define LIST_H 1
/*
* The definitions of this file are adopted from those which can be
* found in the Linux kernel headers to enable people familiar with the
* latter find their way in these sources as well.
*/
/* Basic type for the double-link list. */
struct list_head {
struct list_head *next, *prev;
};
/* avoid conflicts with BSD-only sys/queue.h */
#undef LIST_HEAD
/* Define a variable with the head and tail of the list. */
#define LIST_HEAD(name) \
struct list_head name = { &(name), &(name) }
/* Initialize a new list head. */
#define INIT_LIST_HEAD(ptr) \
(ptr)->next = (ptr)->prev = (ptr)
#define LIST_HEAD_INIT(name) { \
.next = &(name), \
.prev = &(name), \
}
/* Add new element at the head of the list. */
static inline void list_add(struct list_head *newp, struct list_head *head)
{
head->next->prev = newp;
newp->next = head->next;
newp->prev = head;
head->next = newp;
}
/* Add new element at the tail of the list. */
static inline void list_add_tail(struct list_head *newp, struct list_head *head)
{
head->prev->next = newp;
newp->next = head;
newp->prev = head->prev;
head->prev = newp;
}
/* Remove element from list. */
static inline void __list_del(struct list_head *prev, struct list_head *next)
{
next->prev = prev;
prev->next = next;
}
/* Remove element from list. */
static inline void list_del(struct list_head *elem)
{
__list_del(elem->prev, elem->next);
}
/* Remove element from list, initializing the element's list pointers. */
static inline void list_del_init(struct list_head *elem)
{
list_del(elem);
INIT_LIST_HEAD(elem);
}
/* Delete from list, add to another list as head. */
static inline void list_move(struct list_head *elem, struct list_head *head)
{
__list_del(elem->prev, elem->next);
list_add(elem, head);
}
/* Replace an old entry. */
static inline void list_replace(struct list_head *old, struct list_head *newp)
{
newp->next = old->next;
newp->prev = old->prev;
newp->prev->next = newp;
newp->next->prev = newp;
}
/* Join two lists. */
static inline void list_splice(struct list_head *add, struct list_head *head)
{
/* Do nothing if the list which gets added is empty. */
if (add != add->next) {
add->next->prev = head;
add->prev->next = head->next;
head->next->prev = add->prev;
head->next = add->next;
}
}
/* Get typed element from list at a given position. */
#define list_entry(ptr, type, member) \
((type *) ((char *) (ptr) - offsetof(type, member)))
/* Get first entry from a list. */
#define list_first_entry(ptr, type, member) \
list_entry((ptr)->next, type, member)
/* Iterate forward over the elements of the list. */
#define list_for_each(pos, head) \
for (pos = (head)->next; pos != (head); pos = pos->next)
/*
* Iterate forward over the elements list. The list elements can be
* removed from the list while doing this.
*/
#define list_for_each_safe(pos, p, head) \
for (pos = (head)->next, p = pos->next; \
pos != (head); \
pos = p, p = pos->next)
/* Iterate backward over the elements of the list. */
#define list_for_each_prev(pos, head) \
for (pos = (head)->prev; pos != (head); pos = pos->prev)
/*
* Iterate backwards over the elements list. The list elements can be
* removed from the list while doing this.
*/
#define list_for_each_prev_safe(pos, p, head) \
for (pos = (head)->prev, p = pos->prev; \
pos != (head); \
pos = p, p = pos->prev)
static inline int list_empty(struct list_head *head)
{
return head == head->next;
}
static inline void list_replace_init(struct list_head *old,
struct list_head *newp)
{
struct list_head *head = old->next;
list_del(old);
list_add_tail(newp, head);
INIT_LIST_HEAD(old);
}
tempfile: use list.h for linked list The tempfile API keeps to-be-cleaned tempfiles in a singly-linked list and never removes items from the list. A future patch would like to start removing items, but removal from a singly linked list is O(n), as we have to walk the list to find the predecessor element. This means that a process which takes "n" simultaneous lockfiles (for example, an atomic transaction on "n" refs) may end up quadratic in "n". Before we start allowing items to be removed, it would be nice to have a way to cover this case in linear time. The simplest solution is to make an assumption about the order in which tempfiles are added and removed from the list. If both operations iterate over the tempfiles in the same order, then by putting new items at the end of the list our removal search will always find its items at the beginning of the list. And indeed, that would work for the case of refs. But it creates a hidden dependency between unrelated parts of the code. If anybody changes the ref code (or if we add a new caller that opens multiple simultaneous tempfiles) they may unknowingly introduce a performance regression. Another solution is to use a better data structure. A doubly-linked list works fine, and we already have an implementation in list.h. But there's one snag: the elements of "struct tempfile" are all marked as "volatile", since a signal handler may interrupt us and iterate over the list at any moment (even if we were in the middle of adding a new entry). We can declare a "volatile struct list_head", but we can't actually use it with the normal list functions. The compiler complains about passing a pointer-to-volatile via a regular pointer argument. And rightfully so, as the sub-function would potentially need different code to deal with the volatile case. That leaves us with a few options: 1. Drop the "volatile" modifier for the list items. This is probably a bad idea. I checked the assembly output from "gcc -O2", and the "volatile" really does impact the order in which it updates memory. 2. Use macros instead of inline functions. The irony here is that list.h is entirely implemented as trivial inline functions. So we basically are already generating custom code for each call. But sadly there's no way in C to declare the inline function to take a more generic type. We could do so by switching the inline functions to macros, but it does make the end result harder to read. And it doesn't fully solve the problem (for instance, the declaration of list_head needs to change so that its "prev" and "next" pointers point to other volatile structs). 3. Don't use list.h, and just make our own ad-hoc doubly-linked list. It's not that much code to implement the basics that we need here. But if we're going to do so, why not add the few extra lines required to model it after the actual list.h interface? We can even reuse a few of the macro helpers. So this patch takes option 3, but actually implements a parallel "volatile list" interface in list.h, where it could potentially be reused by other code. This implements just enough for tempfile.c's use, though we could easily port other functions later if need be. Signed-off-by: Jeff King <peff@peff.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2017-09-05 20:15:00 +08:00
/*
* This is exactly the same as a normal list_head, except that it can be
* declared volatile (e.g., if you have a list that may be accessed from signal
* handlers).
*/
struct volatile_list_head {
volatile struct volatile_list_head *next, *prev;
};
#define VOLATILE_LIST_HEAD(name) \
volatile struct volatile_list_head name = { &(name), &(name) }
static inline void __volatile_list_del(volatile struct volatile_list_head *prev,
volatile struct volatile_list_head *next)
{
next->prev = prev;
prev->next = next;
}
static inline void volatile_list_del(volatile struct volatile_list_head *elem)
{
__volatile_list_del(elem->prev, elem->next);
}
static inline int volatile_list_empty(volatile struct volatile_list_head *head)
{
return head == head->next;
}
static inline void volatile_list_add(volatile struct volatile_list_head *newp,
volatile struct volatile_list_head *head)
{
head->next->prev = newp;
newp->next = head->next;
newp->prev = head;
head->next = newp;
}
#endif /* LIST_H */