NNG_PAIR(7)

✨ NNG_PAIR(7) ✨

okay bestie, welcome to the NNG Reference Manual page for nng_pair 💖 this is the pair protocol and it's genuinely one of the cutest little patterns in the whole library, no cap.

---

🌸 NAME 🌸

nng_pair — the pair protocol 🫶

---

🎀 SYNOPSIS 🎀

so depending on which version you're on, you're gonna grab a different header, okay? don't mix them up, i'm begging 🙈

Version 0

#include <nng/protocol/pair0/pair.h>

Version 1

#include <nng/protocol/pair1/pair.h>

---

💅 DESCRIPTION 💅

The pair protocol implements a peer-to-peer pattern, where relationships between peers are one-to-one. like, literally a duo. a two-person group chat. iconic.

🦋 Socket Operations 🦋

The nng_pair_open() functions create a pair socket. that's your entry point, bestie ✨

Normally, this pattern will block when attempting to send a message if no peer is able to receive the message. it's not ghosting you, it's just waiting 💀

Note 🚨 Even though this mode may appear to be reliable — because back-pressure prevents discarding messages most of the time — there are topologies involving devices (see nng_device()) or raw mode sockets (see NNG_OPT_RAW) where messages may be discarded. 😭 Applications that require reliable delivery semantics should consider using req sockets, or implement their own acknowledgment layer on top of pair sockets. periodt.

🌈 Protocol Versions 🌈

Version 0 is the legacy version of this protocol. It lacks any header information, and is suitable when building simple one-to-one topologies.

Tip 💡 Use version 0 if you need to communicate with other implementations, including the legacy nanomsg (https://github.com/nanomsg/nanomsg) library or mangos (https://github.com/go-mangos/mangos). iykyk.

Version 1 of the protocol offers improved protection against loops when used with nng_device(). glow up fr fr ✨

👑 Polyamorous Mode 👑

Warning ⚠️ Polyamorous mode is deprecated, and support for it will likely be removed in a future release. Applications are strongly discouraged from making further use of it. like, it's giving "we're breaking up eventually", bestie. 💔

Normally pair sockets are for one-to-one communication, and a given peer will reject new connections if it already has an active connection to another peer. exclusive vibes only 🙅‍♀️

Polyamorous mode changes this, to allow a socket to communicate with multiple directly-connected peers. This mode is enabled by opening a socket with the nng_pair1_open_poly() function ✨

Note 🌸 Polyamorous mode is only available when using pair version 1.

In polyamorous mode a socket can support many one-to-one connections. In this mode, the application must choose the remote peer to receive an outgoing message by setting the nng_pipe to use for the outgoing message with the nng_msg_set_pipe() function. you're picking the main character of this message, bestie 👑

If no remote peer is specified by the sender, then the protocol will select any available connected peer. dealer's choice, literally 🎲

Most often the value of the outgoing pipe will be obtained from an incoming message using the nng_msg_get_pipe() function, such as when replying to an incoming message. yes, you caught it from the incoming vibe and you're sending it right back ✨

Note 💀 Directed send only works with directly connected peers. It will not function across device proxies.

In order to prevent head-of-line blocking, if the peer on the given pipe is not able to receive (or the pipe is no longer available, such as if the peer has disconnected), then the message will be discarded with no notification to the sender. 🗑️ no receipt, no read, nothing. gone.

🍓 Protocol Options 🍓

The following protocol-specific options are available:

• NNG_OPT_MAXTTL — (int, version 1 only). Maximum time-to-live. your message's lil expiration date 🫶
• NNG_OPT_PAIR1_POLY — (bool, version 1 only). This option is no longer supported. Formerly it was used to configure polyamorous mode, but that mode is now established by using the nng_pair1_open_poly() function. it's retired bestie, we don't use it anymore 💅

🧚 Protocol Headers 🧚

Version 0 of the pair protocol has no protocol-specific headers. clean face, no makeup ✨

Version 1 of the pair protocol uses a single 32-bit unsigned value. The low-order (big-endian) byte of this value contains a "hop" count, and is used in conjunction with the NNG_OPT_MAXTTL option to guard against device forwarding loops. This value is initialized to 1, and incremented each time the message is received by a new node. cute lil hop counter, keeping the loops from happening 🦋

---

💜 SEE ALSO 💜

• nng_pair_open(3)
• nng_options(5)
• nng(7)

---

and that's the whole page, bestie!! 🌟 this was NNG_PAIR(7) from the NNG Reference Manual, dated 2026-06-30 💖 go forth and pair responsibly, mwah 🎀💅🫶