greenhouse.scheduler – Interacting With The Greenhouse Scheduler¶

greenhouse.scheduler.pause()¶

pause and reschedule the current greenlet and switch to the next

Note

this method blocks for a short period of time

greenhouse.scheduler.pause_until(unixtime)¶

pause and reschedule the current greenlet until a set time

Note

this method will block the current greenlet

Parameters:	unixtime (int or float) – the unix timestamp of when to bring this greenlet back

greenhouse.scheduler.pause_for(secs)¶

pause and reschedule the current greenlet for a set number of seconds

Note

this method will block the current greenlet

Parameters:	secs (int or float) – number of seconds to pause

greenhouse.scheduler.schedule(target=None, args=(), kwargs=None)¶

insert a greenlet into the scheduler

If provided a function, it is wrapped in a new greenlet

Parameters:	target (function or greenlet) – what to schedule args (tuple) – arguments for the function (only used if target is a function) kwargs (dict or None) – keyword arguments for the function (only used if target is a function)
Returns:	the target argument

This function can also be used as a decorator, either preloading args and/or kwargs or not:

>>> @schedule
>>> def f():
...     print 'hello from f'

>>> @schedule(args=('world',))
>>> def f(name):
...     print 'hello %s' % name

greenhouse.scheduler.schedule_at(unixtime, target=None, args=(), kwargs=None)¶

insert a greenlet into the scheduler to be run at a set time

If provided a function, it is wrapped in a new greenlet

Parameters:	unixtime (int or float) – the unix timestamp at which the new greenlet should be started target (function or greenlet) – what to schedule args (tuple) – arguments for the function (only used if target is a function) kwargs (dict or None) – keyword arguments for the function (only used if target is a function)
Returns:	the target argument

This function can also be used as a decorator:

>>> @schedule_at(1296423834)
>>> def f():
...     print 'hello from f'

and args/kwargs can also be preloaded:

>>> @schedule_at(1296423834, args=('world',))
>>> def f(name):
...     print 'hello %s' % name

greenhouse.scheduler.schedule_in(secs, target=None, args=(), kwargs=None)¶

insert a greenlet into the scheduler to run after a set time

If provided a function, it is wrapped in a new greenlet

Parameters:	secs – the number of seconds to wait before running the target target (function or greenlet) – what to schedule args (tuple) – arguments for the function (only used if target is a function) kwargs (dict or None) – keyword arguments for the function (only used if target is a function)
Returns:	the target argument

This function can also be used as a decorator:

>>> @schedule_in(30)
>>> def f():
...     print 'hello from f'

and args/kwargs can also be preloaded:

>>> @schedule_in(30, args=('world',))
>>> def f(name):
...     print 'hello %s' % name

greenhouse.scheduler.schedule_recurring(interval, target=None, maxtimes=0, starting_at=0, args=(), kwargs=None)¶

insert a greenlet into the scheduler to run regularly at an interval

If provided a function, it is wrapped in a new greenlet

Parameters:

interval (int or float) – the number of seconds between invocations target (function or greenlet) – what to schedule maxtimes (int) – if provided, do not run more than maxtimes iterations starting_at (int or float) – the unix timestamp of when to schedule it for the first time (defaults to the time of the schedule_recurring call) args (tuple) – arguments for the function kwargs (dict or None) – keyword arguments for the function

Returns:

the target argument

This function can also be used as a decorator:

>>> @schedule_recurring(30)
>>> def f():
...     print "the regular 'hello' from f"

and args/kwargs can also be preloaded:

>>> @schedule_recurring(30, args=('world',))
>>> def f(name):
...     print 'the regular hello %s' % name

greenhouse.scheduler.schedule_exception(exception, target)¶

schedule a greenlet to have an exception raised in it immediately

Parameters:	exception (Exception) – the exception to raise in the greenlet target (greenlet) – the greenlet that should receive the exception

greenhouse.scheduler.schedule_exception_at(unixtime, exception, target)¶

schedule a greenlet to have an exception raised at a unix timestamp

Parameters:	unixtime (int or float) – when to raise the exception in the target exception (Exception) – the exception to raise in the greenlet target (greenlet) – the greenlet that should receive the exception

greenhouse.scheduler.schedule_exception_in(secs, exception, target)¶

schedule a greenlet receive an exception after a number of seconds

Parameters:	secs (int or float) – the number of seconds to wait before raising exception (Exception) – the exception to raise in the greenlet target (greenlet) – the greenlet that should receive the exception

greenhouse.scheduler.end(target)¶

schedule a greenlet to be stopped immediately

Parameters:	target (greenlet) – the greenlet to end

greenhouse.scheduler.global_exception_handler(handler)¶

add a callback for when an exception goes uncaught in any greenlet

Parameters:	handler (function) – the callback function. must be a function taking 3 arguments: klass the exception class exc the exception instance tb the traceback object

Note also that the callback is only held by a weakref, so if all other refs to the function are lost it will stop handling greenlets’ exceptions

greenhouse.scheduler.remove_global_exception_handler(handler)¶

remove a callback from the list of global exception handlers

Parameters:	handler (function) – the callback, previously added via global_exception_handler(), to remove
Returns:	bool, whether the handler was found (and therefore removed)

greenhouse.scheduler.local_exception_handler(handler=None, coro=None)¶

add a callback for when an exception occurs in a particular greenlet

Parameters:	handler (function) – the callback function, must be a function taking 3 arguments: klass the exception class exc the exception instance tb the traceback object coro (greenlet) – the coroutine for which to apply the exception handler (defaults to the current coroutine)

greenhouse.scheduler.remove_local_exception_handler(handler, coro=None)¶

remove a callback from the list of exception handlers for a coroutine

Parameters:	handler (function) – the callback to remove coro (greenlet) – the coroutine for which to remove the local handler
Returns:	bool, whether the handler was found (and therefore removed)

greenhouse.scheduler.handle_exception(klass, exc, tb, coro=None)¶

run all the registered exception handlers

the first 3 arguments to this function match the output of sys.exc_info()

Parameters:	klass (type) – the exception klass exc (Exception) – the exception instance tb (Traceback) – the traceback object coro (greenlet) – behave as though the exception occurred in this coroutine (defaults to the current coroutine)

exception handlers run would be all those added with global_exception_handler(), and any added for the relevant coroutine with local_exception_handler().

greenhouse.scheduler.greenlet(func, args=(), kwargs=None)¶

create a new greenlet from a function and arguments

Parameters:	func (function) – the function the new greenlet should run args (tuple) – any positional arguments for the function kwargs (dict or None) – any keyword arguments for the function

the only major difference between this function and that of the basic greenlet api is that this one sets the new greenlet’s parent to be the greenhouse main loop greenlet, which is a requirement for greenlets that will wind up in the greenhouse scheduler.

greenhouse.scheduler.global_hook(handler)¶

add a callback to run in every switch between coroutines

Parameters:	handler (function) – the callback function, must be a function taking 2 arguments: the greenlet being switched from the greenlet being switched to be aware that only a weak reference to this function will be held.

greenhouse.scheduler.remove_global_hook(handler)¶

remove a callback from the list of global hooks

Parameters:	handler (function) – the callback function, previously added with global_hook, to remove from the list of global hooks
Returns:	bool, whether the handler was removed from the global hooks

greenhouse.scheduler.local_incoming_hook(handler=None, coro=None)¶

add a callback to run every time a greenlet is about to be switched to

Parameters:

handler (function) – the callback function, must be a function taking 2 arguments: an integer indicating whether it is being called as an incoming (1) hook or an outgoing (2) hook (in this case it will always receive 1). the coroutine being switched into (in this case it will always be the same as the one indicated by the coro argument to local_incoming_hook. Be aware that only a weak reference to this function will be held. coro (greenlet) – the coroutine for which to apply the trace hook (defaults to current)

greenhouse.scheduler.remove_local_incoming_hook(handler, coro=None)¶

remove a callback from the incoming hooks for a particular coro

Parameters:	handler (function) – the callback previously added via local_incoming_hook coro (greenlet) – the coroutine for which the hook should be removed
Returns:	bool, whether the handler was found and removed

greenhouse.scheduler.local_outgoing_hook(handler=None, coro=None)¶

add a callback to run every time a greenlet is switched away from

Parameters:

handler (function) – the callback function, must be a function taking 2 arguments: an integer indicating whether it is being called as an incoming (1) hook or as an outgoing (2) hook (in this case it will always be 2). the coroutine being switched from (in this case it is the one indicated by the coro argument to local_outgoing_hook. Be aware that only a weak reference to this function will be held. coro (greenlet) – the coroutine for which to apply the trace hook (defaults to current)

greenhouse.scheduler.remove_local_outgoing_hook(handler, coro=None)¶

remove a callback from the outgoing hooks for a particular coro

Parameters:	handler (function) – the callback previously added via local_outgoing_hook coro (greenlet) – the coroutine for which the hook should be removed
Returns:	bool, whether the handler was found and removed

greenhouse.scheduler.set_ignore_interrupts(flag=True)¶

turn off EINTR-raising from emulated syscalls on interruption by signals

due to the nature of greenhouse’s system call emulation, signal.siginterrupt can’t be made to work with it. specifically, greenhouse can’t differentiate between different signals. so this function toggles whether to restart for ALL or NO signals.

Parameters:	flag (bool) – whether to turn EINTR exceptions off (True) or on (False)

greenhouse.scheduler.reset_poller(poll=None)¶

replace the scheduler’s poller, throwing away any pre-existing state

this is only really a good idea in the new child process after a fork(2).