5.2.10. vlcp.event.runnable¶

Note

This document is generated from the source file.

Created on 2015/6/16

author:	hubo

class vlcp.event.runnable.EventHandler(scheduler=None, daemon=False)¶

Runnable with an event handler model.

__init__(scheduler=None, daemon=False)¶: Initialize self. See help(type(self)) for accurate signature.

__iter__()¶: Keep it like a iterator. Not very useful.

__next__()¶: Python 3 next

next()¶: Keep it like a iterator. Not very useful.

registerAllHandlers(handlerDict)¶: Register self to scheduler

registerHandler(matcher, handler)¶: Register self to scheduler

send(etup)¶: Handle events

exception vlcp.event.runnable.GeneratorExit_¶: Bypass PyPy3 bug

exception vlcp.event.runnable.IllegalMatchersException¶

exception vlcp.event.runnable.MultipleException(exceptions)¶

Special exception type raised from :py:method::vlcp.event.runnable.RoutineContainer.executeAll

__init__(exceptions)¶: Initialize self. See help(type(self)) for accurate signature.

vlcp.event.runnable.Routine(coroutine, scheduler, asyncStart=True, container=None, manualStart=False, daemon=False)¶: This wraps a normal coroutine to become a VLCP routine. Usually you do not need to call this yourself; container.start and container.subroutine calls this automatically.

class vlcp.event.runnable.RoutineContainer(scheduler=None, daemon=False)¶

A routine container groups several routines together and shares data among them. It is also used to pass important information like events, matchers and return values to the routine.

Several attributes are commonly used:

currentroutine: Always set to the executing routine - which is the wrapped routine object of the routine itself
mainroutine: Set to the main routine container.main (started by container.start)

__init__(scheduler=None, daemon=False)¶

Create the routine container.

Parameters:	scheduler – The scheduler. This must be set; if None is used, it must be set with container.bind(scheduler) before using. daemon – If daemon = True, the main routine container.main is set to be a daemon routine. A daemon routine does not stop the scheduler from quitting; if all non-daemon routines are quit, the scheduler stops.

beginDelegateOther(subprocess, container, retnames=('', ))¶

DEPRECATED Start the delegate routine, but do not wait for result, instead returns a (matcher routine) tuple. Useful for advanced delegates (e.g. delegate multiple subprocesses in the same time). This is NOT a coroutine method.

Parameters:	subprocess – a coroutine container – container in which to start the routine retnames – get return values from keys. ‘’ for the return value (for compatibility with earlier versions)
Returns:	(matcher, routine) where matcher is a event matcher to get the delegate result, routine is the created routine

begin_delegate(subprocess)¶

Start the delegate routine, but do not wait for result, instead returns a (matcher, routine) tuple. Useful for advanced delegates (e.g. delegate multiple subprocesses in the same time). This is NOT a coroutine method.

WARNING: this is not a safe way for asynchronous executing and get the result. Use RoutineFuture instead.

Parameters:	subprocess – a coroutine
Returns:	(matcher, routine) where matcher is a event matcher to get the delegate result, routine is the created routine

begin_delegate_other(subprocess, container, retnames=('', ))¶

DEPRECATED Start the delegate routine, but do not wait for result, instead returns a (matcher routine) tuple. Useful for advanced delegates (e.g. delegate multiple subprocesses in the same time). This is NOT a coroutine method.

Parameters:	subprocess – a coroutine container – container in which to start the routine retnames – get return values from keys. ‘’ for the return value (for compatibility with earlier versions)
Returns:	(matcher, routine) where matcher is a event matcher to get the delegate result, routine is the created routine

bind(scheduler)¶: If scheduler is not specified, bind the scheduler

close()¶: Same as terminate()

delegate(subprocess, forceclose=False)¶

Run a subprocess without container support

Many subprocess assume itself running in a specified container, it uses container reference like self.events. Calling the subprocess in other containers will fail.

With delegate, you can call a subprocess in any container (or without a container):

r = await c.delegate(c.someprocess())

Returns:	original return value

delegateOther(subprocess, container, retnames=('', ), forceclose=False)¶

DEPRECATED Another format of delegate allows delegate a subprocess in another container, and get some returning values the subprocess is actually running in ‘container’.

ret = await self.delegate_other(c.method(), c)

Returns:	a tuple for retnames values

delegate_other(subprocess, container, retnames=('', ), forceclose=False)¶

DEPRECATED Another format of delegate allows delegate a subprocess in another container, and get some returning values the subprocess is actually running in ‘container’.

ret = await self.delegate_other(c.method(), c)

Returns:	a tuple for retnames values

classmethod destroy_container_cache(scheduler)¶: Remove cached container

doEvents()¶: Suspend this routine until the next polling. This can be used to give CPU time for other routines and socket processings in long calculating procedures. Can call without delegate.

do_events()¶: Suspend this routine until the next polling. This can be used to give CPU time for other routines and socket processings in long calculating procedures. Can call without delegate.

end_delegate(delegate_matcher, routine=None, forceclose=False)¶

Retrieve a begin_delegate result. Must be called immediately after begin_delegate before any other await, or the result might be lost.

Do not use this method without thinking. Always use RoutineFuture when possible.

executeAll(subprocesses, container=None, retnames=('', ), forceclose=True)¶

DEPRECATED Execute all subprocesses and get the return values.

Parameters:

subprocesses – sequence of subroutines (coroutines)
container – if specified, run subprocesses in another container.
retnames – DEPRECATED get return value from container.(name) for each name in retnames. ‘’ for return value (to be compatible with earlier versions)
forceclose – force close the routines on exit, so all the subprocesses are terminated on timeout if used with executeWithTimeout

Returns:

a list of tuples, one for each subprocess, with value of retnames inside: [(‘retvalue1’,),(‘retvalue2’,),…]

executeWithTimeout(timeout, subprocess)¶

Execute a subprocess with timeout. If time limit exceeds, the subprocess is terminated, and is_timeout is set to True; otherwise the is_timeout is set to False.

You can uses execute_with_timeout with other help functions to create time limit for them:

timeout, result = await container.execute_with_timeout(10, container.execute_all([routine1(), routine2()]))

Returns:	(is_timeout, result) When is_timeout = True, result = None

execute_all(subprocesses, forceclose=True)¶

Execute all subprocesses and get the return values.

Parameters:	subprocesses – sequence of subroutines (coroutines) forceclose – force close the routines on exit, so all the subprocesses are terminated on timeout if used with executeWithTimeout
Returns:	a list of return values for each subprocess

execute_all_with_names(subprocesses, container=None, retnames=('', ), forceclose=True)¶

DEPRECATED Execute all subprocesses and get the return values.

Parameters:

subprocesses – sequence of subroutines (coroutines)
container – if specified, run subprocesses in another container.
retnames – DEPRECATED get return value from container.(name) for each name in retnames. ‘’ for return value (to be compatible with earlier versions)
forceclose – force close the routines on exit, so all the subprocesses are terminated on timeout if used with executeWithTimeout

Returns:

a list of tuples, one for each subprocess, with value of retnames inside: [(‘retvalue1’,),(‘retvalue2’,),…]

execute_with_timeout(timeout, subprocess)¶

Execute a subprocess with timeout. If time limit exceeds, the subprocess is terminated, and is_timeout is set to True; otherwise the is_timeout is set to False.

You can uses execute_with_timeout with other help functions to create time limit for them:

timeout, result = await container.execute_with_timeout(10, container.execute_all([routine1(), routine2()]))

Returns:	(is_timeout, result) When is_timeout = True, result = None

classmethod get_container(scheduler)¶: Create temporary instance for helper functions

main()¶: The main routine method, should be rewritten to an async method

start(asyncStart=False)¶

Start container.main as the main routine.

Parameters:	asyncStart – if True, start the routine in background. By default, the routine starts in foreground, which means it is executed to the first yield statement before returning. If the started routine raises an exception, the exception is re-raised to the caller of start

subroutine(iterator, asyncStart=True, name=None, daemon=False)¶

Start extra routines in this container.

Parameters:

iterator – A coroutine object i.e the return value of an async method my_routine()
asyncStart – if False, start the routine in foreground. By default, the routine starts in background, which means it is not executed until the current caller reaches the next yield statement or quit.
name – if not None, container.<name> is set to the routine object. This is useful when you want to terminate the routine from outside.
daemon – if True, this routine is set to be a daemon routine. A daemon routine does not stop the scheduler from quitting; if all non-daemon routines are quit, the scheduler stops.

syscall(func, ignoreException=False)¶: Call a syscall method and retrieve its return value

syscall_noreturn(func)¶: Call a syscall method. A syscall method is executed outside of any routines, directly in the scheduler loop, which gives it chances to directly operate the event loop. See :py:method::vlcp.event.core.Scheduler.syscall.

terminate(routine=None)¶

Stop a routine.

Parameters:	routine – if None, stop the main routine. If not None, it should be a routine object. You can specify a name for a subroutine, and use container.<name> to retrieve it.

waitForAll(*matchers, eventlist=None, eventdict=None, callback=None)¶

Wait until each matcher matches an event. When this coroutine method returns, eventlist is set to the list of events in the arriving order (may not be the same as the matchers); eventdict is set to a dictionary {matcher1: event1, matcher2: event2, …}

Parameters:	eventlist – use external event list, so when an exception occurs (e.g. routine close), you can retrieve the result from the passed-in list eventdict – use external event dict callback – if not None, the callback should be a callable callback(event, matcher) which is called each time an event is received
Returns:	(eventlist, eventdict)

waitForAllEmpty(*queues)¶

Wait for multiple queues to be empty at the same time.

Require delegate when calling from coroutines running in other containers

waitForAllToProcess(*matchers, eventlist=None, eventdict=None, callback=None)¶: Similar to waitForAll, but set canignore=True for these events. This ensures blocking events are processed correctly.

waitForEmpty(queue)¶: Wait for a queue to be empty. Can call without delegate

waitForSend(event, *, until=None)¶

Send an event to the main event queue. Can call without delegate.

Parameters:	until – if the callback returns True, stop sending and return
Returns:	the last True value the callback returns, or None

waitWithTimeout(timeout, *matchers)¶

Wait for multiple event matchers, or until timeout.

Parameters:	timeout – a timeout value *matchers – event matchers
Returns:	(is_timeout, event, matcher). When is_timeout = True, event = matcher = None.

wait_for_all(*matchers, eventlist=None, eventdict=None, callback=None)¶

Wait until each matcher matches an event. When this coroutine method returns, eventlist is set to the list of events in the arriving order (may not be the same as the matchers); eventdict is set to a dictionary {matcher1: event1, matcher2: event2, …}

Parameters:	eventlist – use external event list, so when an exception occurs (e.g. routine close), you can retrieve the result from the passed-in list eventdict – use external event dict callback – if not None, the callback should be a callable callback(event, matcher) which is called each time an event is received
Returns:	(eventlist, eventdict)

wait_for_all_empty(*queues)¶

Wait for multiple queues to be empty at the same time.

Require delegate when calling from coroutines running in other containers

wait_for_all_to_process(*matchers, eventlist=None, eventdict=None, callback=None)¶: Similar to waitForAll, but set canignore=True for these events. This ensures blocking events are processed correctly.

wait_for_empty(queue)¶: Wait for a queue to be empty. Can call without delegate

wait_for_send(event, *, until=None)¶

Send an event to the main event queue. Can call without delegate.

Parameters:	until – if the callback returns True, stop sending and return
Returns:	the last True value the callback returns, or None

wait_with_timeout(timeout, *matchers)¶

Wait for multiple event matchers, or until timeout.

Parameters:	timeout – a timeout value *matchers – event matchers
Returns:	(is_timeout, event, matcher). When is_timeout = True, event = matcher = None.

withCallback(subprocess, callback, *matchers, intercept_callback=None)¶

Monitoring event matchers while executing a subprocess. callback(event, matcher) is called each time an event is matched by any event matchers. If the callback raises an exception, the subprocess is terminated.

Parameters:	intercept_callback – a callback called before a event is delegated to the inner subprocess

withException(subprocess, *matchers)¶: Monitoring event matchers while executing a subprocess. If events are matched before the subprocess ends, the subprocess is terminated and a RoutineException is raised.

with_callback(subprocess, callback, *matchers, intercept_callback=None)¶

Monitoring event matchers while executing a subprocess. callback(event, matcher) is called each time an event is matched by any event matchers. If the callback raises an exception, the subprocess is terminated.

Parameters:	intercept_callback – a callback called before a event is delegated to the inner subprocess

with_exception(subprocess, *matchers)¶: Monitoring event matchers while executing a subprocess. If events are matched before the subprocess ends, the subprocess is terminated and a RoutineException is raised.

class vlcp.event.runnable.RoutineControlEvent(*args, **kwargs)¶

exception vlcp.event.runnable.RoutineException(matcher, event)¶

Special exception type raised from :py:method::vlcp.event.runnable.RoutineContainer.withException. e.matcher is set to the matcher and e.event is set to the matched event.

__init__(matcher, event)¶: Initialize self. See help(type(self)) for accurate signature.

class vlcp.event.runnable.generatorwrapper(run, name='coroutine', classname='routine')¶

Default __repr__ of a generator is not readable, use a wrapper to improve the readability

__init__(run, name='coroutine', classname='routine')¶: Initialize self. See help(type(self)) for accurate signature.

__repr__(*args, **kwargs)¶: Return repr(self).