From ff00eac2401732e9efb6170ffb90100dcf6332a7 Mon Sep 17 00:00:00 2001 From: Garrett D'Amore Date: Tue, 23 Apr 2024 07:14:25 -0700 Subject: Move some supplemental APIs to reduce friction in using them. The supplemental/util/platform.h is kind of a pain, so we move move the prototypes for commonly used functions out of there, into nng.h proper. --- docs/man/nng_clock.3supp.adoc | 6 ++---- docs/man/nng_msleep.3supp.adoc | 3 +-- docs/man/nng_random.3supp.adoc | 5 +---- docs/man/nng_socket_pair.3supp.adoc | 5 ++--- include/nng/nng.h | 18 ++++++++++++++++++ include/nng/supplemental/util/options.h | 4 +++- include/nng/supplemental/util/platform.h | 22 +++------------------- 7 files changed, 30 insertions(+), 33 deletions(-) diff --git a/docs/man/nng_clock.3supp.adoc b/docs/man/nng_clock.3supp.adoc index d413f1b2..4c91c645 100644 --- a/docs/man/nng_clock.3supp.adoc +++ b/docs/man/nng_clock.3supp.adoc @@ -1,6 +1,6 @@ = nng_clock(3supp) // -// Copyright 2018 Staysail Systems, Inc. +// Copyright 2024 Staysail Systems, Inc. // Copyright 2018 Capitar IT Group BV // // This document is supplied under the terms of the MIT License, a @@ -18,7 +18,6 @@ nng_clock - get time [source, c] ---- #include -#include typedef uint64_t nng_time; @@ -37,8 +36,7 @@ very fine-grained values. IMPORTANT: The reference time will be the same for a given program, but different programs may have different references. -TIP: This function is intended mostly to help with setting appropriate -timeouts using xref:nng_cv_until.3supp.adoc[`nng_cv_until()`]. +TIP: This function should help with setting appropriate timeouts. == RETURN VALUES diff --git a/docs/man/nng_msleep.3supp.adoc b/docs/man/nng_msleep.3supp.adoc index 57d3615b..bef74587 100644 --- a/docs/man/nng_msleep.3supp.adoc +++ b/docs/man/nng_msleep.3supp.adoc @@ -1,6 +1,6 @@ = nng_msleep(3supp) // -// Copyright 2018 Staysail Systems, Inc. +// Copyright 2024 Staysail Systems, Inc. // Copyright 2018 Capitar IT Group BV // // This document is supplied under the terms of the MIT License, a @@ -18,7 +18,6 @@ nng_msleep - sleep milliseconds [source, c] ---- #include -#include void nng_msleep(nng_duration msec); ---- diff --git a/docs/man/nng_random.3supp.adoc b/docs/man/nng_random.3supp.adoc index 3f8ac39e..c2cd4bac 100644 --- a/docs/man/nng_random.3supp.adoc +++ b/docs/man/nng_random.3supp.adoc @@ -1,6 +1,6 @@ = nng_random(3supp) // -// Copyright 2018 Staysail Systems, Inc. +// Copyright 2024 Staysail Systems, Inc. // Copyright 2018 Capitar IT Group BV // // This document is supplied under the terms of the MIT License, a @@ -18,7 +18,6 @@ nng_random - get random number [source, c] ---- #include -#include uint32_t nng_random(void); ---- @@ -26,8 +25,6 @@ uint32_t nng_random(void); == DESCRIPTION The `nng_random()` returns a random number. -The value returned is suitable for use with cryptographic functions such as -key generation. The value is obtained using platform specific cryptographically strong random number facilities when available. diff --git a/docs/man/nng_socket_pair.3supp.adoc b/docs/man/nng_socket_pair.3supp.adoc index 68b4a943..7718e27b 100644 --- a/docs/man/nng_socket_pair.3supp.adoc +++ b/docs/man/nng_socket_pair.3supp.adoc @@ -1,6 +1,6 @@ = nng_socket_pair(3supp) // -// Copyright 2023 Staysail Systems, Inc. +// Copyright 2024 Staysail Systems, Inc. // // This document is supplied under the terms of the MIT License, a // copy of which should be located in the distribution where this @@ -17,7 +17,6 @@ nng_socket_pair - create a connected pair of BSD sockets [source, c] ---- #include -#include int nng_socket_pair(int fds[2]); ---- @@ -34,7 +33,7 @@ using the `AF_UNIX` family and the `SOCK_STREAM` socket type. NOTE: At present only POSIX platforms implementing `socketpair()` are supported with this function. TIP: This function may be useful for creating a shared connection between a parent process and -a child process on UNIX platforms, without requiring the processes use a shared filesystem or TCP connection. +a child process on UNIX platforms, without requiring a shared filesystem or TCP connection. == RETURN VALUES diff --git a/include/nng/nng.h b/include/nng/nng.h index 95aaed7a..9192cc5e 100644 --- a/include/nng/nng.h +++ b/include/nng/nng.h @@ -1567,6 +1567,24 @@ NNG_DECL void nng_log_debug(const char *msgid, const char *msg, ...); NNG_DECL void nng_log_auth( nng_log_level level, const char *msgid, const char *msg, ...); +// Return an absolute time from some arbitrary point. The value is +// provided in milliseconds, and is of limited resolution based on the +// system clock. (Do not use it for fine-grained performance measurements.) +NNG_DECL nng_time nng_clock(void); + +// Sleep for specified msecs. +NNG_DECL void nng_msleep(nng_duration); + +// nng_random returns a "strong" (cryptographic sense) random number. +NNG_DECL uint32_t nng_random(void); + +// nng_socket_pair is used to create a bound pair of file descriptors +// typically using the socketpair() call. The descriptors are backed +// by reliable, bidirectional, byte streams. This will return NNG_ENOTSUP +// if the platform lacks support for this. The argument is a pointer +// to an array of file descriptors (or HANDLES or similar). +NNG_DECL int nng_socket_pair(int[2]); + #ifdef __cplusplus } #endif diff --git a/include/nng/supplemental/util/options.h b/include/nng/supplemental/util/options.h index 83969a90..6d0a3c1a 100644 --- a/include/nng/supplemental/util/options.h +++ b/include/nng/supplemental/util/options.h @@ -1,5 +1,5 @@ // -// Copyright 2018 Staysail Systems, Inc. +// Copyright 2024 Staysail Systems, Inc. // Copyright 2018 Capitar IT Group BV // // This software is supplied under the terms of the MIT License, a @@ -13,6 +13,8 @@ #include +#include + #ifdef __cplusplus extern "C" { #endif diff --git a/include/nng/supplemental/util/platform.h b/include/nng/supplemental/util/platform.h index 26f910a3..70eee1b8 100644 --- a/include/nng/supplemental/util/platform.h +++ b/include/nng/supplemental/util/platform.h @@ -1,5 +1,5 @@ // -// Copyright 2023 Staysail Systems, Inc. +// Copyright 2024 Staysail Systems, Inc. // Copyright 2018 Capitar IT Group BV // // This software is supplied under the terms of the MIT License, a @@ -23,18 +23,12 @@ #include #include +#include + #ifdef __cplusplus extern "C" { #endif -// Return an absolute time from some arbitrary point. The value is -// provided in milliseconds, and is of limited resolution based on the -// system clock. (Do not use it for fine-grained performance measurements.) -NNG_DECL nng_time nng_clock(void); - -// Sleep for specified msecs. -NNG_DECL void nng_msleep(nng_duration); - // nng_thread is a handle to a "thread", which may be a real system // thread, or a coroutine on some platforms. typedef struct nng_thread nng_thread; @@ -97,16 +91,6 @@ NNG_DECL void nng_cv_wake(nng_cv *); // that no waiter starves forever. NNG_DECL void nng_cv_wake1(nng_cv *); -// nng_random returns a "strong" (cryptographic sense) random number. -NNG_DECL uint32_t nng_random(void); - -// nng_socket_pair is used to create a bound pair of file descriptors -// typically using the socketpair() call. The descriptors are backed -// by reliable, bidirectional, byte streams. This will return NNG_ENOTSUP -// if the platform lacks support for this. The argument is a pointer -// to an array of file descriptors (or HANDLES or similar). -NNG_DECL int nng_socket_pair(int [2]); - #ifdef __cplusplus } #endif -- cgit v1.2.3-70-g09d2