Struct base::sys::linux::EventContext

pub struct EventContext<T> {
    epoll_ctx: File,
    tokens: PhantomData<[T]>,
}

Used to poll multiple objects that have file descriptors.

See crate::WaitContext for an example that uses the cross-platform wrapper.

Fields

epoll_ctx: File

tokens: PhantomData<[T]>

Implementations

impl<T: EventToken> EventContext<T>

pub fn new() -> Result<EventContext<T>>

Creates a new EventContext.

pub fn build_with( fd_tokens: &[(&dyn AsRawDescriptor, T)], ) -> Result<EventContext<T>>

Creates a new EventContext and adds the slice of fd and token tuples to the new context.

This is equivalent to calling new followed by add_many. If there is an error, this will return the error instead of the new context.

pub fn add_many(&self, fd_tokens: &[(&dyn AsRawDescriptor, T)]) -> Result<()>

Adds the given slice of fd and token tuples to this context.

This is equivalent to calling add with each fd and token. If there are any errors, this method will stop adding fds and return the first error, leaving this context in a undefined state.

pub fn add(&self, fd: &dyn AsRawDescriptor, token: T) -> Result<()>

Adds the given fd to this context and associates the given token with the fd’s readable events.

A fd can only be added once and does not need to be kept open. If the fd is dropped and there were no duplicated file descriptors (i.e. adding the same descriptor with a different FD number) added to this context, events will not be reported by wait anymore.

pub fn add_for_event( &self, descriptor: &dyn AsRawDescriptor, event_type: EventType, token: T, ) -> Result<()>

Adds the given descriptor to this context, watching for the specified events and associates the given ‘token’ with those events.

A descriptor can only be added once and does not need to be kept open. If the descriptor is dropped and there were no duplicated file descriptors (i.e. adding the same descriptor with a different FD number) added to this context, events will not be reported by wait anymore.

pub fn modify( &self, fd: &dyn AsRawDescriptor, event_type: EventType, token: T, ) -> Result<()>

If fd was previously added to this context, the watched events will be replaced with event_type and the token associated with it will be replaced with the given token.

pub fn delete(&self, fd: &dyn AsRawDescriptor) -> Result<()>

Deletes the given fd from this context. If the fd is not being polled by this context, the call is silently dropped without errors.

If an fd’s token shows up in the list of hangup events, it should be removed using this method or by closing/dropping (if and only if the fd was never dup()’d/fork()’d) the fd. Failure to do so will cause the wait method to always return immediately, causing ~100% CPU load.

pub fn wait(&self) -> Result<SmallVec<[TriggeredEvent<T>; 16]>>

Waits for any events to occur in FDs that were previously added to this context.

The events are level-triggered, meaning that if any events are unhandled (i.e. not reading for readable events and not closing for hungup events), subsequent calls to wait will return immediately. The consequence of not handling an event perpetually while calling wait is that the callers loop will degenerated to busy loop polling, pinning a CPU to ~100% usage.

pub fn wait_timeout( &self, timeout: Duration, ) -> Result<SmallVec<[TriggeredEvent<T>; 16]>>

Like wait except will only block for a maximum of the given timeout.

This may return earlier than timeout with zero events if the duration indicated exceeds system limits.

Trait Implementations

impl<T: EventToken> AsRawDescriptor for EventContext<T>

fn as_raw_descriptor(&self) -> RawDescriptor

Returns the underlying raw descriptor.