SUB protocol

The SUB protocol is one half of a publisher/subscriber pattern. In this pattern, a publisher sends data, which is broadcast to all subscribers. The subscribing applications only see the data to which they have subscribed.

The SUB protocol is the subscriber side, and the PUB protocol is the publisher side.

note

The publisher delivers all messages to all subscribers. The subscribers maintain their own subscriptions, and filter them locally. Thus, this pattern should not be used in an attempt to reduce bandwidth consumption.

The topics that subscribers subscribe to is compared to the leading bytes of the message body. Applications should construct their messages accordingly.

Socket Operations

int nng_sub0_open(nng_socket *);
int nng_sub0_open_raw(nng_socket *);
int nng_sub0_socket_subscribe(nng_socket id, const void *buf, size_t sz);
int nng_sub0_socket_unsubscribe(nng_socket id, const void *buf, size_t sz);

The nng_sub0_open and nng_sub0_open_raw functions create a SUB socket in either cooked or raw mode.

The nng_sub0_socket_subscribe function is used to add a subscription topic to the socket. Messages that do not match any subscription topic will be filtered out, and unavailable for receiving.

A message is deemed to match a subscription if it has at least sz bytes, and the first sz bytes are the same as buf.

The nng_sub0_socket_unsubscribe function removes a subscription from the socket.

note

A socket with no subscriptions cannot receive messages.

tip

To receive all messages, simply subscribe to a zero length topic.

Context Operations

The SUB protocol supports contexts.

int nng_sub0_ctx_subscribe(nng_ctx id, const void *buf, size_t sz);
int nng_sub0_ctx_unsubscribe(nng_ctx id, const void *buf, size_t sz);

The nng_sub0_ctx_subscribe and nng_sub0_ctx_unsubscribe functions perform manage subscriptions for the context in precisely the same way that nng_sub0_socket_subscribe and nng_sub0_socket_unsubscribe do.

Each context maintains its own set of subscriptions, and these are also independent of socket level subscriptions.

Protocol Options

Option	Type	Description
`NNG_OPT_SUB_PREF_NEW`	`bool`	If `true` (default), when the receive queue is full, then older unreceived messages will be discarded to make room for newer messages. If `false`, the older message is preserved and the newer message is discarded.

Protocol Versions

Only version 0 of this protocol is supported. (At the time of writing, no other versions of this protocol have been defined.)

Protocol Headers

The SUB protocol has no protocol-specific headers.