1 /*-
2 * Copyright (c) 1996-1997, 2001, 2005, Juniper Networks, Inc.
3 * All rights reserved.
4 * Jim Hayes, November 1996
5 *
6 * queue.h - Description of uKernel queues, for the Juniper Kernel
7 *
8 * JNPR: queue.h,v 1.1 2006/08/07 05:38:57 katta
9 * $FreeBSD: releng/8.1/sys/mips/include/queue.h 178172 2008-04-13 07:27:37Z imp $
10 *
11 */
12
13 #ifndef __QUEUE_H__
14 #define __QUEUE_H__
15
16 /*---------------------------------------------------------------------------
17 * QUEUE MANAGEMENT DOCUMENTATION
18 */
19
20 /*
21 --------
22 Q_INIT()
23 --------
24
25 void q_init(void)
26
27 Initialize the queue management system for the microkernel.
28 This initializes the debugging flags and sets up accounting.
29
30 ---------
31 Q_ALLOC()
32 ---------
33
34 queue_t *q_alloc()
35
36 Allocates a queue from kernel memory, and initializes it for you.
37
38 The default initialization provides a queue that is unbounded.
39
40 If you want to be bounded with special features, use q_control
41 after initialization.
42
43 q_alloc() returns NULL in the face of peril or low memory.
44
45 --------
46 Q_FREE()
47 --------
48
49 void *q_free(queue_t *queue_pointer)
50
51 Returns a queue to kernel memory, and frees the queue contents
52 for you using free() and complains (with a traceback) that you
53 tried to kill of a non-empty queue.
54
55 If any threads are waiting on the queue, wake them up.
56
57 -----------
58 Q_CONTROL()
59 -----------
60 void q_control(queue_t *queue_pointer, queue_size_t max_queue_size);
61
62 For now, allows you to limit queue growth.
63
64 ----------------
65 Q_DEQUEUE_WAIT() ** MAY CAUSE THREAD TO BLOCK/CANNOT BE CALLED FROM ISRs **
66 ----------------
67
68 void *q_dequeue_wait(queue_t *queue_pointer, wakeup_mask_t *mask)
69
70 Removes and returns a pointer to the next message in the specified
71 queue. If the queue is empty, the calling thread goes to sleep
72 until something is queued to the queue. If this call returns NULL,
73 then an extraordinary event requires this thread's attention--
74 check errno in this case.
75
76 ---------
77 Q_DEQUEUE ** CAN BE CALLED FROM ISRs **
78 ---------
79
80 void *q_dequeue(queue_t *queue_pointer)
81
82 Just like q_dequeue_wait(), but instead of blocking, return NULL.
83
84 -----------
85 Q_ENQUEUE() ** CAN BE CALLED FROM ISRs **
86 -----------
87
88 boolean q_enqueue(queue_t *queue_pointer, void *element_pointer)
89
90 Add the element to the end of the named queue. If the add fails
91 because a limit has been reached, return TRUE. Otherwise return
92 FALSE if everything went OK.
93
94 ----------
95 Q_URGENT()
96 ----------
97
98 boolean q_urgent(queue_t *queue_pointer, void *element_pointer)
99
100 Same as q_enqueue(), except this element will be placed at the top
101 of the queue, and will be picked off at the next q_dequeue_wait()
102 operation.
103
104 --------
105 Q_PEEK() ** CAN BE CALLED FROM ISRs **
106 --------
107
108 void *q_peek(queue_t *queue_pointer)
109
110 Returns a pointer to the top element of the queue without actually
111 dequeuing it. Returns NULL of the queue is empty.
112
113 This routine will never block.
114
115 ----------
116 Q_DELETE()
117 ----------
118
119 void q_delete(queue_t *queue_pointer, void *element_pointer)
120
121 Delete the element_pointer from the queue, if it exists. This
122 isn't speedy, and isn't meant for tasks requiring performance.
123 It's primary use is to pull something off the queue when you know
124 in the common case that it's gonna be at or near the top of the
125 list. (I.e. waking a thread from a wake list when extraordinary
126 conditions exist, and you have to pluck it from the middle of the
127 list.)
128
129 This routine does not block or return anything.
130
131 --------
132 Q_SIZE()
133 --------
134
135 queue_size_t q_size(queue_t *queue_pointer)
136
137 Returns the number of elements in the queue.
138
139 ------------
140 Q_MAX_SIZE()
141 ------------
142
143 queue_size_t q_max_size(queue_t *queue_pointer);
144
145 Returns the maximum size of this queue, or 0 if this queue is
146 unbounded.
147
148 */
149
150 /*-------------------------------------------------------------------------
151 * Basic queue management structures.
152 */
153
154 /*
155 * Typedefs
156 */
157
158 typedef u_int32_t queue_size_t;
159
160 /*
161 * Prototypes
162 */
163
164 void q_init(void);
165 queue_t *q_alloc(void);
166 void *q_peek(queue_t *queue);
167 void *q_dequeue(queue_t *queue);
168 boolean q_enqueue(queue_t *queue, void *item);
169 boolean q_urgent(queue_t *queue, void *item);
170
171 #endif /* __QUEUE_H__ */
Cache object: 0ff1ff9a319f696f1adb81adc9291540
|