Lely core libraries  2.2.5
poll.h File Reference

This header file is part of the I/O library; it contains I/O polling interface declarations. More...

#include <lely/io/io.h>
Include dependency graph for poll.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures

struct  io_event
 An I/O event. More...
 

Macros

#define IO_EVENT_INIT
 The static initializer for struct io_event.
 

Typedefs

typedef struct __io_poll io_poll_t
 An opaque I/O polling interface type.
 

Enumerations

enum  { IO_EVENT_SIGNAL = 0, IO_EVENT_ERROR = 1 << 0, IO_EVENT_READ = 1 << 1, IO_EVENT_WRITE = 1 << 2 }
 

Functions

io_poll_tio_poll_create (void)
 Creates a new I/O polling interface. More...
 
void io_poll_destroy (io_poll_t *poll)
 Destroys an I/O polling interface. More...
 
int io_poll_watch (io_poll_t *poll, io_handle_t handle, struct io_event *event, int keep)
 Registers an I/O device with an I/O polling interface and instructs it to watch for certain events. More...
 
int io_poll_wait (io_poll_t *poll, int maxevents, struct io_event *events, int timeout)
 Waits at most timeout milliseconds for at most maxevents I/O events to occur for any of the I/O devices registered with io_poll_watch(). More...
 
int io_poll_signal (io_poll_t *poll, unsigned char sig)
 Generates a signal event. More...
 

Detailed Description

This header file is part of the I/O library; it contains I/O polling interface declarations.

Author
J. S. Seldenthuis jseld.nosp@m.enth.nosp@m.uis@l.nosp@m.ely..nosp@m.com

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Definition in file poll.h.

Enumeration Type Documentation

◆ anonymous enum

anonymous enum
Enumerator
IO_EVENT_SIGNAL 

An event representing the occurrence of a signal.

IO_EVENT_ERROR 

An event signaling that an error has occurred for a file descriptor.

Errors will always be reported by io_poll_wait(), even if not requested by io_poll_watch(). Note that the arrival of high-priority or out-of-band (OOB) data is considered an error.

IO_EVENT_READ 

An event signaling that a file descriptor is ready for reading normal-priority (non-OOB) data.

IO_EVENT_WRITE 

An event signaling that a file descriptor is ready for writing normal-priority (non-OOB) data.

Definition at line 27 of file poll.h.

Function Documentation

◆ io_poll_create()

io_poll_t* io_poll_create ( void  )

Creates a new I/O polling interface.

See also
io_poll_destroy()

Definition at line 215 of file poll.c.

◆ io_poll_destroy()

void io_poll_destroy ( io_poll_t poll)

Destroys an I/O polling interface.

See also
io_poll_create()

Definition at line 240 of file poll.c.

◆ io_poll_watch()

int io_poll_watch ( io_poll_t poll,
io_handle_t  handle,
struct io_event event,
int  keep 
)

Registers an I/O device with an I/O polling interface and instructs it to watch for certain events.

This function is thread-safe and can be run concurrently with io_poll_wait(). However, it is not guaranteed that an ongoing wait will register the new events.

Parameters
polla pointer to an I/O polling interface.
handlea valid I/O device handle.
eventa pointer the events to watch. If events is NULL, the device is unregistered and removed from the polling interface. If not, a copy of *event is registered with the polling interface.
keepa flag indicating whether to keep watching the file descriptor after an event occurs.
Returns
0 on success, or -1 on error. In the latter case, the error number can be obtained with get_errc().

Definition at line 249 of file poll.c.

◆ io_poll_wait()

int io_poll_wait ( io_poll_t poll,
int  maxevents,
struct io_event events,
int  timeout 
)

Waits at most timeout milliseconds for at most maxevents I/O events to occur for any of the I/O devices registered with io_poll_watch().

Events that occur within timeout milliseconds are stored in *events. This function is thread-safe, but only a single invocation SHOULD run at the same time; otherwise the same event might be reported to multiple threads.

Parameters
polla pointer to an I/O polling interface.
maxeventsthe maximum number of events to return (MUST be larger than zero).
eventsan array of at least maxevents io_event structs. On success, *events contains the events that occurred within the timeout.
timeoutthe maximum timeout value (in milliseconds). If timeout is 0, this function will not wait. If timeout is negative, this function will wait indefinitely.
Returns
the number of events in *events, or -1 on error. In the latter case, the error number can be obtained with get_errc(). This function returns 0 if the timeout elapses without an event occurring.

Definition at line 349 of file poll.c.

◆ io_poll_signal()

int io_poll_signal ( io_poll_t poll,
unsigned char  sig 
)

Generates a signal event.

This function can be used to interrupt io_poll_wait(). Note that it is safe to call this function from a signal handler.

Parameters
polla pointer to an I/O polling interface.
sigthe signal number.
Returns
0 on success, or -1 on error. In the latter case, the error number can be obtained with get_errc().

Definition at line 590 of file poll.c.