Section 14.3. The Queue Module


14.3. The Queue Module

The Queue module supplies first-in, first-out (FIFO) queues that support multithread access, with one main class and two exception classes.

Queue

class Queue(maxsize=0)

Queue is the main class for module Queue and is covered in "Methods of Queue Instances" on page 343. When maxsize is greater than 0, the new Queue instance q is deemed full when q has maxsize items. A thread inserting an item with the block option, when q is full, suspends until another thread extracts an item. When maxsize is less than or equal to 0, q is never considered full and is limited in size only by available memory, like normal Python containers.

Empty

Empty is the class of the exception that q.get(False) raises when q is empty.

Full

Full is the class of the exception that q.put(x,False) raises when q is full.


14.3.1. Methods of Queue Instances

An instance q of class Queue supplies the following methods.

empty

q.empty( )

Returns TRue if q is empty; otherwise, False.

full

q.full( )

Returns TRue if q is full; otherwise, False.

get, get_nowait

q.get(block=true,timeout=None)

When block is False, get removes and returns an item from q if one is available; otherwise, get raises Empty. When block is true and timeout is None, get removes and returns an item from q, suspending the calling thread, if need be, until an item is available. When block is TRue and timeout is not None, timeout must be a number >=0 (which may include a fractional part to specify a fraction of a second), and get waits for no longer than timeout seconds (if no item is yet available by then, get raises Empty). q.get_nowait( ) is like q.get(False), which is also like q.get(timeout=0.0). get removes and returns items in the same order as put inserted them (FIFO).

put, put_nowait

q.put(item,block=true,timeout=None)

When block is False, put adds item to q if q is not full; otherwise, put raises Full. When block is TRue and timeout is None, put adds item to q, suspending the calling thread, if need be, until q is not full. When block is TRue and timeout is not None, timeout must be a number >=0 (which may include a fractional part to specify a fraction of a second), and put waits for no longer than timeout seconds (if q is still full by then, put raises Full). q.put_nowait(item) is like q.put(item,False), which is also like q.put(item,timeout=0.0).

qsize

q.qsize( )

Returns the number of items that are currently in q.


Queue offers a good example of the idiom "It's easier to ask forgiveness than permission" (EAFP), covered in "Error-Checking Strategies" on page 134. Due to multithreading, each nonmutating method of q can only be advisory. When some other thread executes and mutates q, things can change between the instant a thread gets the information and the very next moment, when the thread acts on the information. Relying on the "look before you leap" (LBYL) idiom is futile, and fiddling with locks to try and fix things is a substantial waste of effort. Just avoid LBYL code such as:

 if q.empty( ): print "no work to perform" else: x=q.get_nowait( ) 

and instead use the simpler and more robust EAFP approach:

 try: x=q.get_nowait( ) except Queue.Empty: print "no work to perform" 

14.3.2. Customizing Class Queue by Subclassing

If you require the intrinsically thread-safe behavior of class Queue.Queue but do not want a FIFO queuing discipline, you may customize Queue.Queue by subclassing, and you need to override some or all of the hook methods that Queue.Queue provides for the purpose: _qsize, _empty, _full, _put, and _get. Each has semantics that correspond to the public method with the corresponding name, but they're simpler, with no worries about threading, timeouts, or error checking. The only one of them that takes an argument (besides the usual self) is _put (which takes as its argument the item to put on the queue).

Queue.Queue ensures that hook methods will get called only in a state already made properly thread-safe (i.e., Queue.Queue's own methods ensure all the needed locking) and that hook methods need not worry about error-checking (for example, _get is called only when the queue is nonemptyi.e., when _empty has just returned a false result). For example, all it takes to make a thread-safe queue class with a LIFO queuing discipline is:

 import Queue class LIFOQueue(Queue.Queue):     def _get(self): return self.queue.pop( ) 

which exploits the self.queue attribute, which Queue.Queue instances already have (an instance of type collections.deque, covered in "The collections Module" on page 173).




Python in a Nutshell
Python in a Nutshell, Second Edition (In a Nutshell)
ISBN: 0596100469
EAN: 2147483647
Year: 2004
Pages: 192
Authors: Alex Martelli

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net