Moved data structures to new collections subfolder
[strongswan.git] / src / libstrongswan / collections / blocking_queue.h
1 /*
2 * Copyright (C) 2012 Tobias Brunner
3 * Copyright (C) 2012 Giuliano Grassi
4 * Copyright (C) 2012 Ralf Sager
5 * Hochschule fuer Technik Rapperswil
6 *
7 * This program is free software; you can redistribute it and/or modify it
8 * under the terms of the GNU General Public License as published by the
9 * Free Software Foundation; either version 2 of the License, or (at your
10 * option) any later version. See <http://www.fsf.org/copyleft/gpl.txt>.
11 *
12 * This program is distributed in the hope that it will be useful, but
13 * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
14 * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
15 * for more details.
16 */
17
18 /**
19 * @defgroup blocking_queue blocking_queue
20 * @{ @ingroup collections
21 */
22
23 #ifndef BLOCKING_QUEUE_H_
24 #define BLOCKING_QUEUE_H_
25
26 typedef struct blocking_queue_t blocking_queue_t;
27
28 #include <library.h>
29
30 /**
31 * Class implementing a synchronized blocking queue based on linked_list_t
32 */
33 struct blocking_queue_t {
34
35 /**
36 * Inserts a new item at the tail of the queue
37 *
38 * @param item item to insert in queue
39 */
40 void (*enqueue)(blocking_queue_t *this, void *item);
41
42 /**
43 * Removes the first item in the queue and returns its value.
44 * If the queue is empty, this call blocks until a new item is inserted.
45 *
46 * @note This is a thread cancellation point
47 *
48 * @return removed item
49 */
50 void *(*dequeue)(blocking_queue_t *this);
51
52 /**
53 * Destroys a blocking_queue_t object.
54 *
55 * @note No thread must wait in dequeue() when this function is called
56 */
57 void (*destroy)(blocking_queue_t *this);
58
59 /**
60 * Destroys a queue and its objects using the given destructor.
61 *
62 * If a queue and the contained objects should be destroyed, use
63 * destroy_offset. The supplied offset specifies the destructor to
64 * call on each object. The offset may be calculated using the offsetof
65 * macro, e.g.: queue->destroy_offset(queue, offsetof(object_t, destroy));
66 *
67 * @note No thread must wait in dequeue() when this function is called
68 *
69 * @param offset offset of the objects destructor
70 */
71 void (*destroy_offset)(blocking_queue_t *this, size_t offset);
72
73 /**
74 * Destroys a queue and its objects using a cleanup function.
75 *
76 * If a queue and its contents should get destroyed using a specific
77 * cleanup function, use destroy_function. This is useful when the
78 * list contains malloc()-ed blocks which should get freed,
79 * e.g.: queue->destroy_function(queue, free);
80 *
81 * @note No thread must wait in dequeue() when this function is called
82 *
83 * @param function function to call on each object
84 */
85 void (*destroy_function)(blocking_queue_t *this, void (*)(void*));
86
87 };
88
89 /**
90 * Creates an empty queue object.
91 *
92 * @return blocking_queue_t object.
93 */
94 blocking_queue_t *blocking_queue_create();
95
96 #endif /** BLOCKING_QUEUE_H_ @}*/
97