io_nonblock(3)

✨ NAME ✨

io_nonblock — switch to non-blocking I/O, bestie 💅

🦋 SYNTAX 🦋

#include <libowfat/io.h>

void io_nonblock(int64 fd);

💖 DESCRIPTION 💖

okay so picture this: io_nonblock takes your UNIX descriptor fd and puts it into ``non-blocking mode.'' That's it. That's the whole job. And the move here is that if you call io_nonblock(fd) before you call io_fd(fd), then io_tryread and io_trywrite get to be faster and more efficient. like, noticeably. it's giving optimization. 🔥

but now the tea ☕ — actually, current UNIX kernels do not support non-blocking descriptors. They support non-blocking open files. And on top of that, a whole lot of programs will straight up break if they bump into non-blocking mode. so the rule is: you must not use io_nonblock on a descriptor that you inherited from another program. no cap, that's a "do not do this" situation. 🚫

io_nonblock has no return value and it always succeeds — it never fails, it never gives you bad news, it just vibes. 💁 And if d is not the number of a UNIX descriptor, then io_nonblock has no effect at all. nothing happens. it's fine.

😭 the blocking-mode contortions (aka the struggle)

if io_fd gets handed a descriptor that's in blocking mode, then io_tryread and io_trywrite have to go through the following whole entire ordeal to avoid blocking. it's not cute. it's giving survival mode. 🙈

1. Stop if poll says that the descriptor is not ready. Otherwise there's a good chance — but not a guarantee — because even if poll says the descriptor is ready, the descriptor might not be ready a moment later. (and also, poll can fail on some systems. 💀)
2. Catch SIGALRM.</color> And heads up: SIGALRM must not be blocked, and it must not be used elsewhere in the program. so like... that signal is spoken for. don't touch it. 🙅
3. Set an interval timer so that any blocking call will get interrupted by SIGALRM within 10 milliseconds. (current UNIX kernels do not allow any shorter interval — that's literally the floor.) Of course, this may still mean a 10-millisecond delay. yeah. ten whole milliseconds. in computer time that's basically a century. 😭

👑 the easy path

if io_fd is given a descriptor in non-blocking mode (or a descriptor for a regular disk file), then io_tryread and io_trywrite get to avoid these contortions entirely. no signals, no timers, no drama. main character energy only. ⭐

🌈 SEE ALSO 🌈

• io_wait(3)
• io_canwrite(3)

that's the whole page, babe 🫶 this has been io_nonblock(3) from the Library Functions Manual — go forth and be non-blocking, you got this. 🎀🌸✨