Poll – poll handle

class uv.Poll(fd, loop=None, on_event=None)[source]

Poll handles are used to watch file descriptors for readability and writability. The purpose of poll handles is to enable integrating external libraries that rely on the event loop to signal them about the socket status changes. Using them for any other purpose is not recommended. Use uv.TCP, uv.UDP, etc. instead, which provide faster and more scalable implementations, than what can be archived with uv.Poll, especially on Windows.

It is possible that poll handles occasionally signal that a file descriptor is readable or writable even when it is not. The user should therefore always be prepared to handle EAGAIN or equivalent when it attempts to read from or write to the fd.

It is not okay to have multiple active poll handles for the same socket, this can cause libuv to busyloop or otherwise malfunction.

Do not close a file descriptor while it is being polled by an active poll handle. This can cause the handle to report an error, but it might also start polling another socket. However the fd can be safely closed immediately after uv.Poll.stop() or uv.Handle.close() has been called.


On Windows only sockets can be polled with uv.Poll handles. On Unix any file descriptor that would be accepted by poll(2) can be used.


uv.UVError – error while initializing the handle

  • fd (int) – file descriptor to be polled (is set to non-blocking mode)
  • loop (uv.Loop) – event loop the handle should run on
  • on_event (Callable[[uv.Poll, uv.StatusCode, int], None]) – callback which should be called on IO events after the handle has been started

File descriptor the handle polls on.


Callback which should be called on IO events after the handle has been started.

on_event(poll_handle, status, events)
  • poll_handle (uv.Poll) – handle the call originates from
  • status (uv.StatusCode) – may indicate any errors
  • events (int) – bitmask of the triggered IO events
Type:Callable[[uv.Poll, uv.StatusCode, int], None]

Number of the file descriptor polled on.

Return type:int
start(events=<PollEvent.READABLE: 1>, on_event=None)[source]

Start polling the file descriptor for the given events. As soon as an event is detected the callback will be called with status code class:uv.StatusCode.SUCCESS and the triggered events.

If an error happens while polling the callback gets called with status code != 0 which corresponds to a uv.StatusCode.

Calling this on a handle that is already active is fine. Doing so will update the events mask that is being polled for.

  • uv.UVError – error while starting the handle
  • uv.ClosedHandleError – handle has already been closed or is closing
  • events (int) – bitmask of events to be polled for
  • on_event (Callable[[uv.Poll, uv.StatusCode, int], None]) – callback which should be called on IO events (overrides the current callback if specified)

Stop the handle. The callback will no longer be called.

:raises uv.UVError
error while stopping the handle
class uv.PollEvent[source]

Events reported by uv.Poll on IO events.


File descriptor is readable.


File descriptor is writable.