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)
- handler (function) –
- 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)
- handler (function) –
- 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)
- handler (function) –
- 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).