# util/queue.py# Copyright (C) 2005-2012 the SQLAlchemy authors and contributors <see AUTHORS file>## This module is part of SQLAlchemy and is released under# the MIT License: http://www.opensource.org/licenses/mit-license.php"""An adaptation of Py2.3/2.4's Queue module which supports reentrantbehavior, using RLock instead of Lock for its mutex object. TheQueue object is used exclusively by the sqlalchemy.pool.QueuePoolclass.This is to support the connection pool's usage of weakref callbacks to returnconnections to the underlying Queue, which can in extremelyrare cases be invoked within the ``get()`` method of the Queue itself,producing a ``put()`` inside the ``get()`` and therefore a reentrantcondition.An additional change includes a special "abort" method which can be usedto immediately raise a special exception for threads that are blockingon get(). This is to accommodate a rare race condition that can occurwithin QueuePool."""fromcollectionsimportdequefromtimeimporttimeas_timefromsqlalchemy.utilimportthreadingimportsysifsys.version_info<(2,6):defnotify_all(condition):condition.notify()else:defnotify_all(condition):condition.notify_all()__all__=['Empty','Full','Queue','SAAbort']classEmpty(Exception):"Exception raised by Queue.get(block=0)/get_nowait()."passclassFull(Exception):"Exception raised by Queue.put(block=0)/put_nowait()."passclassSAAbort(Exception):"Special SQLA exception to abort waiting"def__init__(self,context):self.context=contextclassQueue:def__init__(self,maxsize=0):"""Initialize a queue object with a given maximum size. If `maxsize` is <= 0, the queue size is infinite. """self._init(maxsize)# mutex must be held whenever the queue is mutating. All methods# that acquire mutex must release it before returning. mutex# is shared between the two conditions, so acquiring and# releasing the conditions also acquires and releases mutex.self.mutex=threading.RLock()# Notify not_empty whenever an item is added to the queue; a# thread waiting to get is notified then.self.not_empty=threading.Condition(self.mutex)# Notify not_full whenever an item is removed from the queue;# a thread waiting to put is notified then.self.not_full=threading.Condition(self.mutex)# when this is set, SAAbort is raised within get().self._sqla_abort_context=Falsedefqsize(self):"""Return the approximate size of the queue (not reliable!)."""self.mutex.acquire()n=self._qsize()self.mutex.release()returnndefempty(self):"""Return True if the queue is empty, False otherwise (not reliable!)."""self.mutex.acquire()n=self._empty()self.mutex.release()returnndeffull(self):"""Return True if the queue is full, False otherwise (not reliable!)."""self.mutex.acquire()n=self._full()self.mutex.release()returnndefput(self,item,block=True,timeout=None):"""Put an item into the queue. If optional args `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). """self.not_full.acquire()try:ifnotblock:ifself._full():raiseFulleliftimeoutisNone:whileself._full():self.not_full.wait()else:iftimeout<0:raiseValueError("'timeout' must be a positive number")endtime=_time()+timeoutwhileself._full():remaining=endtime-_time()ifremaining<=0.0:raiseFullself.not_full.wait(remaining)self._put(item)self.not_empty.notify()finally:self.not_full.release()defput_nowait(self,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. """returnself.put(item,False)defget(self,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). """self.not_empty.acquire()try:ifnotblock:ifself._empty():raiseEmptyeliftimeoutisNone:whileself._empty():self.not_empty.wait()ifself._sqla_abort_context:raiseSAAbort(self._sqla_abort_context)else:iftimeout<0:raiseValueError("'timeout' must be a positive number")endtime=_time()+timeoutwhileself._empty():remaining=endtime-_time()ifremaining<=0.0:raiseEmptyself.not_empty.wait(remaining)ifself._sqla_abort_context:raiseSAAbort(self._sqla_abort_context)item=self._get()self.not_full.notify()returnitemfinally:self.not_empty.release()defabort(self,context):"""Issue an 'abort', will force any thread waiting on get() to stop waiting and raise SAAbort. """self._sqla_abort_context=contextifnotself.not_full.acquire(False):returntry:notify_all(self.not_empty)finally:self.not_full.release()defget_nowait(self):"""Remove and return an item from the queue without blocking. Only get an item if one is immediately available. Otherwise raise the ``Empty`` exception. """returnself.get(False)# Override these methods to implement other queue organizations# (e.g. stack or priority queue).# These will only be called with appropriate locks held# Initialize the queue representationdef_init(self,maxsize):self.maxsize=maxsizeself.queue=deque()def_qsize(self):returnlen(self.queue)# Check whether the queue is emptydef_empty(self):returnnotself.queue# Check whether the queue is fulldef_full(self):returnself.maxsize>0andlen(self.queue)==self.maxsize# Put a new item in the queuedef_put(self,item):self.queue.append(item)# Get an item from the queuedef_get(self):returnself.queue.popleft()