Poll – poll handle

class uv.Poll(fd, loop=None, callback=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 an more scalable implementations, that 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 during the initialization of the handle

  • fd (int) – file descriptor which should be polled (is set to non-blocking mode)
  • loop (Loop) – event loop which should be used for the handle
  • callback ((uv.Poll, uv.StatusCode, int) -> None) – callback which should be called on IO events

File descriptor the handle polls on.


Callback which should be called on IO events.

callback(Poll-Handle, Status-Code, Event-Mask)
Type:(uv.Poll, uv.StatusCode, int) -> None
start(events=<PollEvent.READABLE: 1>, callback=None)[source]

Starts polling the file descriptor for the given events. As soon as an event is detected the callback will be called with status code uv.StatusCode.SUCCESS and the detected 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 watched for.

  • events (int) – bitmask of events which should be polled for
  • callback ((uv.Poll, uv.StatusCode, int) -> None) – callback which should be called on IO events

Stops the handle, the callback will no longer be called.

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

Poll event types enumeration.


File descriptor is readable.


File descriptor is writable.