NNG_SURVEYOR(7)

📦
version 1.12.0 · 4 versions
, in ubuntu stonking

💖 NNG_SURVEYOR(7) 💖

okay bestie, welcome to the NNG Reference Manual — today's main character is nng_surveyor, aka the surveyor protocol, and honestly? she's giving pollster energy and we're obsessed. 🗳️✨

✨ SYNOPSIS ✨

#include <nng/nng.h>
#include <nng/protocol/survey0/survey.h>

🌸 DESCRIPTION 🌸

so the surveyor protocol is, like, one half of a survey pattern. here's the vibe: a surveyor sends out a survey, and that survey gets broadcast to every single peer respondent. then the respondents get their chance to reply — but like, no pressure, they're not obliged to reply. it's not that kind of relationship. 💅

and the survey itself? it's a timed event, periodt. so if responses roll in after the survey has finished, they get discarded. bye bestie, you're too late. 🦋

Tip 💡 this protocol is lowkey perfect for solving voting problems — think leader election in cluster configurations — and also certain kinds of service discovery problems. iykyk.

so to be super clear: the surveyor protocol is the surveyor side, and the respondent protocol (nng_respondent) is the respondent side. two halves, one iconic duo. 🫶

🎀 Socket Operations 🎀

the nng_surveyor0_open() functions create a surveyor socket. this socket can be used to send messages (that's your surveys) and then to receive replies. but here's the thing — a reply can only be received after sending a survey. no survey, no replies, that's the rule.

a surveyor can normally expect to receive at most one reply from each responder. ngl though, messages can be duplicated in some topologies, so there's genuinely no guarantee of that. 🙈

attempts to receive on a socket with no outstanding survey will result in NNG_ESTATE. and if the survey times out while the surveyor is waiting for replies, then the result will be NNG_ETIMEDOUT. 😭

also important, and i mean really important: only one survey can be outstanding at a time. sending another survey cancels the prior one, and any responses from respondents from that prior survey that arrive after this point? discarded. gone. not invited to the group chat. 💀

raw mode sockets ignore all these restrictions, because raw mode does whatever it wants. 👑

🦋 Context Operations 🦋

this protocol supports the creation of contexts for concurrent use cases using nng_ctx_open(). slay.

  • each context can initiate its own surveys, and it will receive only responses to its own outstanding surveys.
  • other contexts on the same socket may have overlapping surveys operating at the same time. multitasking queen energy.
  • each of these may have their own timeouts established with NNG_OPT_SURVEYOR_SURVEYTIME. ✨
  • additionally, sending a survey on a context will only cancel an outstanding survey on the same context. it doesn't reach over and mess with anyone else's.
Note ⚠️ due to the best-effort nature of this protocol, if too may contexts are attempting to perform surveys simultaneously, it is possible for either individual outgoing surveys or incoming responses to be lost. fr fr, keep that in mind.

⭐ Protocol Versions ⭐

only version 0 of this protocol is supported. (at the time of writing, no other versions of this protocol have been defined. an earlier and incompatible version of the protocol was used in older pre-releases of [nanomsg](http://nanomsg.org), but was not released in any production version. so, like, ancient lore. 🏺)

💜 Protocol Options 💜

the following protocol-specific options is available. (that's the whole list, bestie — one iconic option.)

  • NNG_OPT_SURVEYOR_SURVEYTIME — (nng_duration) the Duration of surveys. when a new survey is started, a timer of this duration is also started. any responses arriving this time will be discarded. attempts to receive after the timer expires with no other surveys started will result in NNG_ESTATE. attempts to receive when this timer expires will result in NNG_ETIMEDOUT. it's giving ticking clock. ⏰

🧚 Protocol Headers 🧚

okay this part is the ✨spicy✨ bit, stay with me.

this form uses a stack of 32-bit big-endian identifiers. there must be at least one identifier, the survey ID, which will be the last element in the array, and must have the most significant bit set. 💅

there may be additional peer IDs preceding the survey ID. these will be distinguishable from the survey ID by having their most significant bit clear.

when a survey message is received by a forwarding node (see nng_device()), the forwarding node prepends a 32-bit peer ID (which must have the most significant bit clear), which is the forwarder's way of identifying the directly connected peer from which it received the message. (this peer ID, except for the most significant bit, has meaning only to the forwarding node itself. it's a private little thing. 🙈)

it may help to think of prepending a peer ID as pushing a peer ID onto the front of the stack of headers for the message. (it will use the peer ID it popped from the front to determine the next intermediate destination for the response.)

when a response message is created, it is created using the same headers that the survey contained. matching set, obviously.

a forwarding node can pop the peer ID it originally pushed on the message, stripping it from the front of the message as it does so. very demure, very mindful, cleaning up after itself.

when the response finally arrives back at the initiating surveyor, it should have only a single element in the message, which will be the survey ID it originally used for the request. full circle moment. 🫶

more detail can be found in the [RFC sp-surveyor-01](https://github.com/nanomsg/nanomsg/blob/master/rfc/sp-surveyor-01.txt) document. go read it, bestie, it's a whole vibe.

👑 SEE ALSO 👑

and that's the whole page, babe! 💖 this was the NNG Reference Manual on nng_surveyor(7), dated 2026-06-30, and yes you do have to remember the survey ID. no cap. slay, go build something. 🌈⭐🎀

📦 where this page comes from