queue.h

1. #ifndef QUEUE_H
2. #define QUEUE_H
3. /*===========================================================================
5.             Q U E U E    S E R V I C E S    H E A D E R    F I L E
7. DESCRIPTION
8.  This file contains types and declarations associated with the Queue
9.  Services.与Queue Services相关的类型与声明
11. ===========================================================================*/
15. /*===========================================================================
17.                      INCLUDE FILES FOR MODULE
19. ===========================================================================*/
20. #ifdef CUST_H
21.   #include "customer.h"
22. #endif
25. /*===========================================================================
27.                         DATA DECLARATIONS
29. ===========================================================================*/
31. /* -------------------------------------------------------------------------
32. ** Queue Link Structure这个东东像一个钩子，有了它对象就可以把排在自己的前一个或后一个对象钩起来了
33. **
34. ** The following link structure is really the heart of the Queue Services. 下面的链式结构实际上是Queue Service的核心
35. ** It is used as a link field with variables which allows them to be moved 它被用作一个链域，其中的变量允许它们被移入/出队列
36. ** on and off queues. It is also used in the definition of queues themselves. 其也被用于queue们本身的定义中
37. **
38. ** Do NOT directly access the fields of a link! Only the Queue Services should
39. ** do this.
40. ** ------------------------------------------------------------------------- */
41. typedef struct q_link_struct
42. {
43.   struct q_link_struct  *next_ptr;
44.     /* Ptr to next link in list. If NULL, there is no next link. */
47. #ifndef FEATURE_Q_NO_SELF_QPTR//自我包含
49.   void                  *self_ptr;
50.     /* Ptr to item which contains this link. */
52.   struct q_struct       *q_ptr;
53.     /* Ptr to the queue on which this item is enqueued. NULL if the
54.        item is not on a queue. While not strictly necessary, this field
55.        is helpful for debugging.*/
56. #endif
58. #ifndef FEATURE_Q_SINGLE_LINK
60.   struct q_link_struct  *prev_ptr;//双向链表
62.     /* Ptr to prev link in list. If NULL, there is no prev link. */
63. #endif
65. } q_link_type;
67. /* ------------------------------------------------------------------------
68. ** Queue Head Link Structure
69. **
70. ** When queue items are linked in a singly link list, q_head_link_type is
71. ** used instead of q_link_type. This avoids the overhead of traversing 
72. ** the whole of link list when queueing at the end of the link list.
73. ** This structure should be accessed only by Queue services.
74. ** ------------------------------------------------------------------------ */
75. typedef struct q_head_link_struct
76. {
77.   struct q_link_struct  *next_ptr;//指向后一个的钩子
78.     /* Ptr to head of the link list */
80. #ifndef FEATURE_Q_NO_SELF_QPTR//自我包含
82.   void                  *self_ptr;
83.     /* Ptr to item which contains this link. */
85.   struct q_struct       *q_ptr;
86.     /* Ptr to the queue on which this item is enqueued. NULL if the
87.        item is not on a queue. While not strictly necessary, this field
88.        is helpful for debugging.*/
89. #endif
91.   struct q_link_struct  *prev_ptr;//头指针比较特殊，它有指向尾部的钩子
92.     /* Ptr to the tail of link list */
94. } q_head_link_type;
97. //
98. //双向链表没有用到q_head_link_type，这里的q_head_link_type相当于双向链表中的q_link_type
99. //
100. //
103. /* ------------------------------------------------------------------------
104. ** Queue Structure
105. **
106. ** The following structure format is used by the Queue Services to represent
107. ** a queue.下面的结构被Queue Service用来代表一个队列－－队列结构
108. ** 
109. ** Do NOT access the fields of a queue directly. Only the Queue Services should
110. ** do this.不要直接访问一个队列的这个域，只有Queue Service才可以这样做
111. ** ------------------------------------------------------------------------ */
112. typedef struct q_struct
113. {
114.     //link代表头指针(的钩子)
115. #ifdef FEATURE_Q_SINGLE_LINK
116.   q_head_link_type  link;//单向链表的头指针比其它指针多了一个前向指针元素
117. #else
118.   q_link_type  link;//双向链表，头指针与其它指针相同
119. #endif
120.     /* Used for linking items into queue. 用于把items链到队列内*/
122.   int          cnt;
123.     /* Keeps track of number of items enqueued. Though not necessary, having
124.        this field is tremendously helpful for debugging. *///跟踪队列中元素的数目，虽不必需但对调试很有用
126. #ifdef FEATURE_Q_WIN32_LOCKS
127.   void        *mutex;//线程安全
128. #endif
129. } q_type;
131. /* ------------------------------------------------------------------------
132. ** Queue Generic Item
133. **   Generic items must have q_link_type as the first element.  This allows 每个item必需把它作为自己的第一个(域？)
134. **   the linear search function to traverse the list without knowing 这可以让线性查找函数在不了解它的情况下遍历此链
135. **   anything about the elements
136. ** ------------------------------------------------------------------------ */
137. typedef struct {
138.    q_link_type link;
139. } q_generic_item_type;
141. /* ------------------------------------------------------------------------
142. ** Queue Compare Function
143. **    Used by the searching functions to determine if an item is in
144. **       the queue.查找函数用它判断是否某个元素在链表中
145. **    Returns non zero if the element should be operated upon, 0 otherwise
146. **    For linear searching, the operation is to return a pointer to the
147. **       item and terminate the search
148. **    For linear deleting, the operation is to remove the item from the
149. **       queue and continue the traversal
150. ** ------------------------------------------------------------------------ */
151. typedef int (*q_compare_func_type)( void* item_ptr, void* compare_val );
153. /* ------------------------------------------------------------------------
154. ** Queue Action Function
155. **    Used by q_linear_delete to perform an action on an item which is 
156. **    being deleted from the list AFTER the item is deleted.  To perform
157. **    an action BEFORE the item is deleted, the user can call the action
158. **    function directly in the compare function call back.
159. ** ------------------------------------------------------------------------ */
160. typedef void (*q_action_func_type)( void *item_ptr, void* param );
162. /*===========================================================================
164.                              Macro Definitions
166. ===========================================================================*/
168. #ifdef PC_EMULATOR_H//pc机上模拟
169.   #ifdef Q_RENAME
170.     #define PC_EMULATOR_QUEUE
171.     #include PC_EMULATOR_H
172.   #endif
174.   #ifdef Q_XCEPT
175.     #define PC_EMULATOR_Q_XCEPT
176.     #include PC_EMULATOR_H
177.   #endif
178. #endif
180. #if !defined(PC_EMULATOR_H) || !defined(Q_XCEPT)
181.   #define Q_XCEPT_Q_INIT( q_ptr )
182.   #define Q_XCEPT_Q_LINK( q_ptr, link_ptr )
183.   #define Q_XCEPT_Q_PUT( q_ptr, link_ptr )
184.   #define Q_XCEPT_Q_GET( q_ptr )
185.   #define Q_XCEPT_Q_LAST_GET( q_ptr )
186.   #define Q_XCEPT_Q_CNT( q_ptr )
187.   #define Q_XCEPT_Q_CHECK( q_ptr )
188.   #define Q_XCEPT_Q_LAST_CHECK( q_ptr )
189.   #define Q_XCEPT_Q_NEXT( q_ptr, link_ptr )
190.   #ifdef FEATURE_Q_NO_SELF_QPTR
191.     #define Q_XCEPT_Q_INSERT( q_ptr, q_insert_ptr, q_item_ptr )
192.   #else
193.     #define Q_XCEPT_Q_INSERT( q_insert_ptr, q_item_ptr )
194.   #endif
195.   #ifdef FEATURE_Q_NO_SELF_QPTR
196.     #define Q_XCEPT_Q_DELETE( q_ptr, q_delete_ptr )
197.   #else
198.     #define Q_XCEPT_Q_DELETE( q_delete_ptr )
199.   #endif
200. #endif
202. /* ========================================================================
203. MACRO Q_ALREADY_QUEUED
204. DESCRIPTION
205.    Evaluates to true if the item passed in is already in a queue and to
206.    false otherwise.
207. =========================================================================== */
208. #define Q_ALREADY_QUEUED( q_link_ptr ) /
209.    ((q_link_ptr)->next_ptr != NULL)//q_link_ptr表示一链表而非链表中的一元素///错误!
211. /*===========================================================================
213.                             Function Declarations
215. ===========================================================================*/
216. #ifdef __cplusplus
217.    extern "C" {
218. #endif
220. /*==========================================================================
222. FUNCTION Q_INIT
224. DESCRIPTION
225.   This function initializes a specified queue. It should be called for each
226.   queue prior to using the queue with the other Queue Services.
228. DEPENDENCIES
229.   None.
231. RETURN VALUE
232.   A pointer to the initialized queue.
234. SIDE EFFECTS
235.   The specified queue is initialized for use with Queue Services.
237. ===========================================================================*/
238. q_type* q_init ( q_type *q_ptr );
241. /*===========================================================================
243. FUNCTION Q_LINK
245. DESCRIPTION
246.   This function initializes a specified link. It should be called for each
247.   link prior to using the link with the other Queue Services.
249. DEPENDENCIES
250.   None.
252. RETURN VALUE
253.   A pointer to the initialized link.
255. SIDE EFFECTS
256.   The specified link is initialized for use with the Queue Services.
258. ===========================================================================*/
259. q_link_type* q_link ( void *item_ptr, q_link_type *link_ptr );
262. /*===========================================================================
264. FUNCTION Q_PUT
266. DESCRIPTION
267.   This function enqueues an item onto a specified queue using a specified
268.   link.
270. DEPENDENCIES
271.   The specified queue should have been previously initialized via a call
272.   to q_init. The specified link field of the item should have been prev-
273.   iously initialized via a call to q_init_link.
275. RETURN VALUE
276.   None.
278. SIDE EFFECTS
279.   The specified item is placed at the tail of the specified queue.
281. ===========================================================================*/
282. void  q_put  ( q_type *q_ptr, q_link_type *link_ptr );
285. /*===========================================================================
287. FUNCTION Q_GET
289. DESCRIPTION
290.   This function removes an item from the head of a specified queue.
292. DEPENDENCIES
293.   The specified queue should have been initialized previously via a call
294.   to q_init.
296. RETURN VALUE
297.   A pointer to the dequeued item. If the specified queue is empty, then
298.   NULL is returned.
300. SIDE EFFECTS
301.   The head item, if any, is removed from the specified queue.
303. ===========================================================================*/
304. void* q_get ( q_type *q_ptr );
306. /*===========================================================================
308. FUNCTION Q_LAST_GET
310. DESCRIPTION
311.   This function removes an item from the tail of a specified queue.
313. DEPENDENCIES
314.   The specified queue should have been initialized previously via a call
315.   to q_init.
317. RETURN VALUE
318.   A pointer to the dequeued item. If the specified queue is empty, then
319.   NULL is returned.
321. SIDE EFFECTS
322.   The head item, if any, is removed from the specified queue.
324. ===========================================================================*/
325. void* q_last_get ( q_type *q_ptr );
329. /*===========================================================================
331. FUNCTION Q_CNT
333. DESCRIPTION
334.   This function returns the number of items currently queued on a specified
335.   queue.
337. DEPENDENCIES
338.   The specified queue should have been initialized previously via a call
339.   to q_init.
341. RETURN VALUE
342.   The number of items currently queued on the specified queue.
344. SIDE EFFECTS
345.   None.
347. ===========================================================================*/
348. int q_cnt  ( q_type *q_ptr );
351. /*===========================================================================
353. FUNCTION Q_CHECK
355. DESCRIPTION
356.   This function returns a pointer to the data block at the head of the queue.
357.   The data block is not removed from the queue.
359. DEPENDENCIES
360.   The specified queue should have been initialized previously via a call
361.   to q_init.
363. RETURN VALUE
364.   A pointer to the queue item. If the specified queue is empty, then
365.   NULL is returned.
367. SIDE EFFECTS
368.   None
370. ===========================================================================*/
371. void* q_check (q_type  *q_ptr);
374. /*===========================================================================
376. FUNCTION Q_LAST_CHECK
378. DESCRIPTION
379.   This function returns a pointer to the data block at the tail of the queue.
380.   The data block is not removed from the queue.
382. DEPENDENCIES
383.   The specified queue should have been initialized previously via a call
384.   to q_init.
386. RETURN VALUE
387.   A pointer to the queue item. If the specified queue is empty, then
388.   NULL is returned.
390. SIDE EFFECTS
391.   The head item, if any, is removed from the specified queue.
393. ===========================================================================*/
394. void* q_last_check ( q_type *q_ptr );
397. /*===========================================================================
399. FUNCTION Q_NEXT
401. DESCRIPTION
402.   This function returns a pointer to the next item on the queue.
404. DEPENDENCIES
405.   The specified queue should have been initialized previously via a call
406.   to q_init.
408. RETURN VALUE
409.   A pointer to the next item on the queue. If the end of the queue is reached, 
410.   then NULL is returned.
412. SIDE EFFECTS
413.   None.
415. ===========================================================================*/
416. void* q_next  ( q_type *q_ptr, q_link_type *link_ptr );
419. /*===========================================================================
421. FUNCTION Q_INSERT
423. DESCRIPTION
424.   This function inserts an item before a specified item on a queue.
426. DEPENDENCIES
427.   The specified queue should have been initialized previously via a call
428.   to q_init.
430. RETURN VALUE
431.   None.
433. SIDE EFFECTS
434.   Input item is inserted before input item.
436. ===========================================================================*/
437. #ifdef FEATURE_Q_NO_SELF_QPTR
438.    void q_insert  ( q_type *q_ptr, q_link_type *q_insert_ptr, q_link_type *q_item_ptr );
439. #else
440.    void q_insert  ( q_link_type *q_insert_ptr, q_link_type *q_item_ptr );
441. #endif
444. /*===========================================================================
446. FUNCTION Q_DELETE
448. DESCRIPTION
449.   This function removes an item from a specified queue.
451. DEPENDENCIES
452.   The specified queue should have been initialized previously via a call
453.   to q_init.
455. RETURN VALUE
456.   None.
458. SIDE EFFECTS
459.   Input item is delete from the queue.
461. ===========================================================================*/
462. #ifdef FEATURE_Q_NO_SELF_QPTR
463.    void q_delete  ( q_type *q_ptr, q_link_type *q_delete_ptr );
464. #else
465.    void q_delete  ( q_link_type *q_delete_ptr );
466. #endif
469. /*===========================================================================
471. FUNCTION Q_LINEAR_SEARCH
473. DESCRIPTION
474.   Given a comparison function, this function traverses the elements in
475.   a queue, calls the compare function, and returns a pointer to the
476.   current element being compared if the user passed compare function
477.   returns non zero.
479.   The user compare function should return 0 if the current element is
480.   not the element in which the compare function is interested.
482. DEPENDENCIES
483.   The specified queue should have been initialized previously via a call
484.   to q_init.
486.   The user's queue elements must have q_link_type as the first element
487.   of the queued structure.
489. RETURN VALUE
490.   A pointer to the found element
492. SIDE EFFECTS
493.   None.
495. ===========================================================================*/
496. void* q_linear_search(
497.   q_type             *q_ptr,  
498.   q_compare_func_type compare_func,
499.   void               *compare_val
500. );
502. #if defined FEATURE_Q_NO_SELF_QPTR && defined FEATURE_Q_SINGLE_LINK
503. /*===========================================================================
505. FUNCTION Q_LINEAR_DELETE
507. DESCRIPTION
508.   Given a comparison function, this function traverses the elements in
509.   a queue, calls the compare function, and returns a pointer to the
510.   current element being compared if the user passed compare function
511.   returns non zero.  In addition, the item will be removed from the queue.
513.   The user compare function should return 0 if the current element is
514.   not the element in which the compare function is interested.
516. DEPENDENCIES
517.   The specified queue should have been initialized previously via a call
518.   to q_init.
520.   The user's queue elements must have q_link_type as the first element
521.   of the queued structure.
523.   The user's compare function will be passed NULL for the compare value.
525. RETURN VALUE
526.   None
528. SIDE EFFECTS
529.   None.
531. ===========================================================================*/
532. void q_linear_delete(
533.   q_type             *q_ptr,  
534.   q_compare_func_type compare_func,
535.   void               *param,
536.   q_action_func_type  action_func
537. );
539. #endif
541. #ifdef __cplusplus
542.    }
543. #endif
545. #endif /* QUEUE_H */