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.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(iterator, scheduler, asyncStart=True, container=None, manualStart=False, daemon=False)¶: This wraps a normal generator 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:

event: When a routine returns from yield, container.event is set to the matched event object
matcher: When a routine returns from yeild, container.event is set to the matched event matcher
timeout: waitWithTimeout, executeWithTimeout uses this attribute to indicate whether the wait process exceeds the time limit
retvalue: many coroutine methods use this attribute to return a value
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=('retvalue', ))¶

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

Parameters:	subprocess – a subroutine container – container in which to start the routine retnames – get return values from keys
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):

for m in c.delegate(c.someprocess()):
    yield m

Use delegateOther if you need to retrieve the return value.

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

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

for m in self.delegateOther(c.method(), c):
    yield m
ret = self.retvalue

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.

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

Execute all subprocesses and get the return values. Return values are in self.retvalue.

Parameters:	subprocesses – sequence of subroutines (generators) container – if specified, run subprocesses in another container. retnames – get return value from container.(name) for each name in retnames. 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 container.timeout is set to True; otherwise the container.timeout is set to False.

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

for m in container.executeWithTimeout(10, container.executeAll([routine1(), routine2()])):
    yield m

main()¶: The main routine method, should be rewritten to a generator 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 generator object i.e the return value of a generator 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 from container.retvalue

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.

Can call without delegate.

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

waitForAllEmpty(*queues)¶: Wait for multiple queues to be empty at the same time.

waitForAllToProcess(*matchers)¶: 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)¶: Send an event to the main event queue. Can call without delegate.

waitWithTimeout(timeout, *matchers)¶

Wait for multiple event matchers, or until timeout. If time limit exceeds, container.timeout is set to True; otherwise it is set to False, and event matcher attributes are set. You should check the timeout attribute before accessing event or matcher attribute.

Parameters:	timeout – a timeout value *matchers – event matchers

withCallback(subprocess, callback, *matchers)¶: 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.

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.

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='iterator', classname='routine')¶

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

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

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