Watcher is the base class for all watchers. Though it is not exposed to users, its methods and attributes are described here.
See also
Starts (activates) the watcher. Only active watchers will receive events. If the watcher is already active nothing will happen.
Stops the watcher if active, and clears the pending status (whether the watcher was active or not).
It is possible that stopped watchers are pending - for example, non-repeating timers are being stopped when they become pending - but stop() ensures that the watcher is neither active nor pending.
| Parameters: | revents (int) – See Watcher received events for valid values. |
|---|
Invoke the watcher callback with the given revents.
If the watcher is pending, this method clears its pending status and returns its revents bitset (as if its callback was invoked). If the watcher isn’t pending it does nothing and returns 0.
Sometimes it can be useful to ‘poll’ a watcher instead of waiting for its callback to be invoked, which can be accomplished with this function.
| Parameters: | revents (int) – See Watcher received events for valid values. |
|---|
Feeds the given revents set into the event loop, as if the specified event had happened for the watcher.
Read only
True if the watcher is active (i.e. it has been started and not yet been stopped), False otherwise.
As long as a watcher is active you must not modify it.
Read only
True if the watcher is pending, (i.e. it has outstanding events but its callback has not yet been invoked), False otherwise.
As long as a watcher is pending (but not active) you must not change its priority.
The current watcher callback, its signature must be:
| Parameters: |
|
|---|
As a rule you should not let the callback return with unhandled exceptions. The loop ‘does not know’ what to do with an exception happening in your callback (it depends largely on what you are doing), so, by default, it will just print a warning and suppress it. This behaviour can be changed by setting Loop.debug to True, in which case pyev will stop the loop on all errors. If you want to act on an exception, you’re better off doing it in the callback (where you are allowed to do anything needed, like logging, stopping/restarting the loop, etc.). Example:
def mycallback(watcher, revents):
try:
pass #do something interesting
except Exception:
logging.exception("FATAL!") #this will also log the traceback
watcher.stop() #stop the watcher
watcher.loop.stop() #stop the loop
If you have a lot of callbacks, use decorators:
def mydecorator(func):
def wrap(watcher, revents):
try:
func(watcher, revents)
except RuntimeError: #these are not fatal
logging.exception("stopping {0}".format(watcher))
watcher.stop() #stop the watcher but let the loop continue its merry way
except Exception: #all other exceptions are fatal
logging.exception("FATAL: stopping {0} and {1}".format(watcher, watcher.loop))
watcher.stop() #stop the watcher
watcher.loop.stop() #stop the loop
return wrap
@mydecorator
def mycallback(watcher, revents):
pass #do something interesting
watcher data.
Set and query the priority of the watcher. The priority is a small integer between EV_MAXPRI and EV_MINPRI. Pending watchers with higher priority will be invoked before watchers with lower priority, but priority will not keep watchers from being executed (except for Idle watchers). If you need to suppress invocation when higher priority events are pending you need to look at Idle watchers, which provide this functionality.
Setting a priority outside the range of EV_MINPRI to EV_MAXPRI is fine, as long as you do not mind that the priority value you query might or might not have been clamped to the valid range (see also Watcher priorities).
The default priority used by watchers when no priority has been set is always 0.
You must not change the priority of a watcher as long as it is active or pending.
See also
All Prepare watchers are invoked just before Loop.start() starts to gather new events, and all Check watchers are invoked just after Loop.start() has gathered them, but before it invokes any callbacks for any received events. Callbacks of both watcher types can start and stop as many watchers as they want, and all of them will be taken into account (for example, a Prepare watcher might start an Idle watcher to keep Loop.start() from blocking).
Not ever sent (or otherwise used) by libev itself, but can be freely used by users to signal watchers (e.g. via Watcher.feed()).
An unspecified error has occurred, the watcher has been stopped. This might happen because the watcher could not be properly started because libev ran out of memory, a file descriptor was found to be closed or any other problem. libev considers these application bugs.
Warning
pyev handle this event as a fatal error. On receiving this event pyev will stop the loop (and the watcher). The callback will not be invoked. In practice users should never receive this event (still present for testing purposes).
Unfortunately the range of valid priorities is defined at compile time. If you really need to change it you can still define new values in setup.py and rebuild pyev, example:
setup(
...,
ext_modules=[
Extension("pyev",
["src/pyev.c"],
define_macros=[
# uncomment the following
# to modify priorities
("EV_MINPRI", "-5"),
("EV_MAXPRI", "5"),
]
),
],
...
)
default: -2.
default: 2.