From 09cf37703cd6081bd74a602fe87a2361a463db37 Mon Sep 17 00:00:00 2001 From: Bo Date: Sat, 8 Feb 2025 00:06:49 +0000 Subject: [PATCH] docs --- fio-stl.h | 4 +++- fio-stl.md | 31 +++++++++++++++++++------------ fio-stl/004 sock.h | 4 +++- fio-stl/004 sock.md | 31 +++++++++++++++++++------------ 4 files changed, 44 insertions(+), 26 deletions(-) diff --git a/fio-stl.h b/fio-stl.h index 1d73f58..04d8dd8 100644 --- a/fio-stl.h +++ b/fio-stl.h @@ -10861,7 +10861,9 @@ SFUNC size_t fio_sock_maximize_limits(size_t maximum_limit); * * A zero timeout returns immediately. * - * Possible events are POLLIN | POLLOUT + * Possible events include POLLIN | POLLOUT + * + * Possible return values include POLLIN | POLLOUT | POLLHUP | POLLNVAL */ SFUNC short fio_sock_wait_io(int fd, short events, int timeout); diff --git a/fio-stl.md b/fio-stl.md index 88ab785..4c6300d 100644 --- a/fio-stl.md +++ b/fio-stl.md @@ -4168,33 +4168,40 @@ Uses `poll` to wait until an IO device has one or more of the evens listed in `e Returns 0 on timeout, -1 on error or the events that are valid. -#### `FIO_SOCK_POLL_RW` (macro) +Possible valid return values also include `POLLIN | POLLOUT | POLLHUP | POLLNVAL` + +#### `FIO_SOCK_WAIT_RW` ```c -#define FIO_SOCK_POLL_RW(fd_) \ - (struct pollfd) { .fd = fd_, .events = (POLLIN | POLLOUT) } +#define FIO_SOCK_WAIT_RW(fd, timeout_) fio_sock_wait_io(fd, POLLIN | POLLOUT, timeout_) ``` -This helper macro helps to author a `struct pollfd` member who's set to polling for both read and write events (data availability and/or space in the outgoing buffer). +A helper macro that waits on a single IO with no callbacks (0 = no event) -#### `FIO_SOCK_POLL_R` (macro) +#### `FIO_SOCK_WAIT_R` ```c -#define FIO_SOCK_POLL_R(fd_) \ - (struct pollfd) { .fd = fd_, .events = POLLIN } +#define FIO_SOCK_WAIT_R(fd, timeout_) fio_sock_wait_io(fd, POLLIN, timeout_) ``` -This helper macro helps to author a `struct pollfd` member who's set to polling for incoming data availability. +A helper macro that waits on a single IO with no callbacks (0 = no event) + +#### `FIO_SOCK_WAIT_W` + +```c +#define FIO_SOCK_WAIT_W(fd, timeout_) fio_sock_wait_io(fd, POLLOUT, timeout_) +``` +A helper macro that waits on a single IO with no callbacks (0 = no event) -#### `FIO_SOCK_POLL_W` (macro) +#### `FIO_SOCK_IS_OPEN` ```c -#define FIO_SOCK_POLL_W(fd_) \ - (struct pollfd) { .fd = fd_, .events = POLLOUT } +#define FIO_SOCK_IS_OPEN(fd) \ + (!(fio_sock_wait_io(fd, POLLOUT, 0) & (POLLHUP | POLLNVAL))) ``` -This helper macro helps to author a `struct pollfd` member who's set to polling for space in the outgoing `fd`'s buffer. +A helper macro that tests if a socket was remotely closed. #### `fio_sock_address_new` diff --git a/fio-stl/004 sock.h b/fio-stl/004 sock.h index 28f1160..4e7a15c 100644 --- a/fio-stl/004 sock.h +++ b/fio-stl/004 sock.h @@ -197,7 +197,9 @@ SFUNC size_t fio_sock_maximize_limits(size_t maximum_limit); * * A zero timeout returns immediately. * - * Possible events are POLLIN | POLLOUT + * Possible events include POLLIN | POLLOUT + * + * Possible return values include POLLIN | POLLOUT | POLLHUP | POLLNVAL */ SFUNC short fio_sock_wait_io(int fd, short events, int timeout); diff --git a/fio-stl/004 sock.md b/fio-stl/004 sock.md index 6c41554..3c5b18c 100644 --- a/fio-stl/004 sock.md +++ b/fio-stl/004 sock.md @@ -104,33 +104,40 @@ Uses `poll` to wait until an IO device has one or more of the evens listed in `e Returns 0 on timeout, -1 on error or the events that are valid. -#### `FIO_SOCK_POLL_RW` (macro) +Possible valid return values also include `POLLIN | POLLOUT | POLLHUP | POLLNVAL` + +#### `FIO_SOCK_WAIT_RW` ```c -#define FIO_SOCK_POLL_RW(fd_) \ - (struct pollfd) { .fd = fd_, .events = (POLLIN | POLLOUT) } +#define FIO_SOCK_WAIT_RW(fd, timeout_) fio_sock_wait_io(fd, POLLIN | POLLOUT, timeout_) ``` -This helper macro helps to author a `struct pollfd` member who's set to polling for both read and write events (data availability and/or space in the outgoing buffer). +A helper macro that waits on a single IO with no callbacks (0 = no event) -#### `FIO_SOCK_POLL_R` (macro) +#### `FIO_SOCK_WAIT_R` ```c -#define FIO_SOCK_POLL_R(fd_) \ - (struct pollfd) { .fd = fd_, .events = POLLIN } +#define FIO_SOCK_WAIT_R(fd, timeout_) fio_sock_wait_io(fd, POLLIN, timeout_) ``` -This helper macro helps to author a `struct pollfd` member who's set to polling for incoming data availability. +A helper macro that waits on a single IO with no callbacks (0 = no event) + +#### `FIO_SOCK_WAIT_W` + +```c +#define FIO_SOCK_WAIT_W(fd, timeout_) fio_sock_wait_io(fd, POLLOUT, timeout_) +``` +A helper macro that waits on a single IO with no callbacks (0 = no event) -#### `FIO_SOCK_POLL_W` (macro) +#### `FIO_SOCK_IS_OPEN` ```c -#define FIO_SOCK_POLL_W(fd_) \ - (struct pollfd) { .fd = fd_, .events = POLLOUT } +#define FIO_SOCK_IS_OPEN(fd) \ + (!(fio_sock_wait_io(fd, POLLOUT, 0) & (POLLHUP | POLLNVAL))) ``` -This helper macro helps to author a `struct pollfd` member who's set to polling for space in the outgoing `fd`'s buffer. +A helper macro that tests if a socket was remotely closed. #### `fio_sock_address_new`