Use const for nng_stat when possible.

docs/migrating/nng1.md

@@ -48,3 +48,9 @@ options must be set on the endpoint (dialer or listener) using the appropriate
 `nng_dialer_set` or `nng_listener_set` option. This likely means that it is necessary
 to allocate and configure the endpoint before attaching it to the socket. This will
 also afford a much more fine-grained level of control over transport options.
+
+## Statistics Use Constified Pointers
+
+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`.

docs/ref/api/stats.md

@@ -54,8 +54,8 @@ The {{i:`nng_stats_free`}} function deallocates the snapshot referenced by _stat
 ## Traversing the Tree
 
 ```c
-nng_stat *nng_stat_child(nng_stat *stat);
-nng_stat *nng_stat_next(nng_stat *stat);
+const nng_stat *nng_stat_child(const nng_stat *stat);
+const nng_stat *nng_stat_next(const nng_stat *stat);
 ```
 
 Traversing the tree of statistics is done using the {{i:`nng_stat_child`}} and
@@ -70,10 +70,10 @@ or `NULL` if _stat_ has no more siblings to the right.
 ## Finding a Statistic
 
 ```c
-nng_stat *nng_stat_find(nng_stat *stat, const char *name);
-nng_stat *nng_stat_find_dialer(nng_stat *stat, nng_dialer dialer);
-nng_stat *nng_stat_find_listener(nng_stat *stat, nng_dialer listener);
-nng_stat *nng_stat_find_socket(nng_stat *stat, nng_dialer socket);
+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);
+const nng_stat *nng_stat_find_listener(const nng_stat *stat, nng_dialer listener);
+const nng_stat *nng_stat_find_socket(const nng_stat *stat, nng_dialer socket);
 ```
 
 Sometimes it is easiest to search for a specific statistic, matching by name,
@@ -95,8 +95,8 @@ that they can find the desired object.
 ## Statistic Identification
 
 ```c
-const char *nng_stat_name(nng_stat *stat);
-const char *nng_stat_desc(nng_stat *stat);
+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 {{i:`nng_stat_name`}}, and a description, returned by
@@ -105,7 +105,7 @@ Every statistic has a name, returned by {{i:`nng_stat_name`}}, and a description
 ## Statistic Type
 
 ```c
-int nng_stat_type(nng_stat *stat);
+int nng_stat_type(const nng_stat *stat);
 ```
 
 The function {{i:`nng_stat_type`}} returns the type of the statistic.
@@ -151,9 +151,9 @@ function can be used to obtain that value.
 ## Statistic Value
 
 ```c
-uint64_t nng_stat_value(nng_stat *stat);
-const char *nng_stat_string(nng_stat *stat);
-bool nng_stat_bool(nng_stat *stat);
+uint64_t nng_stat_value(const nng_stat *stat);
+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.
@@ -173,7 +173,7 @@ is not of type `NNG_STAT_STRING`, then `NULL` is returned.
 ## Statistic Units
 
 ```c
-int nng_stat_unit(nng_stat *stat);
+int nng_stat_unit(const nng_stat *stat);
 ```
 
 For statistics of type [`NNG_STAT_COUNTER`][NNG_STAT_COUNTER] or [`NNG_STAT_LEVEL`][NNG_STAT_LEVEL],
@@ -189,7 +189,7 @@ The following units may be returned from {{i:`nng_stat_unit`}} for such a statis
 ## Statistic Timestamp
 
 ```c
-uint64_t nng_stat_timestamp(nng_stat *stat);
+uint64_t nng_stat_timestamp(const nng_stat *stat);
 ```
 
 Statistics have a timestamp indicating when the value was sampled,

include/nng/nng.h

@@ -966,41 +966,42 @@ NNG_DECL void nng_stats_free(nng_stat *);
 
 // nng_stats_dump is a debugging function that dumps the entire set of
 // statistics to stdout.
-NNG_DECL void nng_stats_dump(nng_stat *);
+NNG_DECL void nng_stats_dump(const nng_stat *);
 
 // nng_stat_next finds the next sibling for the current stat.  If there
 // are no more siblings, it returns NULL.
-NNG_DECL nng_stat *nng_stat_next(nng_stat *);
+NNG_DECL const nng_stat *nng_stat_next(const nng_stat *);
 
 // nng_stat_child finds the first child of the current stat.  If no children
 // exist, then NULL is returned.
-NNG_DECL nng_stat *nng_stat_child(nng_stat *);
+NNG_DECL const nng_stat *nng_stat_child(const nng_stat *);
 
 // nng_stat_name is used to determine the name of the statistic.
 // This is a human-readable name.  Statistic names, as well as the presence
 // or absence or semantic of any particular statistic are not part of any
 // stable API, and may be changed without notice in future updates.
-NNG_DECL const char *nng_stat_name(nng_stat *);
+NNG_DECL const char *nng_stat_name(const nng_stat *);
 
 // nng_stat_type is used to determine the type of the statistic.
 // Counters generally increment, and therefore changes in the value over
 // time are likely more interesting than the actual level.  Level
 // values reflect some absolute state however, and should be presented to the
 // user as is.
-NNG_DECL int nng_stat_type(nng_stat *);
+NNG_DECL int nng_stat_type(const nng_stat *);
 
 // nng_stat_find is used to find a specific named statistic within
 // a statistic tree.  NULL is returned if no such statistic exists.
-NNG_DECL nng_stat *nng_stat_find(nng_stat *, const char *);
+NNG_DECL const nng_stat *nng_stat_find(const nng_stat *, const char *);
 
 // nng_stat_find_socket is used to find the stats for the given socket.
-NNG_DECL nng_stat *nng_stat_find_socket(nng_stat *, nng_socket);
+NNG_DECL const nng_stat *nng_stat_find_socket(const nng_stat *, nng_socket);
 
 // nng_stat_find_dialer is used to find the stats for the given dialer.
-NNG_DECL nng_stat *nng_stat_find_dialer(nng_stat *, nng_dialer);
+NNG_DECL const nng_stat *nng_stat_find_dialer(const nng_stat *, nng_dialer);
 
 // nng_stat_find_listener is used to find the stats for the given listener.
-NNG_DECL nng_stat *nng_stat_find_listener(nng_stat *, nng_listener);
+NNG_DECL const nng_stat *nng_stat_find_listener(
+    const nng_stat *, nng_listener);
 
 enum nng_stat_type_enum {
 	NNG_STAT_SCOPE   = 0, // Stat is for scoping, and carries no value
@@ -1014,7 +1015,7 @@ enum nng_stat_type_enum {
 // nng_stat_unit provides information about the unit for the statistic,
 // such as NNG_UNIT_BYTES or NNG_UNIT_BYTES.  If no specific unit is
 // applicable, such as a relative priority, then NN_UNIT_NONE is returned.
-NNG_DECL int nng_stat_unit(nng_stat *);
+NNG_DECL int nng_stat_unit(const nng_stat *);
 
 enum nng_unit_enum {
 	NNG_UNIT_NONE     = 0, // No special units
@@ -1027,24 +1028,24 @@ enum nng_unit_enum {
 // nng_stat_value returns the actual value of the statistic.
 // Statistic values reflect their value at the time that the corresponding
 // snapshot was updated, and are undefined until an update is performed.
-NNG_DECL uint64_t nng_stat_value(nng_stat *);
+NNG_DECL uint64_t nng_stat_value(const nng_stat *);
 
 // nng_stat_bool returns the boolean value of the statistic.
-NNG_DECL bool nng_stat_bool(nng_stat *);
+NNG_DECL bool nng_stat_bool(const nng_stat *);
 
 // nng_stat_string returns the string associated with a string statistic,
 // or NULL if the statistic is not part of the string.  The value returned
 // is valid until the associated statistic is freed.
-NNG_DECL const char *nng_stat_string(nng_stat *);
+NNG_DECL const char *nng_stat_string(const nng_stat *);
 
 // nng_stat_desc returns a human-readable description of the statistic.
 // This may be useful for display in diagnostic interfaces, etc.
-NNG_DECL const char *nng_stat_desc(nng_stat *);
+NNG_DECL const char *nng_stat_desc(const nng_stat *);
 
 // nng_stat_timestamp returns a timestamp (milliseconds) when the statistic
 // was captured.  The base offset is the same as used by nng_clock().
 // We don't use nng_time though, because that's in the supplemental header.
-NNG_DECL uint64_t nng_stat_timestamp(nng_stat *);
+NNG_DECL uint64_t nng_stat_timestamp(const nng_stat *);
 
 // Device functionality.  This connects two sockets together in a device,
 // which means that messages from one side are forwarded to the other.

src/core/list.h

@@ -1,5 +1,5 @@
 //
-// Copyright 2017 Garrett D'Amore <[email protected]>
+// Copyright 2024 Garrett D'Amore <[email protected]>
 //
 // This software is supplied under the terms of the MIT License, a
 // copy of which should be located in the distribution where this
@@ -58,7 +58,8 @@ extern int   nni_list_empty(nni_list *);
 extern int   nni_list_node_active(nni_list_node *);
 extern void  nni_list_node_remove(nni_list_node *);
 
-#define NNI_LIST_FOREACH(l, it) \
-	for (it = nni_list_first(l); it != NULL; it = nni_list_next(l, it))
+#define NNI_LIST_FOREACH(l, it)                  \
+	for (it = nni_list_first(l); it != NULL; \
+	     it = nni_list_next(l, (void *) it))
 
 #endif // CORE_LIST_H

src/core/stats.c

@@ -1,5 +1,5 @@
 //
-// Copyright 2022 Staysail Systems, Inc. <[email protected]>
+// Copyright 2024 Staysail Systems, Inc. <[email protected]>
 // Copyright 2018 Capitar IT Group BV <[email protected]>
 //
 // This software is supplied under the terms of the MIT License, a
@@ -396,28 +396,28 @@
 #endif
 }
 
-nng_stat *
-nng_stat_parent(nng_stat *stat)
+const nng_stat *
+nng_stat_parent(const nng_stat *stat)
 {
 	return (stat->s_parent);
 }
 
-nng_stat *
-nng_stat_next(nng_stat *stat)
+const nng_stat *
+nng_stat_next(const nng_stat *stat)
 {
 #if NNG_ENABLE_STATS
 	if (stat->s_parent == NULL) {
 		return (NULL); // Root node, no siblings.
 	}
-	return (nni_list_next(&stat->s_parent->s_children, stat));
+	return (nni_list_next(&stat->s_parent->s_children, (void *) stat));
 #else
 	NNI_ARG_UNUSED(stat);
 	return (NULL);
 #endif
 }
 
-nng_stat *
-nng_stat_child(nng_stat *stat)
+const nng_stat *
+nng_stat_child(const nng_stat *stat)
 {
 #if NNG_ENABLE_STATS
 	return (nni_list_first(&stat->s_children));
@@ -428,7 +428,7 @@
 }
 
 const char *
-nng_stat_name(nni_stat *stat)
+nng_stat_name(const nng_stat *stat)
 {
 #if NNG_ENABLE_STATS
 	return (stat->s_info->si_name);
@@ -439,7 +439,7 @@
 }
 
 uint64_t
-nng_stat_value(nni_stat *stat)
+nng_stat_value(const nng_stat *stat)
 {
 #if NNG_ENABLE_STATS
 	return (stat->s_val.sv_value);
@@ -450,7 +450,7 @@
 }
 
 bool
-nng_stat_bool(nni_stat *stat)
+nng_stat_bool(const nng_stat *stat)
 {
 #if NNG_ENABLE_STATS
 	return (stat->s_val.sv_bool);
@@ -461,7 +461,7 @@
 }
 
 const char *
-nng_stat_string(nng_stat *stat)
+nng_stat_string(const nng_stat *stat)
 {
 #if NNG_ENABLE_STATS
 	if (stat->s_info->si_type != NNG_STAT_STRING) {
@@ -475,7 +475,7 @@
 }
 
 uint64_t
-nng_stat_timestamp(nng_stat *stat)
+nng_stat_timestamp(const nng_stat *stat)
 {
 #if NNG_ENABLE_STATS
 	return ((uint64_t) stat->s_timestamp);
@@ -486,7 +486,7 @@
 }
 
 int
-nng_stat_type(nng_stat *stat)
+nng_stat_type(const nng_stat *stat)
 {
 #if NNG_ENABLE_STATS
 	return (stat->s_info->si_type);
@@ -497,7 +497,7 @@
 }
 
 int
-nng_stat_unit(nng_stat *stat)
+nng_stat_unit(const nng_stat *stat)
 {
 #if NNG_ENABLE_STATS
 	return (stat->s_info->si_unit);
@@ -508,7 +508,7 @@
 }
 
 const char *
-nng_stat_desc(nng_stat *stat)
+nng_stat_desc(const nng_stat *stat)
 {
 #if NNG_ENABLE_STATS
 	return (stat->s_info->si_desc);
@@ -518,19 +518,19 @@
 #endif
 }
 
-nng_stat *
-nng_stat_find(nng_stat *stat, const char *name)
+const nng_stat *
+nng_stat_find(const nng_stat *stat, const char *name)
 {
 #if NNG_ENABLE_STATS
-	nng_stat *child;
+	const nng_stat *child;
 	if (stat == NULL) {
 		return (NULL);
 	}
 	if (strcmp(name, stat->s_info->si_name) == 0) {
 		return (stat);
 	}
 	NNI_LIST_FOREACH (&stat->s_children, child) {
-		nng_stat *result;
+		const nng_stat *result;
 		if ((result = nng_stat_find(child, name)) != NULL) {
 			return (result);
 		}
@@ -542,8 +542,8 @@
 	return (NULL);
 }
 
-nng_stat *
-nng_stat_find_scope(nng_stat *stat, const char *name, int id)
+const nng_stat *
+nng_stat_find_scope(const nng_stat *stat, const char *name, int id)
 {
 #if NNG_ENABLE_STATS
 	nng_stat *child;
@@ -556,7 +556,7 @@
 		return (stat);
 	}
 	NNI_LIST_FOREACH (&stat->s_children, child) {
-		nng_stat *result;
+		const nng_stat *result;
 		if ((result = nng_stat_find_scope(child, name, id)) != NULL) {
 			return (result);
 		}
@@ -569,27 +569,27 @@
 	return (NULL);
 }
 
-nng_stat *
-nng_stat_find_socket(nng_stat *stat, nng_socket s)
+const nng_stat *
+nng_stat_find_socket(const nng_stat *stat, nng_socket s)
 {
 	return (nng_stat_find_scope(stat, "socket", nng_socket_id(s)));
 }
 
-nng_stat *
-nng_stat_find_dialer(nng_stat *stat, nng_dialer d)
+const nng_stat *
+nng_stat_find_dialer(const nng_stat *stat, nng_dialer d)
 {
 	return (nng_stat_find_scope(stat, "dialer", nng_dialer_id(d)));
 }
 
-nng_stat *
-nng_stat_find_listener(nng_stat *stat, nng_listener l)
+const nng_stat *
+nng_stat_find_listener(const nng_stat *stat, nng_listener l)
 {
 	return (nng_stat_find_scope(stat, "listener", nng_listener_id(l)));
 }
 
 #ifdef NNG_ENABLE_STATS
 void
-stat_sprint_scope(nni_stat *stat, char **scope, int *lenp)
+stat_sprint_scope(const nni_stat *stat, char **scope, int *lenp)
 {
 	if (stat->s_parent != NULL) {
 		stat_sprint_scope(stat->s_parent, scope, lenp);
@@ -606,7 +606,7 @@
 #endif
 
 void
-nng_stats_dump(nng_stat *stat)
+nng_stats_dump(const nng_stat *stat)
 {
 #ifdef NNG_ENABLE_STATS
 	static char        buf[128]; // to minimize recursion, not thread safe