sys/mips/include/queue.h

   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$
  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__ */