NET_WAITUNTILINPUTAVAILABLE(3)

💖 NET_WaitUntilInputAvailable(3) 💖

okay bestie, grab a boba because we're diving into the SDL_net3 manual, and this one is a functions girlie through and through. her name is NET_WaitUntilInputAvailable, and she's the friend who holds your spot in line while you're asleep. let's go 🫶

---

✨ NAME ✨

NET_WaitUntilInputAvailable — block on multiple sockets until at least one of them has data available. literally just vibing on a bunch of sockets at once, waiting for one of them to wake up 💅

---

🌸 SYNOPSIS 🌸

#include <SDL3_net/SDL_net.h>

int NET_WaitUntilInputAvailable(void **vsockets, int numsockets, Sint32 timeout);

---

🦋 DESCRIPTION 🦋

ngl, this is a complex function that most apps won't need, but it could be used to implement a more efficient server or i/o thread in some cases. so like, not for everyone, but if you're that girl, you're that girl ✨

this lets you hand it a list of objects and then wait for new input to become available on any of them. the calling thread is put to sleep until such a time. it's giving "nap until someone knocks" energy 😴

here's what you can put in the vsockets array, each one cast to void *:

• NET_Server — reports new input when a connection is ready to be accepted with NET_AcceptClient(). so someone's knocking at the door 🚪
• NET_StreamSocket — reports new input when the remote end has sent more bytes of data to be read with NET_ReadFromStreamSocket, or if the socket finished making its initial connection. new messages in the group chat 💬
• NET_DatagramSocket — reports new input when a new packet arrives that can be read with NET_ReceiveDatagram. a whole lil parcel just landed 📦

this function takes a timeout value, represented in milliseconds, of how long to wait for resolution to complete. specifying a timeout of -1 instructs the library to wait indefinitely, and a timeout of 0 just checks the current status and returns immediately. so: -1 is "i'll wait forever, i'm loyal", 0 is "okay bye, tell me if anything happened" 🏃♀️

this returns the number of items that have new input, but it does not tell you which ones. since access to them is non-blocking, you can just try to read from each of them and see which are ready. if nothing is ready and the timeout is reached, this returns zero. on error, this returns -1. so you gotta do the detective work yourself, bestie 🔍

---

🎀 FUNCTION PARAMETERS 🎀

• vsockets — an array of pointers to various objects that can be waited on, each cast to a void pointer.
• numsockets — the number of pointers in the vsockets array.
• timeout — number of milliseconds to wait for new input to become available. -1 to wait indefinitely, 0 to check once without waiting.

---

🌈 RETURN VALUE 🌈

returns the number of items that have new input, or -1 on error. that's it, that's the whole tea ☕

---

🧚 THREAD SAFETY 🧚

you should not operate on the same socket from multiple threads at the same time without supplying a serialization mechanism. however, different threads may access different sockets at the same time without problems. so like — one socket, one thread, no sharing, no drama 🙈 shared custody of the same socket is a no, but y'all can each hold your own socket at the same time, no problem 💜

---

⭐ AVAILABILITY ⭐

this function is available since SDL_net 3.0.0. she's been iconic since day one, no cap 👑

---

👑 SEE ALSO 👑

• NET_CreateDatagramSocket(3)
• NET_SendDatagram(3)
• NET_ReceiveDatagram(3)

---

and that's the whole page, bestie!! this was brought to you by the SDL_net girlies, version SDL_net 3.2.0 — fr fr, slay, periodt 💅✨🎀🦋💖