From 3e3dd5ef9bec1db07bcb340691b58af9099446cd Mon Sep 17 00:00:00 2001 From: gdamore Date: Tue, 31 Dec 2024 17:51:33 +0000 Subject: deploy: c3bb282e916bf1ece77bf81901878498e39f0017 --- ref/api/index.html | 20 +++++-- ref/api/stats.html | 45 ++++++++------- ref/api/url.html | 22 ++++---- ref/indexing.html | 48 ++++++++-------- ref/migrate/nng1.html | 16 +++--- ref/print.html | 151 +++++++++++++++++++++++++++----------------------- ref/searchindex.js | 2 +- ref/searchindex.json | 2 +- 8 files changed, 168 insertions(+), 138 deletions(-) diff --git a/ref/api/index.html b/ref/api/index.html index c74ba0b6..db3f30c3 100644 --- a/ref/api/index.html +++ b/ref/api/index.html @@ -222,18 +222,28 @@

API Reference

This section is a reference guide for the NNG programming interfaces. -It is meant to serve as a refernce, rather than as a tutorial.

+It is meant to serve as a reference, rather than as a tutorial.

The material here is organized by major areas of functionality.

Note that unless indicated otherwise, consumers of these interfaces must include the nng/nng.h header file like so:

#include <nng/nng.h>
-

Chapters

+

Sections

diff --git a/ref/api/stats.html b/ref/api/stats.html index 9b1f56dc..83c8b4a3 100644 --- a/ref/api/stats.html +++ b/ref/api/stats.html @@ -272,6 +272,7 @@ through statsp using the function nng_stats_get.

Traversing the Tree

const nng_stat *nng_stat_child(const nng_stat *stat);
 const nng_stat *nng_stat_next(const nng_stat *stat);
+const nng_stat *nng_stat_parent(const nng_stat *stat);

Traversing the tree of statistics is done using the nng_stat_child and nng_stat_next functions.

@@ -279,6 +280,8 @@ const nng_stat *nng_stat_next(const nng_stat *stat); or NULL if the stat has no children.

The nng_stat_next function returns the nearest sibling to the right of stat, or NULL if stat has no more siblings to the right.

+

The nng_stat_parent function returns the parent of stat, or NULL if +stat is the root of the statistics tree.

Finding a Statistic

const nng_stat *nng_stat_find(const nng_stat *stat, const char *name);
 const nng_stat *nng_stat_find_dialer(const nng_stat *stat, nng_dialer dialer);
@@ -289,10 +292,10 @@ const nng_stat *nng_stat_find_socket(const nng_stat *stat, nng_dialer socket);
 or possibly to find the tree of statistics associated iwth a specific socket,
 dialer, or listener.

 
The nng_stat_find functions are provided for this purpose.

-
The nng_stat_find function returns the first statistic within the subtree of
+
The nng_stat_find function returns the first statistic within the subtree of
 statistics stat, with the given name. If no such statistic can be found, NULL
 is returned.

-
The nng_stat_find_dialer, nng_stat_find_listener, and nng_stat_find_socket
+
The nng_stat_find_dialer, nng_stat_find_listener, and nng_stat_find_socket
 return the statistics subtree for the given dialer, listener, or socket object. If no such
 statistic can be found, then they return NULL.
 These functions should be provided the root of the statistic tree, in order to ensure
@@ -301,23 +304,23 @@ that they can find the desired object.

 
const char *nng_stat_name(const nng_stat *stat);
 const char *nng_stat_desc(const nng_stat *stat);
 

-
Every statistic has a name, returned by nng_stat_name, and a description, returned by
-nng_stat_desc. Descriptions are human-readable text, which might be useful for display.

+
Every statistic has a name, returned by nng_stat_name, and a description, returned by
+nng_stat_desc. Descriptions are human-readable text, which might be useful for display.

 
Statistic Type

 
int nng_stat_type(const nng_stat *stat);
 

-
The function nng_stat_type returns the type of the statistic.
+
The function nng_stat_type returns the type of the statistic.
 The type of a statistic determines the nature of the value, and which
 function can be used to obtain that value.

 
    
 
  • 
-
    NNG_STAT_SCOPE: 
+
    NNG_STAT_SCOPE: 
 The statistic does not carry any real value, but is
 used for grouping related statistics together. This is a nexus in the
 statistics tree.
    
 
    • 
 
  • 
-
    NNG_STAT_COUNTER: 
+
    NNG_STAT_COUNTER: 
 The statistic is a counter that only increments.
 Usually the change in the value of the statistic is more interesting
 (as a rate) than the absolute value at any given time. The value should
@@ -325,7 +328,7 @@ be obtained using nng_stat_value
 The units will be given by the value returned from nng_stat_unit.
    
 
    • 
 
  • 
-
    NNG_STAT_LEVEL: 
+
    NNG_STAT_LEVEL: 
 The statistic represnts a measured value which corresponds
 to a specific value at a specific time. For example, this may represent the
 number of messages currently queued for some operation, or the link speed
@@ -335,19 +338,19 @@ than the change in the value over time. Again the value can be obtained with
 with nng_stat_unit.
    
 
    • 
 
  • 
-
    NNG_STAT_STRING: 
+
    NNG_STAT_STRING: 
 The statistic is a string, such as a name. The value
 of the string can be obtained with nng_stat_string.
 The value of this string
 will remain valid until the snapshot is deallocated with nng_stats_free.
    
 
    • 
 
  • 
-
    NNG_STAT_BOOLEAN: 
+
    NNG_STAT_BOOLEAN: 
 The value of the statistic is a truth value (either true
 or false) and can be obtained with nng_stat_bool.
    
 
    • 
 
  • 
-
    NNG_STAT_ID: 
+
    NNG_STAT_ID: 
 The value of the statistic is a numeric identifier, such as a socket
 identifier. The value can be obtained with nng_stat_value,
 and will be fixed for the life of the statistic.
    
@@ -359,12 +362,12 @@ const char *nng_stat_string(const nng_stat *stat);
 bool nng_stat_bool(const nng_stat *stat);

These functions return the value associated with the statistic.

-

The nng_stat_value function returns the the numeric value for the statistic stat +

The nng_stat_value function returns the the numeric value for the statistic stat of type NNG_STAT_COUNTER, NNG_STAT_LEVEL, or NNG_STAT_ID. If stat is not one of these types, then it returns zero.

-

The nng_stat_bool function returns the Boolean value (either true or false) for the statistic stat of +

The nng_stat_bool function returns the Boolean value (either true or false) for the statistic stat of type NNG_STAT_BOOLEAN. If the statistics is not of this type, then it returns false.

-

The nng_stat_string function returns a pointer to a string value for the statistic stat, +

The nng_stat_string function returns a pointer to a string value for the statistic stat, of type NNG_STAT_STRING. This string will remain valud until the snapshot that stat was collected with is deallocated with nng_stats_free. If the statistic is not of type NNG_STAT_STRING, then NULL is returned.

@@ -373,19 +376,19 @@ is not of type NNG_STAT_STRING, then NULL is returned.

For statistics of type NNG_STAT_COUNTER or NNG_STAT_LEVEL, it is often useful to know what that quantity being reported measures. -The following units may be returned from nng_stat_unit for such a statistic:

+The following units may be returned from nng_stat_unit for such a statistic:

Statistic Timestamp

uint64_t nng_stat_timestamp(const nng_stat *stat);

Statistics have a timestamp indicating when the value was sampled, -obtained via nng_stat_timestamp. The timestamp is given in +obtained via nng_stat_timestamp. The timestamp is given in in milliseconds since a reference time, and the reference time used here is the same reference time used for nng_clock.

See Also

diff --git a/ref/api/url.html b/ref/api/url.html index 9276c836..259ad350 100644 --- a/ref/api/url.html +++ b/ref/api/url.html @@ -228,20 +228,12 @@ and RFC 3968.

In Scalability Protocols, this concept is extended, although it includes schemes that are not part of the IETF standards.

URL Structure

-
typedef struct nng_url {
-    const char *u_scheme;
-    char       *u_userinfo;
-    char       *u_hostname;
-    uint16_t   u_port;
-    char       *u_path;
-    char       *u_query;
-    char       *u_fragment;
-} nng_url;
+
typedef struct nng_url nng_url;
 
 const char *nng_url_scheme(const nng_url *url);
 const char *nng_url_userinfo(const nng_url *url);
 const char *nng_url_hostname(const nng_url *url);
-uint16_t    nng_url_port(const nng_url *url);
+uint32_t    nng_url_port(const nng_url *url);
 const char *nng_url_path(const nng_url *url);
 const char *nng_url_query(const nng_url *url);
 const char *nng_url_fragment(const nng_url *url):
@@ -310,7 +302,7 @@ and creates a dynamically allocated nng_url, returning it in ur
 
Only nng_url_free should be used to deallocate nng_url objects.

 
 
Clone a URL

-
int nng_url_clone(nng_url **dup, nng_url *url);
+
int nng_url_clone(nng_url **dup, const nng_url *url);
 

 
The nng_url_clone function creates a copy of url, and returns it in dup.

 
Destroy a URL

@@ -319,6 +311,14 @@ and creates a dynamically allocated nng_url, returning it in ur
 
The nng_url_free function destroy an nng_url object created with
 either nng_url_parse or nng_url_free.

 
This is the only correct way to destroy an nng_url object.

+
Update a URL Port

+
void nng_url_resolve_port(nng_url *url, uint32_t port);
+

+
In order to use dynamic port allocation, some transports and schemes allow a port number of zero
+to be specified. When this is done, the system will allocate a free port when the port is bound
+while starting a listener. Once this is done, the port number may need to be updated so that the
+URL can be used to configure a client. The nng_url_resolve_port function updates such
+a URL with a new port. This will have no effect if the URL already has a non-zero port number.

 
See Also

 
More information about Universal Resource Locators can be found in
 RFC 3986.

diff --git a/ref/indexing.html b/ref/indexing.html
index e46a9482..d2881df8 100644
--- a/ref/indexing.html
+++ b/ref/indexing.html
@@ -303,26 +303,27 @@ named pipes, 1

 nng_socket_proto_name, 1

 nng_socket_raw, 1

 nng_stat, 1

-nng_stat_bool, 1

-NNG_STAT_BOOLEAN, 1

+nng_stat_bool, 1

+NNG_STAT_BOOLEAN, 1

 nng_stat_child, 1

-NNG_STAT_COUNTER, 1

-nng_stat_desc, 1

-nng_stat_find, 1

-nng_stat_find_dialer, 1

-nng_stat_find_listener, 1

-nng_stat_find_socket, 1

-NNG_STAT_ID, 1

-NNG_STAT_LEVEL, 1

-nng_stat_name, 1

+NNG_STAT_COUNTER, 1

+nng_stat_desc, 1

+nng_stat_find, 1

+nng_stat_find_dialer, 1

+nng_stat_find_listener, 1

+nng_stat_find_socket, 1

+NNG_STAT_ID, 1

+NNG_STAT_LEVEL, 1

+nng_stat_name, 1

 nng_stat_next, 1

-NNG_STAT_SCOPE, 1

-NNG_STAT_STRING, 1

-nng_stat_string, 1

-nng_stat_timestamp, 1

-nng_stat_type, 1

-nng_stat_unit, 1

-nng_stat_value, 1

+nng_stat_parent, 1

+NNG_STAT_SCOPE, 1

+NNG_STAT_STRING, 1

+nng_stat_string, 1

+nng_stat_timestamp, 1

+nng_stat_type, 1

+nng_stat_unit, 1

+nng_stat_value, 1

 nng_stats_free, 1

 nng_stats_get, 1

 nng_stderr_logger, 1

@@ -335,11 +336,11 @@ named pipes, 1

 nng_thread_destroy, 1

 nng_thread_set_name, 1

 nng_time, 1

-NNG_UNIT_BYTES, 1

-NNG_UNIT_EVENTS, 1

-NNG_UNIT_MESSAGES, 1

-NNG_UNIT_MILLIS, 1

-NNG_UNIT_NONE, 1

+NNG_UNIT_BYTES, 1

+NNG_UNIT_EVENTS, 1

+NNG_UNIT_MESSAGES, 1

+NNG_UNIT_MILLIS, 1

+NNG_UNIT_NONE, 1

 nng_url_clone, 1

 nng_url_fragment, 1

 nng_url_free, 1

@@ -348,6 +349,7 @@ named pipes, 1

 nng_url_path, 1

 nng_url_port, 1

 nng_url_query, 1

+nng_url_resolve_port, 1

 nng_url_scheme, 1

 nng_url_sprintf, 1

 nng_url_userinfo, 1

diff --git a/ref/migrate/nng1.html b/ref/migrate/nng1.html
index 2ada49ba..6257eb56 100644
--- a/ref/migrate/nng1.html
+++ b/ref/migrate/nng1.html
@@ -400,15 +400,15 @@ structure instead of a string.

 access of the structure is no longer permitted. Intead new
 accessors functions are provided:

 
    
-
  • u_scheme is replaced by [nng_url_scheme].
    • 
-
  • u_port is replaced by [nng_url_port], but this returns a uint16_t.
    • 
-
  • u_hostname is replaced by [nng_url_hostname].
    • 
-
  • u_path is replaced by [nng_url_path].
    • 
-
  • u_query is replaced by [nng_url_query].
    • 
-
  • u_fragment is replaced by [nng_url_fragment].
    • 
-
  • u_userinfo is replaced by [nng_url_userinfo].
    • 
+
  • u_scheme is replaced by nng_url_scheme.
    • 
+
  • u_port is replaced by nng_url_port, but this returns a uint16_t.
    • 
+
  • u_hostname is replaced by nng_url_hostname.
    • 
+
  • u_path is replaced by nng_url_path.
    • 
+
  • u_query is replaced by nng_url_query.
    • 
+
  • u_fragment is replaced by nng_url_fragment.
    • 
+
  • u_userinfo is replaced by nng_url_userinfo.
    • 
 
  • u_requri is removed - it can be easily formulated from the other fields.
    • 
-
  • u_host is removed - use [nng_url_hostname] and [nng_url_port] to construct if needed
    • 
+
  • u_host is removed - use nng_url_hostname and nng_url_port to construct if needed
    • 
 
  • u_rawurl is removed - a “cooked” URL can be obtained from the new nng_url_sprintf function.
    • 
 

 
HTTP API

diff --git a/ref/print.html b/ref/print.html
index 8e489c8f..093edebb 100644
--- a/ref/print.html
+++ b/ref/print.html
@@ -586,18 +586,28 @@ loss of revenue, or other undesirable conditions.

 
 
API Reference

 
This section is a reference guide for the NNG programming interfaces.
-It is meant to serve as a refernce, rather than as a tutorial.

+It is meant to serve as a reference, rather than as a tutorial.

 
The material here is organized by major areas of functionality.

 
Note that unless indicated otherwise, consumers of these interfaces must
 include the nng/nng.h header file like so:

 
#include <nng/nng.h>
 

-
Chapters

+
Sections