aboutsummaryrefslogtreecommitdiff
path: root/docs/ref/api/stat/nng_stats.md
diff options
context:
space:
mode:
Diffstat (limited to 'docs/ref/api/stat/nng_stats.md')
-rw-r--r--docs/ref/api/stat/nng_stats.md107
1 files changed, 0 insertions, 107 deletions
diff --git a/docs/ref/api/stat/nng_stats.md b/docs/ref/api/stat/nng_stats.md
deleted file mode 100644
index a932ca5d..00000000
--- a/docs/ref/api/stat/nng_stats.md
+++ /dev/null
@@ -1,107 +0,0 @@
-# nng_stats
-
-## NAME
-
-nng_stats --- statistics snapshot
-
-## SYNOPSIS
-
-```c
-#include <nng/nng.h>
-
-typedef struct nng_stat nng_stat;
-
-int nng_stats_get(nng_stat **statsp);
-void nng_stats_free(nng_stat *stats);
-nng_stat *nng_stat_next(nng_stat *stat);
-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);
-```
-
-## DESCRIPTION
-
-Statistics maintained by the system are organized in a tree, and
-a snapshot of all statistics can be taken, and then traversed
-and searched.
-
-### Statistics Snapshot Collection
-
-The {{i:`nng_stats_get`}} function attempts to obtain a snapshot of all the
-various diagnostic statistics that are present in the system.
-On success, a pointer to the statistics tree snapshot is returned in _statsp_.
-
-> [!NOTE]
-> The process of collecting statistics is designed to have minimal
-> impact on the system, but there is still some impact.
-
-The statistics are organized as a tree, rooted with a parent
-statistic of type `NNG_STAT_SCOPE` that carries no value, and which
-has an empty name.
-This parent statistic is returned through the _statsp_ pointer.
-
-When no longer needed, the statistics snapshot can be freed with the
-{{i:`nng_stats_free`}} function.
-
-> [!IMPORTANT]
-> The `nng_stats_free` function must be called only with the root statistic that is
-> returned through the _statsp_ pointer.
-
-> [!NOTE]
-> The values of individual statistics are guaranteed to be atomic,
-> but due the way statistics are collected there can be discrepancies between
-> them at certain times.
-> For example, statistics counting bytes and messages received may not
-> reflect the same number of messages, depending on when the snapshot is taken.
-> This potential inconsistency arises as a result of optimizations to minimize
-> the impact of statistics on actual operations.
-
-### Traversing the Statistics Tree
-
-Traversing the tree of statistics is done using the `nng_stat_child` and
-`nng_stat_next` functions.
-
-The `nng_stat_child` function returns either the first child of _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.
-
-### Finding a Statistic
-
-Sometimes it is easiest to search for a specific statistic, matching by name,
-or possibly to find the tree of statistics associated iwth a specific [socket][nng_socket],
-[dialer][nng_dialer], or [listener][nng_listener].
-
-The `nng_stat_find` functions are provided for this purpose.
-
-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` return
-the statistics subtree for the given dialer, listener, or socket object. Note that
-these functions should be provided the root of the statistic tree, in order to ensure
-that they can find the desired object.
-
-## RETURN VALUES
-
-The `nng_stats_get` function returns zero on success, or a non-zero error value on failure.
-
-Aside from `nng_stats_free`, which has no return, the remaining functions return a pointer to
-the desired statistic object, or `NULL` if such a statistic cannot be found.
-
-## ERRORS
-
-- `NNG_ENOMEM`: Insufficient free memory to collect statistics.
-- `NNG_ENOTSUP`: Statistics are not supported (compile time option).
-
-## SEE ALSO
-
-[nng_stat][nng_stat]
-
-[nng_stat]: ./nng_stat.md
-[nng_socket]: TODO.md
-[nng_dialer]: TODO.md
-[nng_listener]: TODO.md