greenhouse.util – Greenlet-Aware Concurrency Primitives¶
- class greenhouse.util.Event¶
Bases: object
an event for which greenlets can wait
mirrors the standard library threading.Event API
- clear()¶
clear the event from being triggered
after calling this method, waiting on this event will block until the set() method has been called
- isSet()¶
indicates whether waiting on the event will block right now
Returns: True if the event has been set() and waiting will not block, False if the event is cleared and wait() will block
- is_set()¶
indicates whether waiting on the event will block right now
Returns: True if the event has been set() and waiting will not block, False if the event is cleared and wait() will block
- set()¶
set the event to triggered
after calling this method, all greenlets waiting on the event will be rescheduled, and calling wait() will not block until clear() has been called
- wait(timeout=None)¶
pause the current coroutine until this event is set
Note
this method will block the current coroutine if set() has not been called.
Parameters: timeout (number or None) – the maximum amount of time to block in seconds. the default of None allows indefinite blocking. Returns: True if a timeout was provided and was hit, otherwise False
- class greenhouse.util.Lock¶
Bases: object
an object that can only be ‘owned’ by one greenlet at a time
mirrors the standard library threading.Lock API
- acquire(blocking=True)¶
lock the lock, blocking until it becomes available
Note
this method will block the current coroutine if the lock is not already owned.
Parameters: blocking (bool) – whether to block if the lock is already owned (default True) Returns: a bool indicating whether the lock was acquired. In the default case of blocking = True this will always be the case, but may not be otherwise.
- acquire_lock(blocking=True)¶
lock the lock, blocking until it becomes available
Note
this method will block the current coroutine if the lock is not already owned.
Parameters: blocking (bool) – whether to block if the lock is already owned (default True) Returns: a bool indicating whether the lock was acquired. In the default case of blocking = True this will always be the case, but may not be otherwise.
- locked()¶
indicates whether the lock is currently locked
Returns: True if the lock is locked (and therefore calling acquire() would block), otherwise False
- locked_lock()¶
indicates whether the lock is currently locked
Returns: True if the lock is locked (and therefore calling acquire() would block), otherwise False
- class greenhouse.util.RLock¶
Bases: greenhouse.util.Lock
a lock which may be acquired more than once by the same greenlet
mirrors the standard library threading.RLock API
- acquire(blocking=True)¶
acquire ownership of the lock
if the lock is already owned by the calling greenlet, a counter simply gets incremented. if it is owned by a different greenlet then it will block until the lock becomes available.
Note
this method will block the current coroutine if the lock is not already owned by another coroutine.
Parameters: blocking (bool) – whether to block if the lock is owned by a different greenlet (default True) Returns: a bool indicating whether the lock was acquired. In the default case of blocking = True this will always be the case, but may not be otherwise.
- class greenhouse.util.Condition(lock=None)¶
Bases: object
a synchronization object capable of waking all or one of its waiters
mirrors the standard library threading.Condition API
Parameters: lock (Lock or RLock) – the lock object wrapped by the condition - notify(num=1)¶
wake one or more waiting greenlets
Parameters: num (int) – the number of waiters to wake (default 1) Raises: RuntimeError if the underlying lock hasn’t been acquired
- notifyAll()¶
wake all waiting greenlets
Raises: RuntimeError if the underlying lock hasn’t been acquired
- class greenhouse.util.Semaphore(value=1)¶
Bases: object
a synchronization object with a counter that blocks when it reaches 0
mirrors the api of threading.Semaphore
Parameters: value (int) – the starting value of the counter - acquire(blocking=True)¶
decrement the counter, waiting if it is already at 0
Note
if the counter is already at 0, this method will block the current coroutine until a release() increments it again.
Parameters: blocking (bool) – whether or not to block if the counter is already at 0 (default True) Returns: a bool, indicating whether the count was decremented (this can only be False if blocking was False – otherwise it would have blocked until it could decrement the counter)
- release()¶
increment the counter, waking up a waiter if there was any
- class greenhouse.util.BoundedSemaphore(value=1)¶
Bases: greenhouse.util.Semaphore
a semaphore with an upper limit to the counter
mirrors the api of threading.BoundedSemaphore
Parameters: value (int) – the starting and maximum value of the counter - release()¶
increment the counter, waking up a waiter if there was any
- class greenhouse.util.Timer(interval, function, args=, []kwargs={})¶
Bases: greenhouse.util.Thread
creates a greenlet from a function and schedules it to run later
mirrors the standard library threading.Timer API
Parameters: - interval (int or float) – how far in the future to defer the function in seconds
- func (function) – the function to run later
- args (tuple) – positional arguments to pass to the function
- kwargs (dict) – keyword arguments to pass to the function
- cancel()¶
attempt to prevent the timer from ever running its function
Returns: True if it was successful, False if the timer had already run or been cancelled
- classmethod wrap(secs, args=(), kwargs=None)¶
a classmethod decorator to immediately turn a function into a timer
Note
you won’t find this on threading.Timer, it is an extension to that API
this is a function returning a decorator, so it is used like so:
>>> @Timer.wrap(5, args=("world",)) >>> def say_hi_timer(name): ... print "hello, %s" % name
Parameters: - secs (int or float) – how far in the future to defer running the function in seconds
- args (tuple) – positional arguments to pass to the function
- kwargs (dict) – keyword arguments to pass to the function
Returns: a decorator function which produces an unstarted Timer
- class greenhouse.util.Local¶
Bases: object
an object that holds greenlet-local data
mirrors the standard library threading.local API
to use, simply create an instance with no arguments, and any attribute gets and sets will be specific to that greenlet
- class greenhouse.util.Thread(group=None, target=None, name=None, args=(), kwargs=None, verbose=None)¶
Bases: object
a standin class for threads, but powered by greenlets
this class is useful for monkey-patching the standard library, but for code written explicitly for greenhouse, the functions in greenhouse.scheduler are a better way to go
mirrors the standard library threading.Thread API
Parameters: - group (None) – this argument does nothing and must be None (for compatibility with the standard library threading.Thread)
- target (function) – the function to run in the greenlet
- name (str) – the thread name (defaults to a generated name)
- args (tuple) – positional arguments to pass in to the target function
- kwargs (dict) – keyword arguments to pass to the target function
- verbose (bool) – here for compatibility, it is actually ignored
- daemon¶
whether the thread is set as a daemon thread (unsupported)
- getName()¶
the thread’s name as passed in the constructor or set_name(), or failing those the automatically generated name
Returns: the thread’s str name
- get_name()¶
the thread’s name as passed in the constructor or set_name(), or failing those the automatically generated name
Returns: the thread’s str name
- ident¶
unique identifier for this thread
- isAlive()¶
indicates whether the thread is currently running
Returns: True if start() has already been called but the function hasn’t yet finished or been killed, False if it isn’t currently running for any reason.
- isDaemon()¶
whether the thread is in daemonized mode
Returns: True. this is here for compatibility with threading.Thread, greenhouse-based threads always operate like daemonized threads.
- is_alive()¶
indicates whether the thread is currently running
Returns: True if start() has already been called but the function hasn’t yet finished or been killed, False if it isn’t currently running for any reason.
- is_daemon()¶
whether the thread is in daemonized mode
Returns: True. this is here for compatibility with threading.Thread, greenhouse-based threads always operate like daemonized threads.
- join(timeout=None)¶
block until this thread terminates
Note
this method can block the calling coroutine if the thread has not yet completed.
Parameters: timeout (int, float or None) – the maximum time to wait. with the default of None, waits indefinitely Raises: RuntimeError if called inside the thread, or it has not yet been started
- run(*args, **kwargs)¶
override this method to define the thread’s behavior
this is an alternative way to define the thread’s function than passing target to the constructor
- setDaemon(daemonic)¶
here for compatibility with threading.Thread (this doesn’t work).
Parameters: daemonic (bool) – whether attempting to turn daemon mode on or off
- setName(name)¶
overwrite the thread’s name
Parameters: name (str) – the name to set
- set_daemon(daemonic)¶
here for compatibility with threading.Thread (this doesn’t work).
Parameters: daemonic (bool) – whether attempting to turn daemon mode on or off
- set_name(name)¶
overwrite the thread’s name
Parameters: name (str) – the name to set
- start()¶
schedule to start the greenlet that runs this thread’s function
Raises: RuntimeError if the thread has already been started
- class greenhouse.util.Queue(maxsize=0)¶
Bases: object
a producer-consumer queue
Parameters: maxsize (int) – optional limit to the amount of queued data, after which put() can block. the default of 0 turns off the limit, so put() will never block mirrors the standard library Queue.Queue API
- empty()¶
indicate whether there is any queued data
Returns: True if there is data in the queue, otherwise False
- full()¶
indicate whether the queue has maxsize data queued
Returns: True if the queue’s data has reached maxsize, otherwise False
- get(block=True, timeout=None)¶
get an item out of the queue
Note
if block is True (the default) and the queue is :meth`empty`, this method will block the current coroutine until something has been put().
Parameters: - block (bool) – whether to block if there is no data yet available (default True)
- timeout (int, float or None) – the maximum time in seconds to block waiting for data. with the default of None, can wait indefinitely. this is unused if block is False.
Raises: Empty if there is no data in the queue and block is False, or timeout expires
Returns: something that was previously put() in the queue
- get_nowait()¶
get an item out of the queue without ever blocking
this call is equivalent to get(block=False)
Returns: something that was previously put() in the queue
- join(timeout=None)¶
wait for task completions
Note
if task_done() has not been called for every put() call, this method will block until it has.
the queue is still usable after a join() call. a return from join() simply indicates that the queue has no jobs currently pending.
Parameters: timeout (int, float or None) – the maximum amount of time to wait in seconds. the default of None allows indefinite waiting. Returns: True if timeout was provided and expired, otherwise False
- put(item, block=True, timeout=None)¶
put an item into the queue
Note
if the queue was created with a maxsize and it is currently full(), this method will block the calling coroutine until another coroutine get()s an item.
Parameters: - item – the object to put into the queue, can be any type
- block (bool) – whether to block if the queue is already full() (default True)
- timeout (int, float or None) – the maximum time in seconds to block waiting. with the default of None, it can wait indefinitely. this is unused if block is False.
Raises: Full if the queue is full() and block is False, or if timeout expires.
- put_nowait(item)¶
put an item into the queue without any chance of blocking
this call is equivalent to put(block=False)
;param item: the object to put into the queue, can be any type
- qsize()¶
the number of queued pieces of data
Returns: int
- task_done()¶
mark that a “job” (corresponding to a put() or put_nowait() call) is finished
the join() method won’t complete until the number of task_done() calls equals the number of put() calls
- class greenhouse.util.LifoQueue(maxsize=0)¶
Bases: greenhouse.util.Queue
a producer-consumer queue that produces items in LIFO order
Parameters: maxsize (int) – optional limit to the amount of queued data, after which put() can block. the default of 0 turns off the limit, so put() will never block mirrors the standard library Queue.LifoQueue API
- class greenhouse.util.PriorityQueue(maxsize=0)¶
Bases: greenhouse.util.Queue
a producer-consumer queue that produces items in prioritized order
Parameters: maxsize (int) – optional limit to the amount of queued data, after which put() can block. the default of 0 turns off the limit, so put() will never block mirrors the standard library Queue.PriorityQueue API
- class greenhouse.util.Counter(initial=0)¶
Bases: object
a counter object that can block
- count¶
the current integer value of the counter
- decrement()¶
decrement the counter and wake anyone waiting for the new value
- increment()¶
increment the counter, and wake anyone waiting for the new value
- wait(until=0)¶
wait until the count has reached a particular number
Note
this method can block the current greenlet
Parameters: until (int) – the number to wait for the count to get down (or up) to. default 0