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.
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.
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.
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.
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.
This method returns
Trueso it will always be included in the list of file-like objects when waiting for IO activity.
This method returns
Falsebecuase there is never any pending write activity like there would be for a actual file or socket.
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.
This method is called when a close is requested, so this in turn passes it to the asyncore.file_dispatcher.close function.
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.
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
Trueif the “event” is “set”.
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”.
Setting the event involves writing a single character to the internal pipe, but only if there is no data in the pipe.
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.