NET_RefAddress(3)

💖 NET_RefAddress(3) 💖

okay bestie, welcome to the SDL_net3 functions corner of the manual, and today's main character is NET_RefAddress 🫶

---

✨ NAME ✨

NET_RefAddress — add a reference to an NET_Address. that's it, that's the job 💅

---

🌸 SYNOPSIS 🌸

#include <SDL3_net/SDL_net.h>

NET_Address* NET_RefAddress(NET_Address *address);

---

🦋 DESCRIPTION 🦋

so here's the tea ☕ — multiple pieces of the library can share a single NET_Address, and that includes a background thread that's out there working on resolving. because of that, these objects are reference counted. it's giving "we all agree we still want this thing." everything using it can declare it still wants it, and then drop its reference when it's done. and when the very last reference gets dropped, the object's resources are freed. gone. bye 👋✨

this function adds a reference to an NET_Address, which bumps its reference count up by one. no cap 📈

the documentation will tell you when your app has to explicitly unref an address. for example, NET_ResolveHostname() creates addresses that are already referenced, so the caller needs to unref it when done. don't forget, bestie 😭

generally you only have to explicitly ref an address when you've got different parts of your own app that will be sharing an address. in normal usage, you only have to unref things you've created once (kinda like you might free() something), but you are absolutely free to add extra refs if it makes sense. your app, your rules 👑

and the best part?? this returns the same address you passed in as a parameter, which makes it super easy to ref and assign in one single step. obsessed:

myAddr = NET_RefAddress(yourAddr);

---

🎀 FUNCTION PARAMETERS 🎀

• address — the NET_Address to add a reference to. yeah. that one. the address right there 🫵

---

🌈 RETURN VALUE 🌈

returns the same address that was passed as a parameter. not a copy, not a new one, the literal same one. iconic behavior honestly ⭐

---

🔥 THREAD SAFETY 🔥

it is safe to call this function from any thread. go wild, no vibe check needed 💀✨

---

👑 AVAILABILITY 👑

this function is available since SDL_net 3.0.0. so if you're on 3.0.0 or later, you're slaying 💅

---

fr fr: this whole ref/unref situation is just malloc/free energy but for shared addresses. you ref when you want in, you unref when you're out, and the last one to leave turns off the lights 🕯️

---

and that's a wrap on the page, babe 🎀 this was pulled straight from the SDL_net manual, version SDL_net 3.2.0 — go forth and reference count responsibly, bestie 💖🌸🦋