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

release()¶

open the lock back up to wake up a waiting greenlet

Raises :	RuntimeError if the calling greenlet is not the one that had acquired the lock

release_lock()¶

open the lock back up to wake up a waiting greenlet

Raises :	RuntimeError if the calling greenlet is not the one that had acquired the lock

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.

release()¶

release one ownership of the lock

if the calling greenlet has acquired the lock more than once this will simply decrement the counter. if this is a final release then a waiting greenlet is awoken

Raises :	RuntimeError if the calling greenlet is not the lock’s owner

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

notify_all()¶

wake all waiting greenlets

Raises :	RuntimeError if the underlying lock hasn’t been acquired

wait(timeout=None)¶

wait to be woken up by the condition

Note

this method will block the current coroutine until a notify() wakes it back up.

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