From 0bd3a9f51ce5800ad023ee548a90f91726ef0e88 Mon Sep 17 00:00:00 2001 From: gdamore Date: Sat, 9 Nov 2024 21:33:57 +0000 Subject: deploy: 150d80c2c62ce3693dbbd0256c16337879c7d825 --- ref/api/logging.html | 34 +++++----- ref/api/sock.html | 43 +++++++++++++ ref/api/synch.html | 36 +++++------ ref/indexing.html | 8 +-- ref/migrate/nng1.html | 17 +++-- ref/print.html | 172 ++++++++++++++++++++++++++++---------------------- ref/proto/sub.html | 34 +--------- ref/searchindex.js | 2 +- ref/searchindex.json | 2 +- 9 files changed, 196 insertions(+), 152 deletions(-) diff --git a/ref/api/logging.html b/ref/api/logging.html index 9813013c..3a6ced13 100644 --- a/ref/api/logging.html +++ b/ref/api/logging.html @@ -287,12 +287,12 @@ set by nng_log_set_level or the default if that function has not been called.

The log levels are defined as follows:

typedef enum nng_log_level {
-	NNG_LOG_NONE   = 0, // used for filters only, NNG suppresses these
-	NNG_LOG_ERR    = 3,
-	NNG_LOG_WARN   = 4,
-	NNG_LOG_NOTICE = 5,
-	NNG_LOG_INFO   = 6,
-	NNG_LOG_DEBUG  = 7
+    NNG_LOG_NONE   = 0, // used for filters only, NNG suppresses these
+    NNG_LOG_ERR    = 3,
+    NNG_LOG_WARN   = 4,
+    NNG_LOG_NOTICE = 5,
+    NNG_LOG_INFO   = 6,
+    NNG_LOG_DEBUG  = 7
 } nng_log_level;

The value NNG_LOG_NONE may be useful to suppress message logs altogether.

@@ -309,17 +309,17 @@ Traditionally these are used with the UNIX syslog system, and the values here represent some (but not all) of the values found there.

The following values are defined:

typedef enum nng_log_facility {
-	NNG_LOG_USER   = 1,
-	NNG_LOG_DAEMON = 3,
-	NNG_LOG_AUTH   = 10,
-	NNG_LOG_LOCAL0 = 16,
-	NNG_LOG_LOCAL1 = 17,
-	NNG_LOG_LOCAL2 = 18,
-	NNG_LOG_LOCAL3 = 19,
-	NNG_LOG_LOCAL4 = 20,
-	NNG_LOG_LOCAL5 = 21,
-	NNG_LOG_LOCAL6 = 22,
-	NNG_LOG_LOCAL7 = 23,
+    NNG_LOG_USER   = 1,
+    NNG_LOG_DAEMON = 3,
+    NNG_LOG_AUTH   = 10,
+    NNG_LOG_LOCAL0 = 16,
+    NNG_LOG_LOCAL1 = 17,
+    NNG_LOG_LOCAL2 = 18,
+    NNG_LOG_LOCAL3 = 19,
+    NNG_LOG_LOCAL4 = 20,
+    NNG_LOG_LOCAL5 = 21,
+    NNG_LOG_LOCAL6 = 22,
+    NNG_LOG_LOCAL7 = 23,
 } nng_log_facility;

The nng_log_set_facility function can be used to diff --git a/ref/api/sock.html b/ref/api/sock.html index 41168bb5..f36fcf64 100644 --- a/ref/api/sock.html +++ b/ref/api/sock.html @@ -256,6 +256,49 @@ The value stored in name is a fixed string located in program text, and or altered. It is guaranteed to remain valid while this library is present.

The nng_socket_raw function determines whether the socket is in raw mode or not, storing true in raw if it is, or false if it is not.

+

Polling Socket Events

+
int nng_socket_get_recv_poll_fd(nng_socket s, int *fdp);
+int nng_socket_get_send_poll_fd(nng_socket s, int *fdp);
+
+

Sometimes it is necessary to integrate a socket into a poll or select driven +event loop. (Or, on Linux, epoll, or on BSD derived systems like macOS kqueue).

+

For these occasions, a suitable file descriptor for polling is provided +by these two functions.

+

The nng_socket_get_recv_poll_fd function obtains a file descriptor +that will poll as readable when a message is ready for receiving for the socket.

+

The nng_socket_get_send_poll_fd function obtains a file descriptor +that will poll as readable when the socket can accept a message for sending.

+

These file descriptors should only be polled for readability, and no +other operation performed on them. The socket will read from, or write to, +these file descriptors to provide a level-signaled behavior automatically.

+

Additionally the socket will close these file descriptors when the socket itself is closed.

+

These functions replace the NNG_OPT_SENDFD and NNG_OPT_RECVFD socket options that +were available in previous versions of NNG.

+
+

+ + note +

+

These functions are not compatible with contexts.

+
+
+

+ + note +

+

The file descriptors supplied by these functions is not used for transporting message data. +The only valid use of these file descriptors is for polling for the ability to send or receive +messages on the socket.

+
+
+

+ + tip +

+

Using these functions will force the socket to perform extra system calls, and thus +have a negative impact on performance and latency. It is preferable to use asynchronous I/O +when possible.

+

Examples

Example 1: Initializing a Socket

nng_socket s = NNG_SOCKET_INITIALIZER;
diff --git a/ref/api/synch.html b/ref/api/synch.html
index 32b155c7..80e0732b 100644
--- a/ref/api/synch.html
+++ b/ref/api/synch.html
@@ -330,28 +330,28 @@ does not depend on which thread will be woken. When in doubt, nng
 
 
Examples

 
Example 1: Allocating the condition variable

-
	nng_mtx *m;
-	nng_cv *cv;
-	nng_mtx_alloc(&m); // error checks elided
-	nng_cv_alloc(&cv, m);
+
nng_mtx *m;
+nng_cv *cv;
+nng_mtx_alloc(&m); // error checks elided
+nng_cv_alloc(&cv, m);
 

 
Example 2: Waiting for the condition

-
    expire = nng_clock() + 1000; // 1 second in the future
-    nng_mtx_lock(m);  // assume cv was allocated using m
-    while (!condition_true) {
-        if (nng_cv_until(cv, expire) == NNG_ETIMEDOUT) {
-            printf("Time out reached!\n");
-            break;
-        }
-    }
-    // condition_true is true
-    nng_mtx_unlock(m);
+
expire = nng_clock() + 1000; // 1 second in the future
+nng_mtx_lock(m);  // assume cv was allocated using m
+while (!condition_true) {
+  if (nng_cv_until(cv, expire) == NNG_ETIMEDOUT) {
+    printf("Time out reached!\n");
+    break;
+  }
+}
+// condition_true is true
+nng_mtx_unlock(m);
 

 
Example 3: Signaling the condition

-
    nng_mtx_lock(m);
-    condition_true = true;
-    nng_cv_wake(cv);
-    nng_mtx_unlock(m);
+
nng_mtx_lock(m);
+condition_true = true;
+nng_cv_wake(cv);
+nng_mtx_unlock(m);
 

 
 
diff --git a/ref/indexing.html b/ref/indexing.html
index b58bcbe6..b83d43a2 100644
--- a/ref/indexing.html
+++ b/ref/indexing.html
@@ -176,6 +176,7 @@ condition variable, 1

 CPU-bound, 1

 duration, 1

 error message, 1

+event loop, 1

 flow control, 1

 getopt, 1

 half-duplex, 1

@@ -283,9 +284,7 @@ named pipes, 1

 NNG_OPT_REQ_RESENDTICK, 1

 NNG_OPT_REQ_RESENDTIME, 1

 NNG_OPT_SOCKET_FD, 1, 2

-NNG_OPT_SUB_PREFNEW, 1

-NNG_OPT_SUB_SUBSCRIBE, 1

-NNG_OPT_SUB_UNSUBSCRIBE, 1

+NNG_OPT_SUB_PREFNEW, 1

 NNG_OPT_SURVEYOR_SURVEYTIME, 1

 nng_opts_parse, 1

 nng_optspec, 1

@@ -293,6 +292,8 @@ named pipes, 1

 nng_random, 1

 nng_sleep_aio, 1

 nng_socket, 1

+nng_socket_get_recv_poll_fd, 1

+nng_socket_get_send_poll_fd, 1

 nng_socket_id, 1

 nng_socket_peer_id, 1

 nng_socket_peer_name, 1

@@ -370,7 +371,6 @@ socket, 1

 statistics, 1

 SUB, 1

 SUB protocol, 1

-subscribe, 1

 subscriber, 1

 survey pattern, 1, 2

 SURVEYOR, 1

diff --git a/ref/migrate/nng1.html b/ref/migrate/nng1.html
index 29562b2b..a50cb845 100644
--- a/ref/migrate/nng1.html
+++ b/ref/migrate/nng1.html
@@ -308,20 +308,27 @@ before bringing them into the socket itself.

 
Socket Options

 
The NNG_OPT_PROTO, NNG_OPT_PROTONAME, NNG_OPT_PEER, and NNG_OPT_PEERNAME options
 have been replaced by functions instead of options.
-Use nng_socket_proto_id, nng_socket_peer_id, nng_socket_proto_name, and nng_socket_peer_name instead.
+Use nng_socket_proto_id, nng_socket_peer_id, nng_socket_proto_name, and nng_socket_peer_name instead.
 Note that the new functions provide a reference to a static string, and thus do not require
 allocation, and the returned strings should not be freed. Also the IDs are provided as uint16_t,
 matching the actual wire protocol values, instead of int.

-
The NNG_OPT_RAW option has aso been replaced by a function, nng_socket_raw.

+
The NNG_OPT_RAW option has aso been replaced by a function, nng_socket_raw.

+
The NNG_OPT_SENDFD and NNG_OPT_RECVFD options have been replaced by
+nng_socket_get_send_poll_fd and nng_socket_get_recv_poll_fd respectively.

 
Subscriptions

 
The NNG_OPT_SUB_SUBSCRIBE and NNG_OPT_SUB_UNSUBCRIBE options have been replaced by
-the following functions: nng_sub0_socket_subscribe, nng_sub0_socket_unsubscribe,
-nng_sub0_ctx_subscribe and nng_sub0_ctx_unsubscribe. These functions, like the options
+the following functions: nng_sub0_socket_subscribe, nng_sub0_socket_unsubscribe,
+nng_sub0_ctx_subscribe and nng_sub0_ctx_unsubscribe. These functions, like the options
 they replace, are only applicable to SUB sockets.

 
Statistics Use Constified Pointers

-
A number of the statistics functions take, or return, const nng_stat * instead
+
A number of the statistics functions take, or return, const nng_stat * instead
 of plain nng_stat *. The ABI has not changed, but it may be necessary to declare
 certain methods variables const to avoid warnings about misuse of const.

+
+
+
+
+
 
                     
 
diff --git a/ref/print.html b/ref/print.html
index a8344191..7e930187 100644
--- a/ref/print.html
+++ b/ref/print.html
@@ -984,6 +984,49 @@ The value stored in name is a fixed string located in program text, and
 or altered. It is guaranteed to remain valid while this library is present.

 
The nng_socket_raw function determines whether the socket is in
 raw mode or not, storing true in raw if it is, or false if it is not.

+
Polling Socket Events

+
int nng_socket_get_recv_poll_fd(nng_socket s, int *fdp);
+int nng_socket_get_send_poll_fd(nng_socket s, int *fdp);
+

+
Sometimes it is necessary to integrate a socket into a poll or select driven
+event loop. (Or, on Linux, epoll, or on BSD derived systems like macOS kqueue).

+
For these occasions, a suitable file descriptor for polling is provided
+by these two functions.

+
The nng_socket_get_recv_poll_fd function obtains a file descriptor
+that will poll as readable when a message is ready for receiving for the socket.

+
The nng_socket_get_send_poll_fd function obtains a file descriptor
+that will poll as readable when the socket can accept a message for sending.

+
These file descriptors should only be polled for readability, and no
+other operation performed on them. The socket will read from, or write to,
+these file descriptors to provide a level-signaled behavior automatically.

+
Additionally the socket will close these file descriptors when the socket itself is closed.

+
These functions replace the NNG_OPT_SENDFD and NNG_OPT_RECVFD socket options that
+were available in previous versions of NNG.

+

+

+  
+  note
+

+
These functions are not compatible with contexts.

+

+

+

+  
+  note
+

+
The file descriptors supplied by these functions is not used for transporting message data.
+The only valid use of these file descriptors is for polling for the ability to send or receive
+messages on the socket.

+

+

+

+  
+  tip
+

+
Using these functions will force the socket to perform extra system calls, and thus
+have a negative impact on performance and latency. It is preferable to use asynchronous I/O
+when possible.

+

 
Examples

 
Example 1: Initializing a Socket

 
nng_socket s = NNG_SOCKET_INITIALIZER;
@@ -1914,28 +1957,28 @@ does not depend on which thread will be woken. When in doubt, nng
 
 
Examples

 
Example 1: Allocating the condition variable

-
	nng_mtx *m;
-	nng_cv *cv;
-	nng_mtx_alloc(&m); // error checks elided
-	nng_cv_alloc(&cv, m);
+
nng_mtx *m;
+nng_cv *cv;
+nng_mtx_alloc(&m); // error checks elided
+nng_cv_alloc(&cv, m);
 

 
Example 2: Waiting for the condition

-
    expire = nng_clock() + 1000; // 1 second in the future
-    nng_mtx_lock(m);  // assume cv was allocated using m
-    while (!condition_true) {
-        if (nng_cv_until(cv, expire) == NNG_ETIMEDOUT) {
-            printf("Time out reached!\n");
-            break;
-        }
-    }
-    // condition_true is true
-    nng_mtx_unlock(m);
+
expire = nng_clock() + 1000; // 1 second in the future
+nng_mtx_lock(m);  // assume cv was allocated using m
+while (!condition_true) {
+  if (nng_cv_until(cv, expire) == NNG_ETIMEDOUT) {
+    printf("Time out reached!\n");
+    break;
+  }
+}
+// condition_true is true
+nng_mtx_unlock(m);
 

 
Example 3: Signaling the condition

-
    nng_mtx_lock(m);
-    condition_true = true;
-    nng_cv_wake(cv);
-    nng_mtx_unlock(m);
+
nng_mtx_lock(m);
+condition_true = true;
+nng_cv_wake(cv);
+nng_mtx_unlock(m);
 

 
 
@@ -2225,12 +2268,12 @@ set by nng_log_set_level or the default
 if that function has not been called.

 
The log levels are defined as follows:

 
typedef enum nng_log_level {
-	NNG_LOG_NONE   = 0, // used for filters only, NNG suppresses these
-	NNG_LOG_ERR    = 3,
-	NNG_LOG_WARN   = 4,
-	NNG_LOG_NOTICE = 5,
-	NNG_LOG_INFO   = 6,
-	NNG_LOG_DEBUG  = 7
+    NNG_LOG_NONE   = 0, // used for filters only, NNG suppresses these
+    NNG_LOG_ERR    = 3,
+    NNG_LOG_WARN   = 4,
+    NNG_LOG_NOTICE = 5,
+    NNG_LOG_INFO   = 6,
+    NNG_LOG_DEBUG  = 7
 } nng_log_level;
 

 
The value NNG_LOG_NONE may be useful to suppress message logs altogether.

@@ -2247,17 +2290,17 @@ Traditionally these are used with the UNIX syslog system, and
 the values here represent some (but not all) of the values found there.

 
The following values are defined:

 
typedef enum nng_log_facility {
-	NNG_LOG_USER   = 1,
-	NNG_LOG_DAEMON = 3,
-	NNG_LOG_AUTH   = 10,
-	NNG_LOG_LOCAL0 = 16,
-	NNG_LOG_LOCAL1 = 17,
-	NNG_LOG_LOCAL2 = 18,
-	NNG_LOG_LOCAL3 = 19,
-	NNG_LOG_LOCAL4 = 20,
-	NNG_LOG_LOCAL5 = 21,
-	NNG_LOG_LOCAL6 = 22,
-	NNG_LOG_LOCAL7 = 23,
+    NNG_LOG_USER   = 1,
+    NNG_LOG_DAEMON = 3,
+    NNG_LOG_AUTH   = 10,
+    NNG_LOG_LOCAL0 = 16,
+    NNG_LOG_LOCAL1 = 17,
+    NNG_LOG_LOCAL2 = 18,
+    NNG_LOG_LOCAL3 = 19,
+    NNG_LOG_LOCAL4 = 20,
+    NNG_LOG_LOCAL5 = 21,
+    NNG_LOG_LOCAL6 = 22,
+    NNG_LOG_LOCAL7 = 23,
 } nng_log_facility;
 

 
The nng_log_set_facility function can be used to
@@ -4421,42 +4464,14 @@ Attempts to send messages will result in NNG_ENOTSUP.

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

 
Protocol Options

-
The following protocol-specific options are available.

+
The following protocol-specific option is available.

 
    
-
  • 
-
    NNG_OPT_SUB_SUBSCRIBE: 
    
-
    
-This option registers a topic that the subscriber is interested in.
-The option is write-only, and takes an array of bytes, of arbitrary size.
-Each incoming message is checked against the list of subscribed topics.
-If the body begins with the entire set of bytes in the topic, then the
-message is accepted. If no topic matches, then the message is
-discarded. 
    
-
    
-This option is a byte array. Thus if you use
-nng_socket_set_string the NUL terminator byte will
-be included in the topic.
-If that isn’t desired, consider using
-nng_socket_set and using strlen of the topic
-as the topic size. 
    
-
    
-To receive all messages, an empty topic (zero length) can be used.
    
-
    • 
-
  • 
-
    NNG_OPT_SUB_UNSUBSCRIBE: 
    
-
    
-This option, also read-only, removes a topic from the subscription list.
-Note that if the topic was not previously subscribed to with
-NNG_OPT_SUB_SUBSCRIBE then an NNG_ENOENT error will result.
    
-
    • 
-
  • 
-
    NNG_OPT_SUB_PREFNEW: 
    
+
  • 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.
    
-
    • 
+When false, the subscriber will reject messages if the message queue does not have room.
 

 
Protocol Headers

 
The SUB protocol has no protocol-specific headers.

@@ -5482,20 +5497,27 @@ before bringing them into the socket itself.

 
Socket Options

 
The NNG_OPT_PROTO, NNG_OPT_PROTONAME, NNG_OPT_PEER, and NNG_OPT_PEERNAME options
 have been replaced by functions instead of options.
-Use nng_socket_proto_id, nng_socket_peer_id, nng_socket_proto_name, and nng_socket_peer_name instead.
+Use nng_socket_proto_id, nng_socket_peer_id, nng_socket_proto_name, and nng_socket_peer_name instead.
 Note that the new functions provide a reference to a static string, and thus do not require
 allocation, and the returned strings should not be freed. Also the IDs are provided as uint16_t,
 matching the actual wire protocol values, instead of int.

-
The NNG_OPT_RAW option has aso been replaced by a function, nng_socket_raw.

+
The NNG_OPT_RAW option has aso been replaced by a function, nng_socket_raw.

+
The NNG_OPT_SENDFD and NNG_OPT_RECVFD options have been replaced by
+nng_socket_get_send_poll_fd and nng_socket_get_recv_poll_fd respectively.

 
Subscriptions

 
The NNG_OPT_SUB_SUBSCRIBE and NNG_OPT_SUB_UNSUBCRIBE options have been replaced by
-the following functions: nng_sub0_socket_subscribe, nng_sub0_socket_unsubscribe,
-nng_sub0_ctx_subscribe and nng_sub0_ctx_unsubscribe. These functions, like the options
+the following functions: nng_sub0_socket_subscribe, nng_sub0_socket_unsubscribe,
+nng_sub0_ctx_subscribe and nng_sub0_ctx_unsubscribe. These functions, like the options
 they replace, are only applicable to SUB sockets.

 
Statistics Use Constified Pointers

-
A number of the statistics functions take, or return, const nng_stat * instead
+
A number of the statistics functions take, or return, const nng_stat * instead
 of plain nng_stat *. The ABI has not changed, but it may be necessary to declare
 certain methods variables const to avoid warnings about misuse of const.

+
+
+
+
+