Struct libuv::handles::poll::PollHandle

pub struct PollHandle { /* fields omitted */ }

Poll handles are used to watch file descriptors for readability, writability and disconnection similar to the purpose of poll(2).

The purpose of poll handles is to enable integrating external libraries that rely on the event loop to signal it about the socket status changes, like c-ares or libssh2. Using PollHandle for any other purpose is not recommended; TcpHandle, UdpHandle, etc. provide an implementation that is faster and more scalable than what can be achieved with PollHandle, especially on Windows.

It is possible that poll handles occasionally signal that a file descriptor is readable or writable even when it isn’t. 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.

The user should 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 a call to stop() or close().

Note: On windows only sockets can be polled with poll handles. On Unix any file descriptor that would be accepted by poll(2) can be used.

Note: On AIX, watching for disconnection is not supported.

Implementations

impl PollHandle

pub fn new(r#loop: &Loop, fd: File) -> Result<PollHandle>

Create and initialize a new poll handle using a file descriptor

pub fn new_socket(r#loop: &Loop, socket: Socket) -> Result<PollHandle>

Create and initialize a new poll handle using a socket descriptor. On Unix this is identical to new(). On windows it takes a SOCKET handle.

pub fn start<CB: Into<PollCB<'static>>>(
    &mut self,
    events: PollEvents,
    cb: CB
) -> Result<()>

Starts polling the file descriptor. events is a bitmask made up of READABLE, WRITABLE, PRIORITIZED and DISCONNECT. As soon as an event is detected the callback will be called with status set to 0, and the detected events set on the events field.

The PRIORITIZED event is used to watch for sysfs interrupts or TCP out-of-band messages.

The DISCONNECT event is optional in the sense that it may not be reported and the user is free to ignore it, but it can help optimize the shutdown path because an extra read or write call might be avoided.

If an error happens while polling, status will a libuv::Error. The user should not close the socket while the handle is active. If the user does that anyway, the callback may be called reporting an error status, but this is not guaranteed.

Note: Calling start() on a handle that is already active is fine. Doing so will update the events mask that is being watched for.

Note: Though DISCONNECT can be set, it is unsupported on AIX and as such will not be set on the events field in the callback.

pub fn stop(&mut self) -> Result<()>

Stop polling the file descriptor, the callback will no longer be called.

Trait Implementations

impl Clone for PollHandle

fn clone(&self) -> PollHandle

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Copy for PollHandle

impl From<PollHandle> for Handle

fn from(poll: PollHandle) -> Handle

Performs the conversion.

impl HandleTrait for PollHandle

fn is_active(&self) -> bool

Returns non-zero if the handle is active, zero if it’s inactive. What “active” means depends on the type of handle: * An AsyncHandle is always active and cannot be deactivated, except by closing it with close(). * A PipeHandle, TcpHandle, UdpHandle, etc. - basically any handle that deals with i/o - is active when it is doing something that involves i/o, like reading, writing, connecting, accepting new connections, etc. * A CheckHandle, IdleHandle, TimerHandle, etc. is active when it has been started with a call to start().

fn is_closing(&self) -> bool

Returns non-zero if the handle is closing or closed, zero otherwise.

fn close<CB: Into<CloseCB<'static>>>(&mut self, cb: CB)

Request handle to be closed. close_cb will be called asynchronously after this call. This MUST be called on each handle before memory is released. Moreover, the memory can only be released in close_cb or after it has returned.

fn ref(&mut self)

Reference the given handle. References are idempotent, that is, if a handle is already referenced calling this function again will have no effect.

fn unref(&mut self)

Un-reference the given handle. References are idempotent, that is, if a handle is not referenced calling this function again will have no effect.

fn has_ref(&self) -> bool

Returns true if the handle referenced, zero otherwise.

fn send_buffer_size(&mut self, value: i32) -> Result<i32>

Gets or sets the size of the send buffer that the operating system uses for the socket.

fn recv_buffer_size(&mut self, value: i32) -> Result<i32>

Gets or sets the size of the receive buffer that the operating system uses for the socket.

fn get_fileno(&self) -> Result<OsFile>

Gets the platform dependent file descriptor equivalent.

fn get_loop(&self) -> Loop

Returns the Loop associated with this handle.

fn get_type(&self) -> HandleType

Returns the type of the handle.

impl ToHandle for PollHandle

fn to_handle(&self) -> Handle

impl TryFrom<Handle> for PollHandle

type Error = ConversionError

The type returned in the event of a conversion error.

fn try_from(handle: Handle) -> Result<Self, Self::Error>

Performs the conversion.