diff options
| -rw-r--r-- | docs/ref/proto/sub.md | 58 | ||||
| -rw-r--r-- | docs/ref/xref.md | 14 |
2 files changed, 53 insertions, 19 deletions
diff --git a/docs/ref/proto/sub.md b/docs/ref/proto/sub.md index 5234b6fb..fcfab49f 100644 --- a/docs/ref/proto/sub.md +++ b/docs/ref/proto/sub.md @@ -19,25 +19,57 @@ Applications should construct their messages accordingly. ### Socket Operations -The [`nng_sub0_open`] functions create a _SUB_ socket. -This socket may be used to receive messages, but is unable to send them. -Attempts to send messages will result in [`NNG_ENOTSUP`]. +```c +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); +``` -### Protocol Versions +The {{i:`nng_sub0_open`}} and {{i:`nng_sub0_open_raw`}} functions create a _SUB_ socket in +either [cooked] or [raw] mode. -Only version 0 of this protocol is supported. -(At the time of writing, no other versions of this protocol have been defined.) +The {{i:`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 {{i:`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][context]. + +```c +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 {{i:`nng_sub0_ctx_subscribe`}} and {{i:`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 -The following protocol-specific option is available. +| Option | Type | Description | +| ---------------------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| {{i:`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. | -- {{i:`NNG_OPT_SUB_PREFNEW`}}: \ - (`bool`) \ - \ - This read/write option specifies the behavior of the subscriber when the queue is full. - When `true` (the default), the subscriber will make room in the queue by removing the oldest message. - When `false`, the subscriber will reject messages if the message queue does not have room. +### 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 diff --git a/docs/ref/xref.md b/docs/ref/xref.md index e8aa03ea..8ac6e2f5 100644 --- a/docs/ref/xref.md +++ b/docs/ref/xref.md @@ -172,10 +172,10 @@ [`nng_stream_listener_set_string`]: ../api/stream.md#stream-factory-options [`nng_init`]: ../api/init.md#initialization [`nng_fini`]: ../api/init.md#finalization -[`nng_sub0_ctx_subscribe`]: ../TODO.md -[`nng_sub0_ctx_unsubscribe`]: ../TODO.md -[`nng_sub0_socket_subscribe`]: ../TODO.md -[`nng_sub0_socket_unsubscribe`]: ../TODO.md +[`nng_sub0_ctx_subscribe`]: ../proto/sub.md#context-operations +[`nng_sub0_ctx_unsubscribe`]: ../proto/sub.md#context-operations +[`nng_sub0_socket_subscribe`]: ../proto/sub.md#socket-operations +[`nng_sub0_socket_unsubscribe`]: ../proto/sub.md#socket-operations [`nng_bus0_open`]: ../api/sock.md#opening-a-socket [`nng_pair_open`]: ../api/sock.md#opening-a-socket [`nng_pair0_open`]: ../api/sock.md#opening-a-socket @@ -454,6 +454,7 @@ [`NNG_OPT_PEER_GID`]: ../tran/ipc.md#NNG_OPT_PEER_GID [`NNG_OPT_PEER_PID`]: ../tran/ipc.md#NNG_OPT_PEER_PID [`NNG_OPT_PEER_ZONEID`]: ../tran/ipc.md#NNG_OPT_PEER_ZONEID +[`NNG_OPT_SUB_PREF_NEW`]: ../proto/sub.md#protocol-options [`NNG_OPT_IPC_PERMISSIONS`]: ../tran/ipc.md#NNG_OPT_IPC_PERMISSIONS [`NNG_SOCKET_INITIALIZER`]: ../api/sock.md#socket-structure [`NNG_CTX_INITIALIZER`]: ../api/ctx.md#context-structure @@ -486,10 +487,11 @@ <!-- Concept index --> [aio]: ../api/aio.md +[cooked]: ../api/sock.md#raw-mode-sockets [raw]: ../api/sock.md#raw-mode-sockets [pipe]: ../api/pipe.md -[socket]: ../TODO.md -[context]: ../TODO.md +[socket]: ../api/sock.md +[context]: ../api/ctx.md [device]: ../TODO.md [dialer]: ../TODO.md [listener]: ../TODO.md |