Event

At the heart of core.run() is a call to the select function of the built in select module. That function is provided a list of file descriptors and will exit when there is activity on one of them.

In a multi-threaded application, if the main thread is waiting for IO activity then child threads need a mechanism to “wake up” the main thread. This may be because the child thread has detected some timeout.

An instance of this class is used by the task.TaskManager to wake up the main thread when tasks are scheduled by child threads. If the child thread is requesting “as soon as possible” execution of the task, then scheduling the task wakes up the main thread, which causes it to be processed.

Note

This is not available on Windows platforms, which may suffer from a small preformance hit. This can be mitigated somewhat by changing the SPIN value in the core module.

Classes

class event.WaitableEvent

The methods in this class provide the same interface as asyncore.file_dispatcher and the ones that are typically used in multi-threaded applications the way Threading.Event objects are used.

These methods use an internal pipe to provide a “read” and “write” file descriptors. There are no direct references to this pipe, only through the file descriptors that are linked to it.

__init__()

The internal file descriptors which are understood by the asyncore.loop call in core.run() are created by calling os.pipe(), then initialization continues to the usual asyncore.file_dispatcher initializer.

__del__()

When an instance of this class is deleted, the file references to the “read” and “write” sides of the pipe are closed. The OS will then delete the pipe.

readable()

This method returns True so it will always be included in the list of file-like objects when waiting for IO activity.

writable()

This method returns False becuase there is never any pending write activity like there would be for a actual file or socket.

handle_read()

This method performs no activity. If an instance of this event is “set” then the only way to clear it is by calling clear() which will read the pending character out of the pipe.

handle_write()

This function is never called because writable() always returns False.

handle_close()

This method is called when a close is requested, so this in turn passes it to the asyncore.file_dispatcher.close function.

wait(timeout=None)

Parameters:timeout (float) – maximum time to wait for the event to be set

Similar to the way the asyncore.loop function will wait for activity on a file descriptor, select.select is used by this method to wait for some activity on the “read” side of its internal pipe.

The set() function will write to the “write” side of the pipe, so the “read” side will have activity and the select function will exit.

This function returns True if the “event” is “set”.

isSet()

This method calls wait() with a zero timeout which essentially probes the pipe to see if there is data waiting, which in turn implies the “event” is “set”.

set()

Setting the event involves writing a single character to the internal pipe, but only if there is no data in the pipe.

clear()

Clearing the event involves reading the character that was written to the intrenal pipe, provided one is there. If there is no data in the pipe then the os.read function would stall the thread.