NNG_DEVICE(3)

🌸 NNG_DEVICE(3) — bestie edition 🌸

okay so this is nng_device from the NNG Reference Manual, and honestly? it's giving "the little function that holds entire network topologies together." sit down, hydrate, we're learning message forwarding. 💖

✨ NAME ✨

nng_device — the message forwarding device, aka the girl who just passes notes between two friend groups, no questions asked.

🎀 SYNOPSIS 🎀

#include <nng/nng.h>

int nng_device(nng_socket s1, nng_socket s2);

void nng_device_aio(nng_aio *aio, nng_socket s1, nng_socket s2);

💅 DESCRIPTION 💅

So nng_device() and nng_device_aio() take messages that show up on one socket, s1, and forward them to another socket, s2 — and yes bestie, they go the other way too. both directions. it's mutual. 👑

These functions are literally the blueprint for forwarders, and forwarders are how you build those complex network topologies that give you improved horizontal scalability, reliability, and isolation. main character networking fr fr.

⚠️ only raw mode sockets are allowed up in here. you make those with the _raw forms of the various socket constructors, like nng_req0_open_raw(). no raw, no forwarding, that's the vibe check.

And the two functions are NOT the same energy:

• nng_device() — does not return until one of the sockets is closed. it just stays. committed. loyal.
• nng_device_aio() — returns immediately and operates completely in the background. busy girl behavior, no notes. ✨

🦋 Reflectors 🦋

plot twist: one of the sockets you pass in can be an unopened socket, initialized with the NNG_SOCKET_INITIALIZER special value. if that's the case, then the other socket must be valid, and it must use a protocol that is bidirectional and can peer with itself — like pair or bus. when that happens, the device acts as a reflector or loop-back device, where messages received from the valid socket are merely returned to the sender. boomerang energy. 🪃

💫 Forwarders 💫

when both sockets are valid, congrats, you've got yourself a forwarder or proxy. in that case s1 and s2 must be compatible with each other — meaning they should represent the opposite halves of a two protocol pattern, or both be the same protocol for a single protocol pattern.

the receipts:

• if s1 is a pub socket, then s2 must be a sub socket. 🫶
• or, if s1 is a bus socket, then s2 must also be a bus socket.

🌈 Operation 🌈

the nng_device() function moves messages between the provided sockets. simple as that, iconic as that.

when a protocol has a backtrace style header, routing information is present in the header of received messages, and is copied to the header of the output bound message. the underlying raw mode protocols supply the necessary header adjustments to add or remove routing headers as needed. this is what allows replies to be returned to requesters, and responses to be routed back to surveyors. it's the postal system but make it slay. 📬

the caller of these functions is required to close the sockets when the device is stopped. that's on you, bestie, nobody else is doing it.

additionally, some protocols have a maximum time-to-live to protect against forwarding loops and especially amplification loops. in these cases, the default limit (usually 8) ensures that messages will self-terminate when they have passed through too many forwarders — protecting the network from unlimited message amplification that can arise through misconfiguration. this is controlled via the NNG_OPT_MAXTTL option. 🛑

💀 Important 💀

not all protocols have support for guarding against forwarding loops, and even for those that do, forwarding loops can be extremely detrimental to network performance. like, unhinged levels of detrimental. do not let the loops happen.

🙈 Note 🙈

devices (forwarders and reflectors) act in best-effort delivery mode only. if a message is received from one socket that cannot be accepted by the other — due to backpressure or other issues — then the message is discarded. gone. she left, no forwarding address. 😭

🌟 Tip 🌟

use the request/reply pattern, which includes automatic retries by the requester, if reliable delivery is needed. that's the one that won't ghost you. 💖

⭐ RETURN VALUES ⭐

this function continues running, and only returns an appropriate error when one occurs, or if one of the sockets is closed. it's not a quick little in-and-out situation. it commits. periodt.

🔥 ERRORS 🔥

• NNG_ECLOSED — at least one of the sockets is not open. bestie is shut. 💀
• NNG_ENOMEM — insufficient memory is available. the brain is full, cannot retain.
• NNG_EINVAL — the sockets are not compatible, or are both invalid. incompatible fr, it's not gonna work out.

👑 SEE ALSO 👑

• nng_options(5) ✨
• nng_socket(5) ✨
• nng(7) ✨

---

and that's the whole page, bestie — the NNG Reference Manual version of NNG_DEVICE(3), dated 2026-06-30. go forth, forward messages responsibly, and close your sockets when you're done. mwah. 💅🦋🌈