Cleanup: remove redundant doxygen \file argument
[blender.git] / source / blender / blenlib / BLI_linklist_lockfree.h
1 /*
2  * This program is free software; you can redistribute it and/or
3  * modify it under the terms of the GNU General Public License
4  * as published by the Free Software Foundation; either version 2
5  * of the License, or (at your option) any later version.
6  *
7  * This program is distributed in the hope that it will be useful,
8  * but WITHOUT ANY WARRANTY; without even the implied warranty of
9  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
10  * GNU General Public License for more details.
11  *
12  * You should have received a copy of the GNU General Public License
13  * along with this program; if not, write to the Free Software Foundation,
14  * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
15  *
16  * The Original Code is Copyright (C) 2018 Blender Foundation.
17  * All rights reserved.
18  */
19
20 #ifndef __BLI_LINKLIST_LOCKFREE_H__
21 #define __BLI_LINKLIST_LOCKFREE_H__
22
23 /** \file \ingroup bli
24  */
25
26 #ifdef __cplusplus
27 extern "C" {
28 #endif
29
30 typedef struct LockfreeLinkNode {
31         struct LockfreeLinkNode *next;
32         /* NOTE: "Subclass" this structure to add custom-defined data. */
33 } LockfreeLinkNode;
34
35 typedef struct LockfreeLinkList {
36         /* We keep a dummy node at the beginning of the list all the time.
37          * This allows us to make sure head and tail pointers are always
38          * valid, and saves from annoying exception cases in insert().
39          */
40         LockfreeLinkNode dummy_node;
41         /* NOTE: This fields might point to a dummy node. */
42         LockfreeLinkNode *head, *tail;
43 } LockfreeLinkList;
44
45 typedef void (*LockfreeeLinkNodeFreeFP)(void *link);
46
47 /* ************************************************************************** */
48 /* NOTE: These functions are NOT safe for use from threads. */
49 /* NOTE: !!! I REPEAT: DO NOT USE THEM WITHOUT EXTERNAL LOCK !!! */
50
51 /* Make list ready for lock-free access. */
52 void BLI_linklist_lockfree_init(LockfreeLinkList *list);
53
54 /* Completely free the whole list, it is NOT re-usable after this. */
55 void BLI_linklist_lockfree_free(LockfreeLinkList *list,
56                                 LockfreeeLinkNodeFreeFP free_func);
57
58 /* Remove all the elements from the list, keep it usable for further
59  * inserts.
60  */
61 void BLI_linklist_lockfree_clear(LockfreeLinkList *list,
62                                  LockfreeeLinkNodeFreeFP free_func);
63
64
65 /* Begin iteration of lock-free linked list, starting with a
66  * first user=defined node. Will ignore the dummy node.
67  */
68 LockfreeLinkNode *BLI_linklist_lockfree_begin(LockfreeLinkList *list);
69
70
71 /* ************************************************************************** */
72 /* NOTE: These functions are safe for use from threads. */
73
74 void BLI_linklist_lockfree_insert(LockfreeLinkList *list,
75                                   LockfreeLinkNode *node);
76
77 #ifdef __cplusplus
78 }
79 #endif
80
81 #endif  /* __BLI_LINKLIST_H__ */