"queue" -- Queue class
**********************

Synchronized queues.

The "eventlet.queue" module implements multi-producer, multi-consumer
queues that work across greenlets, with the API similar to the classes
found in the standard "Queue" and "multiprocessing" modules.

A major difference is that queues in this module operate as channels
when initialized with *maxsize* of zero. In such case, both
"Queue.empty()" and "Queue.full()" return "True" and "Queue.put()"
always blocks until a call to "Queue.get()" retrieves the item.

An interesting difference, made possible because of greenthreads, is
that "Queue.qsize()", "Queue.empty()", and "Queue.full()" *can* be
used as indicators of whether the subsequent "Queue.get()" or
"Queue.put()" will not block.  The new methods "Queue.getting()" and
"Queue.putting()" report on the number of greenthreads blocking in
"put" or "get" respectively.

exception eventlet.queue.Empty

   Exception raised by Queue.get(block=0)/get_nowait().

exception eventlet.queue.Full

   Exception raised by Queue.put(block=0)/put_nowait().

class eventlet.queue.LifoQueue(maxsize=None)

   A subclass of "Queue" that retrieves most recently added entries
   first.

class eventlet.queue.LightQueue(maxsize=None)

   This is a variant of Queue that behaves mostly like the standard
   "Stdlib_Queue".  It differs by not supporting the "task_done" or
   "join" methods, and is a little faster for not having that
   overhead.

   empty()

      Return "True" if the queue is empty, "False" otherwise.

   full()

      Return "True" if the queue is full, "False" otherwise.

      "Queue(None)" is never full.

   get(block=True, timeout=None)

      Remove and return an item from the queue.

      If optional args *block* is true and *timeout* is "None" (the
      default), block if necessary until an item is available. If
      *timeout* is a positive number, it blocks at most *timeout*
      seconds and raises the "Empty" exception if no item was
      available within that time. Otherwise (*block* is false), return
      an item if one is immediately available, else raise the "Empty"
      exception (*timeout* is ignored in that case).

   get_nowait()

      Remove and return an item from the queue without blocking.

      Only get an item if one is immediately available. Otherwise
      raise the "Empty" exception.

   getting()

      Returns the number of greenthreads that are blocked waiting on
      an empty queue.

   put(item, block=True, timeout=None)

      Put an item into the queue.

      If optional arg *block* is true and *timeout* is "None" (the
      default), block if necessary until a free slot is available. If
      *timeout* is a positive number, it blocks at most *timeout*
      seconds and raises the "Full" exception if no free slot was
      available within that time. Otherwise (*block* is false), put an
      item on the queue if a free slot is immediately available, else
      raise the "Full" exception (*timeout* is ignored in that case).

   put_nowait(item)

      Put an item into the queue without blocking.

      Only enqueue the item if a free slot is immediately available.
      Otherwise raise the "Full" exception.

   putting()

      Returns the number of greenthreads that are blocked waiting to
      put items into the queue.

   qsize()

      Return the size of the queue.

   resize(size)

      Resizes the queue's maximum size.

      If the size is increased, and there are putters waiting, they
      may be woken up.

class eventlet.queue.PriorityQueue(maxsize=None)

   A subclass of "Queue" that retrieves entries in priority order
   (lowest first).

   Entries are typically tuples of the form: "(priority number,
   data)".

class eventlet.queue.Queue(maxsize=None)

   Create a queue object with a given maximum size.

   If *maxsize* is less than zero or "None", the queue size is
   infinite.

   "Queue(0)" is a channel, that is, its "put()" method always blocks
   until the item is delivered. (This is unlike the standard
   "Stdlib_Queue", where 0 means infinite size).

   In all other respects, this Queue class resembles the standard
   library, "Stdlib_Queue".

   join()

      Block until all items in the queue have been gotten and
      processed.

      The count of unfinished tasks goes up whenever an item is added
      to the queue. The count goes down whenever a consumer thread
      calls "task_done()" to indicate that the item was retrieved and
      all work on it is complete. When the count of unfinished tasks
      drops to zero, "join()" unblocks.

   task_done()

      Indicate that a formerly enqueued task is complete. Used by
      queue consumer threads. For each "get" used to fetch a task, a
      subsequent call to "task_done()" tells the queue that the
      processing on the task is complete.

      If a "join()" is currently blocking, it will resume when all
      items have been processed (meaning that a "task_done()" call was
      received for every item that had been "put" into the queue).

      Raises a "ValueError" if called more times than there were items
      placed in the queue.
