From 77c40c3fc14913579b8983f2b383e5d731ab7316 Mon Sep 17 00:00:00 2001 From: Garrett D'Amore Date: Sat, 5 Oct 2024 18:26:50 -0700 Subject: [PATCH 001/222] msg: add sockaddr to message structure This is expected to be useful for new transports where we need the sock address to properly reply (think UDP with multicast). Signed-off-by: jaylin --- src/core/message.c | 25 +++++++++++++++++++------ src/core/message.h | 12 ++++++++++-- 2 files changed, 29 insertions(+), 8 deletions(-) diff --git a/src/core/message.c b/src/core/message.c index f9148f074..5c70b2290 100644 --- a/src/core/message.c +++ b/src/core/message.c @@ -29,15 +29,16 @@ struct nng_msg { size_t m_header_len; nni_chunk m_body; // equal to variable header + payload nni_proto_msg_ops *m_proto_ops; - void * m_proto_data; + void *m_proto_data; uint32_t m_pipe; // set on receive nni_atomic_int m_refcnt; + nng_sockaddr m_addr; // set on receive, transport use // FOR NANOMQ - size_t remaining_len; // TODO replace it with body len - uint8_t CMD_TYPE; - uint8_t * payload_ptr; // payload - nni_time times; // the time msg arrives - conn_param *cparam; // indicates where it originated + size_t remaining_len; // TODO replace it with body len + uint8_t CMD_TYPE; + uint8_t *payload_ptr; // payload + nni_time times; // the time msg arrives + conn_param *cparam; // indicates where it originated }; #if 0 @@ -683,6 +684,18 @@ nni_msg_get_pipe(const nni_msg *m) return (m->m_pipe); } +const nng_sockaddr * +nni_msg_address(const nni_msg *msg) +{ + return (&msg->m_addr); +} + +void +nni_msg_set_address(nng_msg *msg, const nng_sockaddr *addr) +{ + msg->m_addr = *addr; +} + // NAOMQ APIs uint8_t * diff --git a/src/core/message.h b/src/core/message.h index ab91e91ba..9b95eea66 100644 --- a/src/core/message.h +++ b/src/core/message.h @@ -23,9 +23,9 @@ extern int nni_msg_realloc(nni_msg *, size_t); extern int nni_msg_reserve(nni_msg *, size_t); extern size_t nni_msg_capacity(nni_msg *); extern int nni_msg_dup(nni_msg **, const nni_msg *); -extern void * nni_msg_header(nni_msg *); +extern void *nni_msg_header(nni_msg *); extern size_t nni_msg_header_len(const nni_msg *); -extern void * nni_msg_body(nni_msg *); +extern void *nni_msg_body(nni_msg *); extern size_t nni_msg_len(const nni_msg *); extern int nni_msg_append(nni_msg *, const void *, size_t); extern int nni_msg_insert(nni_msg *, const void *, size_t); @@ -58,6 +58,14 @@ extern void nni_msg_clone(nni_msg *); extern nni_msg *nni_msg_unique(nni_msg *); extern bool nni_msg_shared(nni_msg *); +// Socket address access. Principally useful for transports like UDP, +// which may need to remember or add the socket address later. +// SP transports will generally not support upper layers setting the +// address on send, but will take the information from the pipe. +// It may be set on receive, depending upon the transport. +extern const nng_sockaddr *nni_msg_address(const nni_msg *); +extern void nni_msg_set_address(nng_msg *, const nng_sockaddr *); + // nni_msg_pull_up ensures that the message is unique, and that any // header present is "pulled up" into the message body. If the function // cannot do this for any reason (out of space in the body), then NULL From 76bb3e85bd440799084e3b9062d7f14decf96221 Mon Sep 17 00:00:00 2001 From: Garrett D'Amore Date: Sat, 5 Oct 2024 18:34:36 -0700 Subject: [PATCH 002/222] fixes #168 UDP transport This is the initial implementation of UDP transport. It does in order guarantees (and consequently filters duplicates), but it does not guarantee delivery. The protocol limits payloads to 65000 bytes (minus headers for SP), but you really want to keep it to much less -- probably best for short messages that within a single MTU to avoid IP fragmentation and reassembly. This is unicast only for now (although there are plans for some support for multicast and broadcast as well as being able to perform automatic mesh building, but that will be in following work. Additional tunables are coming. This is only lightly tested at this point, and should be considered experimental. Its also undocumented. --- src/sp/transport/udp/CMakeLists.txt | 15 + src/sp/transport/udp/udp.c | 1853 ++++++++++++++++++++++++++ src/sp/transport/udp/udp_tran_test.c | 171 +++ 3 files changed, 2039 insertions(+) create mode 100644 src/sp/transport/udp/CMakeLists.txt create mode 100644 src/sp/transport/udp/udp.c create mode 100644 src/sp/transport/udp/udp_tran_test.c diff --git a/src/sp/transport/udp/CMakeLists.txt b/src/sp/transport/udp/CMakeLists.txt new file mode 100644 index 000000000..b08cd8613 --- /dev/null +++ b/src/sp/transport/udp/CMakeLists.txt @@ -0,0 +1,15 @@ +# +# Copyright 2024 Staysail Systems, Inc. +# +# This software is supplied under the terms of the MIT License, a +# copy of which should be located in the distribution where this +# file was obtained (LICENSE.txt). A copy of the license may also be +# found online at https://opensource.org/licenses/MIT. +# + +# UDP transport +nng_directory(udp) + +nng_sources_if(NNG_TRANSPORT_UDP udp.c) +nng_defines_if(NNG_TRANSPORT_UDP NNG_TRANSPORT_UDP) +nng_test_if(NNG_TRANSPORT_UDP udp_tran_test) diff --git a/src/sp/transport/udp/udp.c b/src/sp/transport/udp/udp.c new file mode 100644 index 000000000..4555c7493 --- /dev/null +++ b/src/sp/transport/udp/udp.c @@ -0,0 +1,1853 @@ +// Copyright 2024 Staysail Systems, Inc. +// +// This software is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +#include "core/aio.h" +#include "core/defs.h" +#include "core/idhash.h" +#include "core/nng_impl.h" +#include "core/options.h" +#include "core/platform.h" +#include "nng/nng.h" + +#include +#include +#include + +// Experimental UDP transport. Unicast only. +typedef struct udp_pipe udp_pipe; +typedef struct udp_ep udp_ep; + +// These should reallyh be renamed for the project. +#define nni_udp_open nni_plat_udp_open +#define nni_udp_close nni_plat_udp_close +#define nni_udp_send nni_plat_udp_send +#define nni_udp_recv nni_plat_udp_recv +#define nni_udp nni_plat_udp +#define nni_udp_sockname nni_plat_udp_sockname + +// OP code, 8 bits +enum udp_opcode { + OPCODE_DATA = 0, + OPCODE_CREQ = 1, + OPCODE_CACK = 2, + OPCODE_DISC = 3, + OPCODE_MESH = 4, +}; + +// Disconnect reason, must be 16 bits +typedef enum udp_disc_reason { + DISC_CLOSED = 0, // normal close + DISC_TYPE = 1, // bad SP type + DISC_NOTCONN = 2, // no such connection + DISC_REFUSED = 3, // refused by policy + DISC_MSGSIZE = 4, // message too large + DISC_NEGO = 5, // neogtiation failed + DISC_INACTIVE = 6, // closed due to inactivity + DISC_PROTO = 7, // other protocol error + DISC_NOBUF = 8, // resources exhausted +} udp_disc_reason; + +#ifndef NNG_UDP_TXQUEUE_LEN +#define NNG_UDP_TXQUEUE_LEN 32 +#endif + +#ifndef NNG_UDP_RXQUEUE_LEN +#define NNG_UDP_RXQUEUE_LEN 16 +#endif + +#ifndef NNG_UDP_RECVMAX +#define NNG_UDP_RECVMAX 65000 // largest permitted by spec +#endif + +#ifndef NNG_UDP_REFRESH +#define NNG_UDP_REFRESH (5 * NNI_SECOND) +#endif + +#ifndef NNG_UDP_CONNRETRY +#define NNG_UDP_CONNRETRY (NNI_SECOND / 5) +#endif + +#define UDP_EP_ROLE(ep) ((ep)->dialer ? "dialer " : "listener") + +// NB: Each of the following messages is exactly 20 bytes in size + +typedef struct udp_sp_data { + uint8_t us_ver; + uint8_t us_op_code; + uint16_t us_type; + uint32_t us_sender_id; + uint32_t us_peer_id; + uint32_t us_sequence; + uint16_t us_length; + uint16_t us_reserved; // depends on message type +} udp_sp_data; + +typedef struct udp_sp_creq { + uint8_t us_ver; + uint8_t us_op_code; + uint16_t us_type; + uint32_t us_sender_id; + uint32_t us_peer_id; + uint32_t us_sequence; + uint16_t us_recv_max; // actually max payload size + uint8_t us_reserved; + uint8_t us_refresh; +} udp_sp_creq; + +typedef struct udp_sp_disc { + uint8_t us_ver; + uint8_t us_op_code; + uint16_t us_type; + uint32_t us_sender_id; + uint32_t us_peer_id; + uint32_t us_sequence; + uint16_t us_reason; // depends on message type + uint16_t us_reserved; +} udp_sp_disc; + +typedef struct udp_sp_mesh { + uint8_t us_ver; + uint8_t us_op_code; + uint16_t us_type; + uint32_t us_sender_id; + uint32_t us_reserved1; + uint32_t us_sequence; + uint32_t us_reserved2; +} udp_sp_mesh; + +// ack is the same format as request +typedef struct udp_sp_creq udp_sp_cack; + +typedef union udp_sp_msg { + udp_sp_data data; + udp_sp_creq creq; + udp_sp_cack cack; + udp_sp_disc disc; + udp_sp_mesh mesh; +} udp_sp_msg; + +// Like a NIC driver, this is a "descriptor" for UDP TX packets. +// This allows us to create a circular ring of these to support +// queueing for TX gracefully. +typedef struct udp_txdesc { + udp_sp_msg header; // UDP transport message headers + nni_msg *payload; // may be null, only for data messages + nng_sockaddr sa; + bool submitted; // true if submitted +} udp_txdesc; + +typedef struct udp_txring { + udp_txdesc *descs; + uint16_t head; + uint16_t tail; + uint16_t count; + uint16_t size; +} udp_txring; + +#define UDP_TXRING_SZ 128 + +// UDP pipe resend (CREQ) in msec (nng_duration) +#define UDP_PIPE_REFRESH(p) ((p)->refresh) + +// UDP pipe timeout in msec (nng_duration) +#define UDP_PIPE_TIMEOUT(p) ((p)->refresh * 5) + +struct udp_pipe { + udp_ep *ep; + nni_pipe *npipe; + nng_sockaddr peer_addr; + uint16_t peer; + uint16_t proto; + uint32_t self_id; + uint32_t peer_id; + uint32_t self_seq; + uint32_t peer_seq; + uint16_t sndmax; // peer's max recv size + uint16_t rcvmax; // max recv size + bool closed; + bool dialer; + nng_duration refresh; // seconds, for the protocol + nng_time next_wake; + nng_time next_creq; + nng_time expire; + nni_list_node node; + nni_lmq rx_mq; + nni_list rx_aios; +}; + +struct udp_ep { + nni_udp *udp; + nni_mtx mtx; + uint16_t proto; + uint16_t af; // address family + bool fini; + bool started; + bool closed; + bool cooldown; + nng_url *url; + const char *host; // for dialers + int refcnt; // active pipes + nni_aio *useraio; + nni_aio *connaio; + nni_aio timeaio; + nni_aio resaio; + bool dialer; + bool tx_busy; // true if tx pending + nni_msg *rx_payload; // current receive message + nng_sockaddr rx_sa; // addr for last message + nni_aio tx_aio; // aio for TX handling + nni_aio rx_aio; // aio for RX handling + nni_id_map pipes; // pipes (indexed by id) + nni_sockaddr self_sa; // our address + nni_sockaddr peer_sa; // peer address, only for dialer; + nni_sockaddr mesh_sa; // mesh source address (ours) + nni_list connaios; // aios from accept waiting for a client peer + nni_list connpipes; // pipes waiting to be connected + nng_duration refresh; // refresh interval for connections in seconds + udp_sp_msg rx_msg; // contains the received message header + uint16_t rcvmax; // max payload, trimmed to uint16_t + uint16_t short_msg; + udp_txring tx_ring; + nni_time next_wake; + nni_aio_completions complq; + +#ifdef NNG_ENABLE_STATS + nni_stat_item st_rcv_max; +#endif +}; + +static void udp_ep_hold(udp_ep *ep); +static void udp_ep_rele(udp_ep *ep); +static void udp_ep_fini(void *); +static void udp_ep_start(udp_ep *); +static void udp_pipe_fini(void *); +static void udp_resolv_cb(void *); +static void udp_rx_cb(void *); + +static int +udp_pipe_alloc(udp_pipe **pp, udp_ep *ep, uint32_t peer_id, nng_sockaddr *sa) +{ + udp_pipe *p; + int rv; + nni_time now; + if ((p = NNI_ALLOC_STRUCT(p)) == NULL) { + return (NNG_ENOMEM); + } + if ((rv = nni_id_alloc32(&ep->pipes, &p->self_id, p)) != 0) { + NNI_FREE_STRUCT(p); + return (rv); + } + now = nni_clock(); + nni_aio_list_init(&p->rx_aios); + p->ep = ep; + p->dialer = ep->dialer; + p->self_seq = nni_random(); + p->peer_id = peer_id; + p->proto = ep->proto; + p->peer_addr = *sa; + p->refresh = p->dialer ? NNG_UDP_CONNRETRY : ep->refresh; + p->next_wake = now + UDP_PIPE_REFRESH(p); + p->expire = now + (p->dialer ? (5 * NNI_SECOND) : UDP_PIPE_TIMEOUT(p)); + p->rcvmax = ep->rcvmax; + *pp = p; + nni_lmq_init(&p->rx_mq, NNG_UDP_RXQUEUE_LEN); + udp_ep_hold(ep); + return (0); +} + +static void udp_recv_data( + udp_ep *ep, udp_sp_data *dreq, size_t len, nng_sockaddr *sa); +static void udp_send_disc_full(udp_ep *ep, nng_sockaddr *sa, uint32_t local_id, + uint32_t remote_id, uint32_t seq, udp_disc_reason reason); +static void udp_send_disc(udp_ep *ep, udp_pipe *p, udp_disc_reason reason); + +static void udp_ep_match(udp_ep *ep); + +static void +udp_tran_init(void) +{ +} + +static void +udp_tran_fini(void) +{ +} + +static void +udp_pipe_close(void *arg) +{ + udp_pipe *p = arg; + udp_ep *ep = p->ep; + nni_aio *aio; + + nni_mtx_lock(&ep->mtx); + udp_send_disc(ep, p, DISC_CLOSED); + while ((aio = nni_list_first(&p->rx_aios)) != NULL) { + nni_aio_list_remove(aio); + nni_aio_finish_error(aio, NNG_ECLOSED); + } + nni_mtx_unlock(&ep->mtx); +} + +static void +udp_pipe_stop(void *arg) +{ + udp_pipe_close(arg); +} + +static int +udp_pipe_init(void *arg, nni_pipe *npipe) +{ + udp_pipe *p = arg; + p->npipe = npipe; + + return (0); +} + +static void +udp_pipe_destroy(udp_pipe *p) +{ + nng_msg *m; + + // call with ep->mtx lock held + while (!nni_lmq_empty(&p->rx_mq)) { + nni_lmq_get(&p->rx_mq, &m); + nni_msg_free(m); + } + NNI_ASSERT(nni_list_empty(&p->rx_aios)); + + NNI_FREE_STRUCT(p); +} + +static void +udp_pipe_fini(void *arg) +{ + udp_pipe *p = arg; + udp_ep *ep = p->ep; + + nni_mtx_lock(&ep->mtx); + nni_id_remove(&ep->pipes, p->self_id); + + udp_pipe_destroy(p); + udp_ep_rele(ep); // releases lock +} + +// Find the pipe matching the given id (our pipe id, taken from the peer_id +// of the header) and peer's sockaddr. Returns NULL if not found. The +// ep lock must be held. If a pending pipe (not yet connected) is found, then +// it is returned instead. +static udp_pipe * +udp_find_pipe(udp_ep *ep, uint32_t self_id, uint32_t peer_id) +{ + udp_pipe *p; + if (((p = nni_id_get(&ep->pipes, self_id)) != NULL) && (!p->closed)) { + if (p->peer_id == 0 || p->peer_id == peer_id) { + return (p); + } + } + return (NULL); +} + +static bool +udp_check_pipe_sequence(udp_pipe *p, uint32_t seq) +{ + int32_t delta; + // signed math so we can see how far apart they are + delta = (int32_t) (seq - p->peer_seq); + if (delta < 0) { + // out of order delivery + return (false); + } + // TODO: bump a stat for misses if delta > 0. + p->peer_seq = seq + 1; // expected next sequence number + return (true); +} + +static void +udp_pipe_schedule(udp_pipe *p) +{ + udp_ep *ep = p->ep; + bool changed = false; + if (p->expire < ep->next_wake) { + ep->next_wake = p->expire; + changed = true; + } + if (p->next_wake < ep->next_wake) { + ep->next_wake = p->next_wake; + changed = true; + } + if (changed) { + nni_aio_abort(&ep->timeaio, NNG_EINTR); + } +} + +static void +udp_start_rx(udp_ep *ep) +{ + nni_iov iov[2]; + + iov[0].iov_buf = &ep->rx_msg; + iov[0].iov_len = sizeof(ep->rx_msg); + iov[1].iov_buf = nni_msg_body(ep->rx_payload); + iov[1].iov_len = nni_msg_len(ep->rx_payload); + nni_aio_set_input(&ep->rx_aio, 0, &ep->rx_sa); + nni_aio_set_iov(&ep->rx_aio, 2, iov); + nni_udp_recv(ep->udp, &ep->rx_aio); +} + +static void +udp_start_tx(udp_ep *ep) +{ + udp_txring *ring = &ep->tx_ring; + udp_txdesc *desc; + nng_msg *msg; + + if ((!ring->count) || (!ep->started) || ep->tx_busy) { + return; + } + ep->tx_busy = true; + + // NB: This does not advance the tail yet. + // The tail will be advanced when the operation is complete. + desc = &ring->descs[ring->tail]; + nni_iov iov[3]; + int niov = 0; + + NNI_ASSERT(desc->submitted); + iov[0].iov_buf = &desc->header; + iov[0].iov_len = sizeof(desc->header); + niov++; + + if ((msg = desc->payload) != NULL) { + if (nni_msg_header_len(msg) > 0) { + iov[niov].iov_buf = nni_msg_header(msg); + iov[niov].iov_len = nni_msg_header_len(msg); + niov++; + } + if (nni_msg_len(msg) > 0) { + iov[niov].iov_buf = nni_msg_body(msg); + iov[niov].iov_len = nni_msg_len(msg); + niov++; + } + } + nni_aio_set_input(&ep->tx_aio, 0, &desc->sa); + nni_aio_set_iov(&ep->tx_aio, niov, iov); + // it should *never* take this long, but allow for ARP resolution + nni_aio_set_timeout(&ep->tx_aio, NNI_SECOND * 10); + nni_udp_send(ep->udp, &ep->tx_aio); +} + +static void +udp_queue_tx(udp_ep *ep, nng_sockaddr *sa, udp_sp_msg *msg, nni_msg *payload) +{ + udp_txring *ring = &ep->tx_ring; + udp_txdesc *desc = &ring->descs[ring->head]; + + if (ring->count == ring->size || !ep->started) { + // ring is full + // TODO: bump a stat + if (payload != NULL) { + nni_msg_free(payload); + } + return; + } +#ifdef NNG_LITTLE_ENDIAN + // This covers modern GCC, clang, Visual Studio. + desc->header = *msg; +#else + // Fix the endianness, so other routines don't have to. + // It turns out that the endianness of the fields of CREQ + // is compatible with the fields of every other message type. + // We only have to do this for systems that are not known + // (at compile time) to be little endian. + desc->header.creq.us_ver = 0x1; + desc->header.creq.us_op_code = msg->creq.us_op_code; + NNI_PUT16LE(&desc->header.creq.us_type, msg->creq.us_type); + NNI_PUT32LE(&desc->header.creq.us_sended_id, msg->creq.us_sender_id); + NNI_PUT32LE(&desc->header.creq.us_peer_id, msg->creq.us_peer_id); + NNI_PUT32LE(&desc->header.creq.us_sequence, msg->creq.us_sequence); + NNI_PUT16LE(&desc->header.creq.us_recv_max, msg->creq.us_recv_max); + desc->header.creq.us_reserved = 0; + desc->header.creq.us_refresh = msg->creq.us_refresh; +#endif + + desc->payload = payload; + desc->sa = *sa; + desc->submitted = true; + ring->count++; + ring->head++; + if (ring->head == ring->size) { + ring->head = 0; + } + udp_start_tx(ep); +} + +static void +udp_finish_tx(udp_ep *ep) +{ + udp_txring *ring = &ep->tx_ring; + udp_txdesc *desc; + + NNI_ASSERT(ring->count > 0); + desc = &ring->descs[ring->tail]; + NNI_ASSERT(desc->submitted); + if (desc->payload != NULL) { + nni_msg_free(desc->payload); + desc->payload = NULL; + } + desc->submitted = false; + ring->tail++; + ring->count--; + if (ring->tail == ring->size) { + ring->tail = 0; + } + ep->tx_busy = false; + + // possibly start another tx going + udp_start_tx(ep); +} + +static void +udp_send_disc(udp_ep *ep, udp_pipe *p, udp_disc_reason reason) +{ + nni_aio *aio; + if (p->closed) { + return; + } + p->closed = true; + while ((aio = nni_list_first(&p->rx_aios)) != NULL) { + nni_aio_list_remove(aio); + nni_aio_finish_error(aio, NNG_ECLOSED); + } + udp_send_disc_full( + ep, &p->peer_addr, p->self_id, p->peer_id, p->self_seq++, reason); +} + +static void +udp_send_disc_full(udp_ep *ep, nng_sockaddr *sa, uint32_t local_id, + uint32_t remote_id, uint32_t seq, udp_disc_reason reason) +{ + udp_sp_disc disc; + + disc.us_ver = 0x1; + disc.us_op_code = OPCODE_DISC; + disc.us_type = ep->proto; + disc.us_sender_id = local_id; + disc.us_peer_id = remote_id; + disc.us_sequence = seq; + disc.us_reason = (uint16_t) reason; + udp_queue_tx(ep, sa, (void *) &disc, NULL); +} + +static void +udp_send_creq(udp_ep *ep, udp_pipe *p) +{ + udp_sp_creq creq; + creq.us_ver = 0x1; + creq.us_op_code = OPCODE_CREQ; + creq.us_type = p->proto; + creq.us_sender_id = p->self_id; + creq.us_peer_id = p->peer_id; + creq.us_sequence = p->self_seq++; + creq.us_recv_max = p->rcvmax; + creq.us_refresh = (p->refresh + NNI_SECOND - 1) / NNI_SECOND; + p->next_creq = nni_clock() + UDP_PIPE_REFRESH(p); + p->next_wake = p->next_creq; + + udp_pipe_schedule(p); + udp_queue_tx(ep, &p->peer_addr, (void *) &creq, NULL); +} + +static void +udp_send_cack(udp_ep *ep, udp_pipe *p) +{ + udp_sp_cack cack; + cack.us_ver = 0x01; + cack.us_op_code = OPCODE_CACK; + cack.us_type = p->proto; + cack.us_sender_id = p->self_id; + cack.us_peer_id = p->peer_id; + cack.us_sequence = p->self_seq++; + cack.us_recv_max = p->rcvmax; + cack.us_refresh = (p->refresh + NNI_SECOND - 1) / NNI_SECOND; + udp_queue_tx(ep, &p->peer_addr, (void *) &cack, NULL); +} + +static void +udp_recv_disc(udp_ep *ep, udp_sp_disc *disc, nng_sockaddr *sa) +{ + udp_pipe *p; + nni_aio *aio; + NNI_ARG_UNUSED(sa); + + p = udp_find_pipe(ep, disc->us_peer_id, disc->us_sender_id); + if (p != NULL) { + // For now we aren't validating the sequence numbers. + // This allows for an out of order DISC to cause the + // connection to be dropped, but it should self heal. + p->closed = true; + p->self_id = 0; // prevent it from being identified later + while ((aio = nni_list_first(&p->rx_aios)) != NULL) { + nni_aio_list_remove(aio); + nni_aio_finish_error(aio, NNG_ECLOSED); + } + } +} + +// Receive data for the pipe. Returns true if we used +// the message, false otherwise. +static void +udp_recv_data(udp_ep *ep, udp_sp_data *dreq, size_t len, nng_sockaddr *sa) +{ + // NB: ep mtx is locked + udp_pipe *p; + nni_aio *aio; + nni_msg *msg; + nni_time now; + + // send_id is the remote peer's ID + // peer_id is our ID (receiver ID) + // sequence number is our sender's sequence + uint32_t send_id = dreq->us_sender_id; + uint32_t peer_id = dreq->us_peer_id; + + // NB: Peer ID endianness does not matter, as long we use it + // consistently. + if ((p = udp_find_pipe(ep, peer_id, send_id)) == NULL) { + // TODO: Bump a stat... + udp_send_disc_full(ep, sa, send_id, peer_id, 0, DISC_NOTCONN); + // Question: how do we store the sockaddr for that? + return; + } + if (p->peer_id == 0) { + // connection isn't formed yet ... send another CREQ + udp_send_creq(ep, p); + return; + } + + now = nni_clock(); + + // Make sure the message wasn't truncated, and that it fits within + // our maximum agreed upon payload. + if ((dreq->us_length > len) || (dreq->us_length > p->rcvmax)) { + udp_send_disc(ep, p, DISC_MSGSIZE); + return; + } + + p->expire = now + UDP_PIPE_TIMEOUT(p); + p->next_wake = now + UDP_PIPE_REFRESH(p); + + udp_pipe_schedule(p); + + // trim the message down to its + nni_msg_chop( + ep->rx_payload, nni_msg_len(ep->rx_payload) - dreq->us_length); + + if (!udp_check_pipe_sequence(p, dreq->us_sequence)) { + // out of order delivery, drop it + // TODO: bump a stat + return; + } + + if (nni_lmq_full(&p->rx_mq)) { + // bump a NOBUF stat + return; + } + + // Short message, just alloc and copy + if (len <= ep->short_msg) { + if (nng_msg_alloc(&msg, len) != 0) { + // TODO: bump a stat + return; + } + nni_msg_set_address(msg, sa); + nni_msg_clear(msg); + nni_msg_append(msg, nni_msg_body(ep->rx_payload), len); + nni_lmq_put(&p->rx_mq, msg); + } else { + // Message size larger than copy break, do zero copy + msg = ep->rx_payload; + if (nng_msg_alloc(&ep->rx_payload, + ep->rcvmax + sizeof(ep->rx_msg)) != 0) { + // TODO: bump a stat + ep->rx_payload = msg; // make sure we put it back + return; + } + + if (len > nng_msg_len(msg)) { + // chop off any unfilled tail + nng_msg_chop(msg, nng_msg_len(msg) - len); + } + nni_msg_set_address(msg, sa); + nni_lmq_put(&p->rx_mq, msg); + } + + while (((aio = nni_list_first(&p->rx_aios)) != NULL) && + (!nni_lmq_empty(&p->rx_mq))) { + nni_aio_list_remove(aio); + nni_lmq_get(&p->rx_mq, &msg); + nni_aio_set_msg(aio, msg); + nni_aio_completions_add( + &ep->complq, aio, 0, nni_aio_count(aio)); + } +} + +static void +udp_recv_creq(udp_ep *ep, udp_sp_creq *creq, nng_sockaddr *sa) +{ + udp_pipe *p; + nni_time now; + + now = nni_clock(); + if (ep->dialer) { + // dialers do not accept CREQ requests + udp_send_disc_full(ep, sa, creq->us_peer_id, + creq->us_sender_id, 0, DISC_REFUSED); + return; + } + if ((p = udp_find_pipe(ep, creq->us_peer_id, creq->us_sender_id))) { + if ((p->peer_id == 0) || (p->peer != creq->us_type)) { + // we don't expect this -- a connection request from a + // peer while we have an oustanding request of our own. + // We *could* compare the sockaddrs to see if they + // match and if so then treat this as just a dueling + // connection. but for now we just discard it -- we'll + // wait for the CACK. + return; + } + + // so we know who it is from.. this is a refresh. + if (creq->us_refresh == 0) { + udp_send_disc(ep, p, DISC_NEGO); + return; + } + if ((creq->us_refresh * NNI_SECOND) < p->refresh) { + p->refresh = creq->us_refresh * NNI_SECOND; + } + p->next_wake = now + UDP_PIPE_REFRESH(p); + p->expire = now + UDP_PIPE_TIMEOUT(p); + + udp_pipe_schedule(p); + udp_send_cack(ep, p); + return; + } + + // new pipe + if (ep->fini || ep->closed) { + // endpoint is closing down, reject it. + udp_send_disc_full( + ep, sa, 0, creq->us_sender_id, 0, DISC_REFUSED); + return; + } + if (creq->us_refresh == 0) { + udp_send_disc_full( + ep, sa, 0, creq->us_sender_id, 0, DISC_NEGO); + return; + } + + if (udp_pipe_alloc(&p, ep, creq->us_peer_id, sa) != 0) { + udp_send_disc_full( + ep, sa, 0, creq->us_sender_id, 0, DISC_NOBUF); + return; + } + p->refresh = ep->refresh; + if ((creq->us_refresh * NNI_SECOND) < p->refresh) { + p->refresh = (creq->us_refresh * NNI_SECOND); + } + p->peer = creq->us_type; + p->peer_id = creq->us_sender_id; + p->peer_seq = creq->us_sequence + 1; + p->sndmax = creq->us_recv_max; + p->next_wake = now + UDP_PIPE_REFRESH(p); + p->expire = now + UDP_PIPE_TIMEOUT(p); + + udp_pipe_schedule(p); + nni_list_append(&ep->connpipes, p); + udp_send_cack(ep, p); + udp_ep_match(ep); +} + +static void +udp_recv_cack(udp_ep *ep, udp_sp_creq *cack, nng_sockaddr *sa) +{ + udp_pipe *p; + bool first; + nni_time now; + + if ((p = udp_find_pipe(ep, cack->us_peer_id, cack->us_sender_id)) && + (!p->closed)) { + if ((p->peer_id != 0) && (p->peer != cack->us_type)) { + udp_send_disc(ep, p, DISC_TYPE); + return; + } + + first = (p->peer_id == 0); + + // so we know who it is from.. this is a refresh. + p->sndmax = cack->us_recv_max; + p->peer = cack->us_type; + p->peer_id = cack->us_sender_id; + + if (cack->us_refresh == 0) { + udp_send_disc(ep, p, DISC_NEGO); + return; + } + if (first) { + p->refresh = ep->refresh; + p->peer_seq = cack->us_sequence + 1; + } + if ((cack->us_refresh * NNI_SECOND) < p->refresh) { + p->refresh = cack->us_refresh * NNI_SECOND; + } + now = nni_clock(); + p->next_wake = now + UDP_PIPE_REFRESH(p); + p->expire = now + UDP_PIPE_TIMEOUT(p); + udp_pipe_schedule(p); + + if (first) { + nni_list_append(&ep->connpipes, p); + udp_ep_match(ep); + } + return; + } + + // a CACK without a corresponding CREQ (or timed out pipe already) + udp_send_disc_full( + ep, sa, cack->us_peer_id, cack->us_sender_id, 0, DISC_NOTCONN); +} + +static void +udp_tx_cb(void *arg) +{ + udp_ep *ep = arg; + + nni_mtx_lock(&ep->mtx); + udp_finish_tx(ep); + nni_mtx_unlock(&ep->mtx); +} + +// In the case of unicast UDP, we don't know +// whether the message arrived from a connected peer as part of a +// logical connection, or is a message related to connection management. +static void +udp_rx_cb(void *arg) +{ + udp_ep *ep = arg; + nni_aio *aio = &ep->rx_aio; + int rv; + size_t n; + udp_sp_msg *hdr; + nng_sockaddr *sa; + nni_aio_completions complq; + + // for a received packet we are either receiving it for a + // connection we already have established, or for a new connection. + // Dialers cannot receive connection requests (as a safety + // precaution). + + nni_mtx_lock(&ep->mtx); + if ((rv = nni_aio_result(aio)) != 0) { + // something bad happened on RX... which is unexpected. + // sleep a little bit and hope for recovery. + switch (nni_aio_result(aio)) { + case NNG_ECLOSED: + case NNG_ECANCELED: + nni_mtx_unlock(&ep->mtx); + return; + case NNG_ETIMEDOUT: + case NNG_EAGAIN: + case NNG_EINTR: + ep->cooldown = false; + goto finish; + break; + default: + ep->cooldown = true; + nni_sleep_aio(5, aio); + nni_mtx_unlock(&ep->mtx); + return; + } + } + if (ep->cooldown) { + ep->cooldown = false; + goto finish; + } + + // Received message will be in the ep rx header. + hdr = &ep->rx_msg; + sa = &ep->rx_sa; + n = nng_aio_count(aio); + + if ((n >= sizeof(*hdr)) && (hdr->data.us_ver == 1)) { + n -= sizeof(*hdr); + +#ifndef NNG_LITTLE_ENDIAN + // Fix the endianness, so other routines don't have to. + // It turns out that the endianness of the fields of CREQ + // is compatible with the fields of every other message type. + // We only have to do this for systems that are not known + // (at compile time) to be little endian. + hdr->data.us_type = NNI_GET16LE(&hdr->data.us_type); + hdr->data.us_sender_id = NNI_GET32LE(&hdr->data.us_sender_id); + hdr->data.us_peeer_id = NNI_GET32LE(&hdr->data.us_peer_id); + hdr->data.us_sequence = NNI_GET32LE(&hdr->data.us_sequence); + hdr->data.us_length = NNI_GET16LE(&hdr->data.us_length); +#endif + + // TODO: verify that incoming type matches us! + + switch (hdr->data.us_op_code) { + case OPCODE_DATA: + udp_recv_data(ep, &hdr->data, n, sa); + break; + case OPCODE_CREQ: + udp_recv_creq(ep, &hdr->creq, sa); + break; + case OPCODE_CACK: + udp_recv_cack(ep, &hdr->cack, sa); + break; + case OPCODE_DISC: + udp_recv_disc(ep, &hdr->disc, sa); + break; + case OPCODE_MESH: // TODO: + // udp_recv_mesh(ep, &hdr->mesh, sa); + // break; + default: + udp_send_disc_full( + ep, sa, 0, hdr->data.us_sender_id, 0, DISC_PROTO); + break; + } + } + +finish: + // start another receive + udp_start_rx(ep); + + // grab the list of completions so we can finish them. + complq = ep->complq; + nni_aio_completions_init(&ep->complq); + nni_mtx_unlock(&ep->mtx); + + // now run the completions -- synchronously + nni_aio_completions_run(&complq); +} + +static void +udp_pipe_send(void *arg, nni_aio *aio) +{ + udp_pipe *p = arg; + udp_ep *ep; + udp_sp_data dreq; + nng_msg *msg; + + if (nni_aio_begin(aio) != 0) { + // No way to give the message back to the protocol, + // so we just discard it silently to prevent it from leaking. + nni_msg_free(nni_aio_get_msg(aio)); + nni_aio_set_msg(aio, NULL); + return; + } + + msg = nni_aio_get_msg(aio); + ep = p->ep; + + nni_mtx_lock(&ep->mtx); + if ((nni_msg_len(msg) + nni_msg_header_len(msg)) > p->sndmax) { + nni_mtx_unlock(&ep->mtx); + // rather failing this with an error, we just drop it on the + // floor. this is on the sender, so there isn't a compelling + // need to disconnect the pipe, since it we're not being + // "ill-behaved" to our peer. + // TODO: bump a stat + nni_msg_free(msg); + return; + } + + dreq.us_ver = 1; + dreq.us_type = ep->proto; + dreq.us_op_code = OPCODE_DATA; + dreq.us_sender_id = p->self_id; + dreq.us_peer_id = p->peer_id; + dreq.us_sequence = p->self_seq++; + dreq.us_length = + msg != NULL ? nni_msg_len(msg) + nni_msg_header_len(msg) : 0; + + // Just queue it, or fail it. + udp_queue_tx(ep, &p->peer_addr, (void *) &dreq, msg); + nni_mtx_unlock(&ep->mtx); + nni_aio_finish(aio, 0, dreq.us_length); +} + +static void +udp_pipe_recv_cancel(nni_aio *aio, void *arg, int rv) +{ + udp_pipe *p = arg; + udp_ep *ep = p->ep; + + nni_mtx_lock(&ep->mtx); + if (!nni_aio_list_active(aio)) { + nni_mtx_unlock(&ep->mtx); + return; + } + nni_aio_list_remove(aio); + nni_mtx_unlock(&ep->mtx); + nni_aio_finish_error(aio, rv); +} + +static void +udp_pipe_recv(void *arg, nni_aio *aio) +{ + udp_pipe *p = arg; + udp_ep *ep = p->ep; + int rv; + + if (nni_aio_begin(aio) != 0) { + return; + } + nni_mtx_lock(&ep->mtx); + if (p->closed) { + nni_mtx_unlock(&ep->mtx); + nni_aio_finish_error(aio, NNG_ECLOSED); + return; + } + if ((rv = nni_aio_schedule(aio, udp_pipe_recv_cancel, p)) != 0) { + nni_mtx_unlock(&ep->mtx); + nni_aio_finish_error(aio, rv); + return; + } + + nni_list_append(&p->rx_aios, aio); + nni_mtx_unlock(&ep->mtx); +} + +static uint16_t +udp_pipe_peer(void *arg) +{ + udp_pipe *p = arg; + + return (p->peer); +} + +static int +udp_pipe_get_recvmax(void *arg, void *v, size_t *szp, nni_type t) +{ + udp_pipe *p = arg; + udp_ep *ep = p->ep; + int rv; + nni_mtx_lock(&ep->mtx); + rv = nni_copyout_size(p->rcvmax, v, szp, t); + nni_mtx_unlock(&ep->mtx); + return (rv); +} + +static int +udp_pipe_get_remaddr(void *arg, void *v, size_t *szp, nni_type t) +{ + udp_pipe *p = arg; + udp_ep *ep = p->ep; + int rv; + nni_mtx_lock(&ep->mtx); + rv = nni_copyout_sockaddr(&p->peer_addr, v, szp, t); + nni_mtx_unlock(&ep->mtx); + return (rv); +} + +static nni_option udp_pipe_options[] = { + { + .o_name = NNG_OPT_RECVMAXSZ, + .o_get = udp_pipe_get_recvmax, + }, + { + .o_name = NNG_OPT_REMADDR, + .o_get = udp_pipe_get_remaddr, + }, + { + .o_name = NULL, + }, +}; + +static int +udp_pipe_getopt( + void *arg, const char *name, void *buf, size_t *szp, nni_type t) +{ + udp_pipe *p = arg; + int rv; + + rv = nni_getopt(udp_pipe_options, name, p, buf, szp, t); + return (rv); +} + +// udp_ep_hold simply bumps the reference count. +// This needs to be done with the lock for the EP held. +static void +udp_ep_hold(udp_ep *ep) +{ + ep->refcnt++; +} + +// udp_ep_rele drops the reference count on the endpoint. +// If the endpoint drops to zero, the EP is freed. It also +// unlocks the mutex, which must be held when calling this. +static void +udp_ep_rele(udp_ep *ep) +{ + nni_aio *aio; + NNI_ASSERT(ep->refcnt > 0); + ep->refcnt--; + if (!ep->fini || ep->refcnt > 0) { + nni_mtx_unlock(&ep->mtx); + return; + } + while ((aio = nni_list_first(&ep->connaios)) != NULL) { + nni_aio_list_remove(aio); + nni_aio_finish_error(aio, NNG_ECLOSED); + } + nni_mtx_unlock(&ep->mtx); + + nni_aio_close(&ep->timeaio); + nni_aio_close(&ep->resaio); + nni_aio_close(&ep->tx_aio); + nni_aio_close(&ep->rx_aio); + if (ep->udp != NULL) { + nni_udp_close(ep->udp); + } + nni_aio_fini(&ep->timeaio); + nni_aio_fini(&ep->resaio); + nni_aio_fini(&ep->tx_aio); + nni_aio_fini(&ep->rx_aio); + nni_id_map_fini(&ep->pipes); + NNI_FREE_STRUCTS(ep->tx_ring.descs, ep->tx_ring.size); + NNI_FREE_STRUCT(ep); +} + +static void +udp_ep_fini(void *arg) +{ + udp_ep *ep = arg; + + // We optionally linger a little bit (up to a half second) + // so that the disconnect messages can get pushed out. On + // most systems this should only take a single millisecond. + nni_time linger = + nni_clock() + NNI_SECOND / 2; // half second to drain, max + nni_mtx_lock(&ep->mtx); + ep->fini = true; + while ((ep->tx_ring.count > 0) && (nni_clock() < linger)) { + NNI_ASSERT(ep->refcnt > 0); + nni_mtx_unlock(&ep->mtx); + nng_msleep(1); + nni_mtx_lock(&ep->mtx); + } + if (ep->tx_ring.count > 0) { + nng_log_warn("NNG-UDP-LINGER", + "Lingering timed out on endpoint close, peer " + "notifications dropped"); + } + udp_ep_rele(ep); // drops the lock +} + +static void +udp_ep_close(void *arg) +{ + udp_ep *ep = arg; + udp_pipe *p; + nni_aio *aio; + + nni_mtx_lock(&ep->mtx); + while ((aio = nni_list_first(&ep->connaios)) != NULL) { + nni_aio_list_remove(aio); + nni_aio_finish_error(aio, NNG_ECONNABORTED); + } + + // close all pipes + uint32_t cursor = 0; + while (nni_id_visit(&ep->pipes, NULL, (void **) &p, &cursor)) { + p->closed = true; + if (p->peer_id != 0) { + udp_send_disc(ep, p, DISC_CLOSED); + } + while ((aio = nni_list_first(&p->rx_aios)) != NULL) { + nni_aio_list_remove(aio); + nni_aio_finish_error(aio, NNG_ECLOSED); + } + if (p->npipe == NULL) { + nni_list_remove(&ep->connpipes, p); + nni_id_remove(&ep->pipes, p->self_id); + udp_pipe_destroy(p); + ep->refcnt--; + } + } + nni_aio_close(&ep->resaio); + nni_mtx_unlock(&ep->mtx); +} + +// timer handler - sends out additional creqs as needed, +// reaps stale connections, and handles linger. +static void +udp_timer_cb(void *arg) +{ + udp_ep *ep = arg; + udp_pipe *p; + int rv; + + nni_mtx_lock(&ep->mtx); + rv = nni_aio_result(&ep->timeaio); + if ((rv == NNG_ECLOSED) || (rv == NNG_ECANCELED) || ep->closed) { + nni_mtx_unlock(&ep->mtx); + return; + } + + uint32_t cursor = 0; + nni_time now = nni_clock(); + nng_duration refresh = ep->refresh; + + ep->next_wake = NNI_TIME_NEVER; + while (nni_id_visit(&ep->pipes, NULL, (void **) &p, &cursor)) { + + if (p->closed) { + if (p->npipe == NULL) { + // pipe closed, but we have to clean it up + // ourselves + nni_id_remove(&ep->pipes, p->self_id); + udp_pipe_destroy(p); + ep->refcnt--; + } + continue; + } + + if (now > p->expire) { + char buf[128]; + nni_aio *aio; + nng_log_info("NNG-UDP-INACTIVE", + "Pipe peer %s timed out due to inactivity", + nng_str_sockaddr(&p->peer_addr, buf, sizeof(buf))); + if ((ep->dialer) && (p->peer_id == 0) && + (aio = nni_list_first(&ep->connaios))) { + nni_aio_list_remove(aio); + nni_aio_finish_error(aio, NNG_ETIMEDOUT); + } + // This will probably not be received by the peer, + // since we aren't getting anything from them. But + // having it on the wire may help debugging later. + udp_send_disc(ep, p, DISC_INACTIVE); + continue; + } + + if (p->dialer && now > p->next_creq) { + udp_send_creq(ep, p); + } + if (p->next_wake < ep->next_wake) { + ep->next_wake = p->next_wake; + } + } + refresh = ep->next_wake == NNI_TIME_NEVER + ? NNG_DURATION_INFINITE + : (nng_duration) (ep->next_wake - now); + nni_sleep_aio(refresh, &ep->timeaio); + + nni_mtx_unlock(&ep->mtx); +} + +static int +udp_ep_init(udp_ep **epp, nng_url *url, nni_sock *sock) +{ + udp_ep *ep; + int rv; + + if ((ep = NNI_ALLOC_STRUCT(ep)) == NULL) { + return (NNG_ENOMEM); + } + + ep->tx_ring.descs = + NNI_ALLOC_STRUCTS(ep->tx_ring.descs, NNG_UDP_TXQUEUE_LEN); + if (ep->tx_ring.descs == NULL) { + NNI_FREE_STRUCT(ep); + return (NNG_ENOMEM); + } + ep->tx_ring.size = NNG_UDP_TXQUEUE_LEN; + + if (strcmp(url->u_scheme, "udp") == 0) { + ep->af = NNG_AF_UNSPEC; + } else if (strcmp(url->u_scheme, "udp4") == 0) { + ep->af = NNG_AF_INET; + } else if (strcmp(url->u_scheme, "udp6") == 0) { + ep->af = NNG_AF_INET6; + } else { + NNI_FREE_STRUCT(ep); + return (NNG_EADDRINVAL); + } + + ep->self_sa.s_family = ep->af; + ep->proto = nni_sock_proto_id(sock); + ep->url = url; + ep->refresh = NNG_UDP_REFRESH; // one minute by default + ep->rcvmax = NNG_UDP_RECVMAX; + ep->refcnt = 1; + if ((rv = nni_msg_alloc(&ep->rx_payload, + ep->rcvmax + sizeof(ep->rx_msg)) != 0)) { + NNI_FREE_STRUCTS(ep->tx_ring.descs, NNG_UDP_TXQUEUE_LEN); + NNI_FREE_STRUCT(ep); + return (rv); + } + + nni_mtx_init(&ep->mtx); + nni_id_map_init(&ep->pipes, 1, 0xFFFFFFFF, true); + NNI_LIST_INIT(&ep->connpipes, udp_pipe, node); + nni_aio_list_init(&ep->connaios); + + nni_aio_init(&ep->rx_aio, udp_rx_cb, ep); + nni_aio_init(&ep->tx_aio, udp_tx_cb, ep); + nni_aio_init(&ep->timeaio, udp_timer_cb, ep); + nni_aio_init(&ep->resaio, udp_resolv_cb, ep); + nni_aio_completions_init(&ep->complq); + +#ifdef NNG_ENABLE_STATS + static const nni_stat_info rcv_max_info = { + .si_name = "rcv_max", + .si_desc = "maximum receive size", + .si_type = NNG_STAT_LEVEL, + .si_unit = NNG_UNIT_BYTES, + .si_atomic = true, + }; + nni_stat_init(&ep->st_rcv_max, &rcv_max_info); +#endif + + // schedule our timer callback - forever for now + // adjusted automatically as we add pipes or other + // actions which require earlier wakeup. + nni_sleep_aio(NNG_DURATION_INFINITE, &ep->timeaio); + + *epp = ep; + return (0); +} + +static int +udp_check_url(nng_url *url, bool listen) +{ + // Check for invalid URL components. + if ((strlen(url->u_path) != 0) && (strcmp(url->u_path, "/") != 0)) { + return (NNG_EADDRINVAL); + } + if ((url->u_fragment != NULL) || (url->u_userinfo != NULL) || + (url->u_query != NULL)) { + return (NNG_EADDRINVAL); + } + if (!listen) { + if ((strlen(url->u_hostname) == 0) || + (strlen(url->u_port) == 0) || (atoi(url->u_port) == 0)) { + return (NNG_EADDRINVAL); + } + } + return (0); +} + +static int +udp_dialer_init(void **dp, nng_url *url, nni_dialer *ndialer) +{ + udp_ep *ep; + int rv; + nni_sock *sock = nni_dialer_sock(ndialer); + + if ((rv = udp_check_url(url, false)) != 0) { + return (rv); + } + + if ((rv = udp_ep_init(&ep, url, sock)) != 0) { + return (rv); + } + +#ifdef NNG_ENABLE_STATS + nni_dialer_add_stat(ndialer, &ep->st_rcv_max); +#endif + *dp = ep; + return (0); +} + +static int +udp_listener_init(void **lp, nng_url *url, nni_listener *nlistener) +{ + udp_ep *ep; + int rv; + nni_sock *sock = nni_listener_sock(nlistener); + + // Check for invalid URL components. + if ((rv = udp_check_url(url, true)) != 0) { + return (rv); + } + + if ((rv = udp_ep_init(&ep, url, sock)) != 0) { + return (rv); + } + + if ((rv = nni_url_to_address(&ep->self_sa, url)) != 0) { + return (rv); + } + +#ifdef NNG_ENABLE_STATS + nni_listener_add_stat(nlistener, &ep->st_rcv_max); +#endif + + *lp = ep; + return (0); +} + +static void +udp_ep_cancel(nni_aio *aio, void *arg, int rv) +{ + udp_ep *ep = arg; + nni_mtx_lock(&ep->mtx); + if (nni_aio_list_active(aio)) { + nni_aio_list_remove(aio); + nni_aio_finish_error(aio, rv); + nni_aio_abort(&ep->resaio, rv); + } + nni_mtx_unlock(&ep->mtx); +} + +static void +udp_resolv_cb(void *arg) +{ + udp_ep *ep = arg; + udp_pipe *p; + nni_aio *aio; + int rv; + nni_mtx_lock(&ep->mtx); + if ((aio = nni_list_first(&ep->connaios)) == NULL) { + nni_mtx_unlock(&ep->mtx); + return; + } + if (ep->closed) { + nni_aio_list_remove(aio); + nni_mtx_unlock(&ep->mtx); + nni_aio_finish_error(aio, NNG_ECLOSED); + return; + } + if ((rv = nni_aio_result(&ep->resaio)) != 0) { + nni_aio_list_remove(aio); + nni_mtx_unlock(&ep->mtx); + nng_log_warn("NNG-UDP-RESOLV", + "Failed resolving IP address: %s", nng_strerror(rv)); + nni_aio_finish_error(aio, rv); + return; + } + + // Choose the right port to bind to. The family must match. + if (ep->self_sa.s_family == NNG_AF_UNSPEC) { + ep->self_sa.s_family = ep->peer_sa.s_family; + } + + if (ep->udp == NULL) { + if ((rv = nni_udp_open(&ep->udp, &ep->self_sa)) != 0) { + nni_aio_list_remove(aio); + nni_mtx_unlock(&ep->mtx); + nni_aio_finish_error(aio, rv); + return; + } + } + + // places a "hold" on the ep + if ((rv = udp_pipe_alloc(&p, ep, 0, &ep->peer_sa)) != 0) { + nni_aio_list_remove(aio); + nni_mtx_unlock(&ep->mtx); + nni_aio_finish_error(aio, rv); + return; + } + + udp_pipe_schedule(p); + udp_ep_start(ep); + + // Send out the connection request. We don't complete + // the user aio until we confirm a connection, so that + // we can supply details like maximum receive message size + // and the protocol the peer is using. + udp_send_creq(ep, p); + nni_mtx_unlock(&ep->mtx); +} + +static void +udp_ep_connect(void *arg, nni_aio *aio) +{ + udp_ep *ep = arg; + int rv; + + if (nni_aio_begin(aio) != 0) { + return; + } + nni_mtx_lock(&ep->mtx); + if (ep->closed) { + nni_mtx_unlock(&ep->mtx); + nni_aio_finish_error(aio, NNG_ECLOSED); + return; + } + if (ep->started) { + nni_mtx_unlock(&ep->mtx); + nni_aio_finish_error(aio, NNG_EBUSY); + return; + } + NNI_ASSERT(nni_list_empty(&ep->connaios)); + ep->dialer = true; + + if ((rv = nni_aio_schedule(aio, udp_ep_cancel, ep)) != 0) { + nni_mtx_unlock(&ep->mtx); + nni_aio_finish_error(aio, rv); + return; + } + + nni_list_append(&ep->connaios, aio); + + // lookup the IP address + + nni_aio_set_timeout(&ep->resaio, NNI_SECOND * 5); + nni_resolv_ip(ep->url->u_hostname, ep->url->u_port, ep->af, false, + &ep->peer_sa, &ep->resaio); + + // wake up for retries + nni_aio_abort(&ep->timeaio, NNG_EINTR); + + nni_mtx_unlock(&ep->mtx); +} + +static int +udp_ep_get_port(void *arg, void *buf, size_t *szp, nni_type t) +{ + udp_ep *ep = arg; + nng_sockaddr sa; + int port; + uint8_t *paddr; + + nni_mtx_lock(&ep->mtx); + if (ep->udp != NULL) { + (void) nni_udp_sockname(ep->udp, &sa); + } else { + sa = ep->self_sa; + } + switch (sa.s_family) { + case NNG_AF_INET: + paddr = (void *) &sa.s_in.sa_port; + break; + + case NNG_AF_INET6: + paddr = (void *) &sa.s_in6.sa_port; + break; + + default: + paddr = NULL; + break; + } + nni_mtx_unlock(&ep->mtx); + + if (paddr == NULL) { + return (NNG_ESTATE); + } + + NNI_GET16(paddr, port); + return (nni_copyout_int(port, buf, szp, t)); +} + +static int +udp_ep_get_url(void *arg, void *v, size_t *szp, nni_opt_type t) +{ + udp_ep *ep = arg; + char *s; + int rv; + int port = 0; + nng_sockaddr sa; + + nni_mtx_lock(&ep->mtx); + if (ep->udp != NULL) { + (void) nni_udp_sockname(ep->udp, &sa); + } else { + sa = ep->self_sa; + } + switch (sa.s_family) { + case NNG_AF_INET: + NNI_GET16((uint8_t *) &sa.s_in.sa_port, port); + break; + case NNG_AF_INET6: + NNI_GET16((uint8_t *) &sa.s_in6.sa_port, port); + break; + } + if ((rv = nni_url_asprintf_port(&s, ep->url, port)) == 0) { + rv = nni_copyout_str(s, v, szp, t); + nni_strfree(s); + } + nni_mtx_unlock(&ep->mtx); + + return (rv); +} + +static int +udp_ep_get_locaddr(void *arg, void *v, size_t *szp, nni_opt_type t) +{ + udp_ep *ep = arg; + int rv; + nng_sockaddr sa; + + if (ep->udp != NULL) { + (void) nni_udp_sockname(ep->udp, &sa); + } else { + sa = ep->self_sa; + } + + rv = nni_copyout_sockaddr(&sa, v, szp, t); + return (rv); +} + +static int +udp_ep_get_remaddr(void *arg, void *v, size_t *szp, nni_opt_type t) +{ + udp_ep *ep = arg; + int rv; + nng_sockaddr sa; + + if (!ep->dialer) { + return (NNG_ENOTSUP); + } + sa = ep->peer_sa; + + rv = nni_copyout_sockaddr(&sa, v, szp, t); + return (rv); +} + +static int +udp_ep_get_recvmaxsz(void *arg, void *v, size_t *szp, nni_opt_type t) +{ + udp_ep *ep = arg; + int rv; + + nni_mtx_lock(&ep->mtx); + rv = nni_copyout_size(ep->rcvmax, v, szp, t); + nni_mtx_unlock(&ep->mtx); + return (rv); +} + +static int +udp_ep_set_recvmaxsz(void *arg, const void *v, size_t sz, nni_opt_type t) +{ + udp_ep *ep = arg; + size_t val; + int rv; + if ((rv = nni_copyin_size(&val, v, sz, 0, 65000, t)) == 0) { + nni_mtx_lock(&ep->mtx); + if (ep->started) { + nni_mtx_unlock(&ep->mtx); + return (NNG_EBUSY); + } + ep->rcvmax = (uint16_t) val; + nni_mtx_unlock(&ep->mtx); +#ifdef NNG_ENABLE_STATS + nni_stat_set_value(&ep->st_rcv_max, val); +#endif + } + return (rv); +} + +// this just looks for pipes waiting for an aio, and aios waiting for +// a connection, and matches them together. +static void +udp_ep_match(udp_ep *ep) +{ + nng_aio *aio = nni_list_first(&ep->connaios); + udp_pipe *p = nni_list_first(&ep->connpipes); + + if ((aio == NULL) || (p == NULL)) { + return; + } + + nni_aio_list_remove(aio); + nni_list_remove(&ep->connpipes, p); + nni_aio_set_output(aio, 0, p); + nni_aio_finish(aio, 0, 0); +} + +static void +udp_ep_start(udp_ep *ep) +{ + ep->started = true; + udp_start_rx(ep); +} + +static int +udp_ep_bind(void *arg) +{ + udp_ep *ep = arg; + int rv; + + nni_mtx_lock(&ep->mtx); + if (ep->started) { + nni_mtx_unlock(&ep->mtx); + return (NNG_EBUSY); + } + + rv = nni_udp_open(&ep->udp, &ep->self_sa); + if (rv != 0) { + nni_mtx_unlock(&ep->mtx); + return (rv); + } + udp_ep_start(ep); + nni_mtx_unlock(&ep->mtx); + + return (rv); +} + +static void +udp_ep_accept(void *arg, nni_aio *aio) +{ + udp_ep *ep = arg; + int rv; + + if (nni_aio_begin(aio) != 0) { + return; + } + nni_mtx_lock(&ep->mtx); + if (ep->closed) { + nni_mtx_unlock(&ep->mtx); + nni_aio_finish_error(aio, NNG_ECLOSED); + return; + } + if ((rv = nni_aio_schedule(aio, udp_ep_cancel, ep)) != 0) { + nni_mtx_unlock(&ep->mtx); + nni_aio_finish_error(aio, rv); + return; + } + nni_aio_list_append(&ep->connaios, aio); + udp_ep_match(ep); + nni_mtx_unlock(&ep->mtx); +} + +static nni_sp_pipe_ops udp_pipe_ops = { + .p_init = udp_pipe_init, + .p_fini = udp_pipe_fini, + .p_stop = udp_pipe_stop, + .p_send = udp_pipe_send, + .p_recv = udp_pipe_recv, + .p_close = udp_pipe_close, + .p_peer = udp_pipe_peer, + .p_getopt = udp_pipe_getopt, +}; + +static const nni_option udp_ep_opts[] = { + { + .o_name = NNG_OPT_RECVMAXSZ, + .o_get = udp_ep_get_recvmaxsz, + .o_set = udp_ep_set_recvmaxsz, + }, + { + .o_name = NNG_OPT_URL, + .o_get = udp_ep_get_url, + }, + { + .o_name = NNG_OPT_LOCADDR, + .o_get = udp_ep_get_locaddr, + }, + { + .o_name = NNG_OPT_REMADDR, + .o_get = udp_ep_get_remaddr, + }, + { + .o_name = NNG_OPT_TCP_BOUND_PORT, + .o_get = udp_ep_get_port, + }, + // terminate list + { + .o_name = NULL, + }, +}; + +static int +udp_dialer_getopt( + void *arg, const char *name, void *buf, size_t *szp, nni_type t) +{ + udp_ep *ep = arg; + + return (nni_getopt(udp_ep_opts, name, ep, buf, szp, t)); +} + +static int +udp_dialer_setopt( + void *arg, const char *name, const void *buf, size_t sz, nni_type t) +{ + udp_ep *ep = arg; + + return (nni_setopt(udp_ep_opts, name, ep, buf, sz, t)); +} + +static int +udp_listener_getopt( + void *arg, const char *name, void *buf, size_t *szp, nni_type t) +{ + udp_ep *ep = arg; + + return (nni_getopt(udp_ep_opts, name, ep, buf, szp, t)); +} + +static int +udp_listener_setopt( + void *arg, const char *name, const void *buf, size_t sz, nni_type t) +{ + udp_ep *ep = arg; + + return (nni_setopt(udp_ep_opts, name, ep, buf, sz, t)); +} + +static nni_sp_dialer_ops udp_dialer_ops = { + .d_init = udp_dialer_init, + .d_fini = udp_ep_fini, + .d_connect = udp_ep_connect, + .d_close = udp_ep_close, + .d_getopt = udp_dialer_getopt, + .d_setopt = udp_dialer_setopt, +}; + +static nni_sp_listener_ops udp_listener_ops = { + .l_init = udp_listener_init, + .l_fini = udp_ep_fini, + .l_bind = udp_ep_bind, + .l_accept = udp_ep_accept, + .l_close = udp_ep_close, + .l_getopt = udp_listener_getopt, + .l_setopt = udp_listener_setopt, +}; + +static nni_sp_tran udp_tran = { + .tran_scheme = "udp", + .tran_dialer = &udp_dialer_ops, + .tran_listener = &udp_listener_ops, + .tran_pipe = &udp_pipe_ops, + .tran_init = udp_tran_init, + .tran_fini = udp_tran_fini, +}; + +static nni_sp_tran udp4_tran = { + .tran_scheme = "udp4", + .tran_dialer = &udp_dialer_ops, + .tran_listener = &udp_listener_ops, + .tran_pipe = &udp_pipe_ops, + .tran_init = udp_tran_init, + .tran_fini = udp_tran_fini, +}; + +#ifdef NNG_ENABLE_IPV6 +static nni_sp_tran udp6_tran = { + .tran_scheme = "udp6", + .tran_dialer = &udp_dialer_ops, + .tran_listener = &udp_listener_ops, + .tran_pipe = &udp_pipe_ops, + .tran_init = udp_tran_init, + .tran_fini = udp_tran_fini, +}; +#endif + +void +nni_sp_udp_register(void) +{ + nni_sp_tran_register(&udp_tran); + nni_sp_tran_register(&udp4_tran); +#ifdef NNG_ENABLE_IPV6 + nni_sp_tran_register(&udp6_tran); +#endif +} diff --git a/src/sp/transport/udp/udp_tran_test.c b/src/sp/transport/udp/udp_tran_test.c new file mode 100644 index 000000000..b99c5af19 --- /dev/null +++ b/src/sp/transport/udp/udp_tran_test.c @@ -0,0 +1,171 @@ +// +// Copyright 2024 Staysail Systems, Inc. +// Copyright 2018 Capitar IT Group BV +// Copyright 2018 Devolutions +// Copyright 2018 Cody Piersall +// +// This software is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +#include "nng/nng.h" +#include + +// TCP tests. + +static void +test_udp_wild_card_connect_fail(void) +{ + nng_socket s; + char addr[NNG_MAXADDRLEN]; + + NUTS_OPEN(s); + (void) snprintf(addr, sizeof(addr), "udp://*:%u", nuts_next_port()); + NUTS_FAIL(nng_dial(s, addr, NULL, 0), NNG_EADDRINVAL); + NUTS_CLOSE(s); +} + +void +test_udp_wild_card_bind(void) +{ + nng_socket s1; + nng_socket s2; + char addr[NNG_MAXADDRLEN]; + uint16_t port; + + port = nuts_next_port(); + + NUTS_OPEN(s1); + NUTS_OPEN(s2); + (void) snprintf(addr, sizeof(addr), "udp4://*:%u", port); + NUTS_PASS(nng_listen(s1, addr, NULL, 0)); + nng_msleep(500); + (void) snprintf(addr, sizeof(addr), "udp://127.0.0.1:%u", port); + NUTS_PASS(nng_dial(s2, addr, NULL, 0)); + NUTS_CLOSE(s2); + NUTS_CLOSE(s1); +} + +void +test_udp_local_address_connect(void) +{ + + nng_socket s1; + nng_socket s2; + char addr[NNG_MAXADDRLEN]; + uint16_t port; + + NUTS_OPEN(s1); + NUTS_OPEN(s2); + port = nuts_next_port(); + (void) snprintf(addr, sizeof(addr), "udp://127.0.0.1:%u", port); + NUTS_PASS(nng_listen(s1, addr, NULL, 0)); + (void) snprintf(addr, sizeof(addr), "udp://127.0.0.1:%u", port); + NUTS_PASS(nng_dial(s2, addr, NULL, 0)); + NUTS_CLOSE(s2); + NUTS_CLOSE(s1); +} + +void +test_udp_port_zero_bind(void) +{ + nng_socket s1; + nng_socket s2; + nng_sockaddr sa; + nng_listener l; + char *addr; + int port; + + NUTS_OPEN(s1); + NUTS_OPEN(s2); + NUTS_PASS(nng_listen(s1, "udp://127.0.0.1:0", &l, 0)); + nng_msleep(100); + NUTS_PASS(nng_listener_get_string(l, NNG_OPT_URL, &addr)); + NUTS_TRUE(memcmp(addr, "udp://", 6) == 0); + NUTS_PASS(nng_listener_get_addr(l, NNG_OPT_LOCADDR, &sa)); + NUTS_TRUE(sa.s_in.sa_family == NNG_AF_INET); + NUTS_TRUE(sa.s_in.sa_port != 0); + NUTS_TRUE(sa.s_in.sa_addr == nuts_be32(0x7f000001)); + NUTS_PASS(nng_dial(s2, addr, NULL, 0)); + NUTS_PASS(nng_listener_get_int(l, NNG_OPT_TCP_BOUND_PORT, &port)); + NUTS_TRUE(port == nuts_be16(sa.s_in.sa_port)); + nng_strfree(addr); + + NUTS_CLOSE(s2); + NUTS_CLOSE(s1); +} + +void +test_udp_non_local_address(void) +{ + nng_socket s1; + + NUTS_OPEN(s1); + NUTS_FAIL(nng_listen(s1, "udp://8.8.8.8", NULL, 0), NNG_EADDRINVAL); + NUTS_CLOSE(s1); +} + +void +test_udp_malformed_address(void) +{ + nng_socket s1; + + NUTS_OPEN(s1); + NUTS_FAIL(nng_dial(s1, "udp://127.0.0.1", NULL, 0), NNG_EADDRINVAL); + NUTS_FAIL(nng_dial(s1, "udp://127.0.0.1.32", NULL, 0), NNG_EADDRINVAL); + NUTS_FAIL(nng_dial(s1, "udp://127.0.x.1.32", NULL, 0), NNG_EADDRINVAL); + NUTS_FAIL( + nng_listen(s1, "udp://127.0.0.1.32", NULL, 0), NNG_EADDRINVAL); + NUTS_FAIL( + nng_listen(s1, "udp://127.0.x.1.32", NULL, 0), NNG_EADDRINVAL); + NUTS_CLOSE(s1); +} + +void +test_udp_recv_max(void) +{ + char msg[256]; + char buf[256]; + nng_socket s0; + nng_socket s1; + nng_listener l; + size_t sz; + char *addr; + + NUTS_ADDR(addr, "udp"); + + NUTS_OPEN(s0); + NUTS_PASS(nng_socket_set_ms(s0, NNG_OPT_RECVTIMEO, 100)); + NUTS_PASS(nng_socket_set_size(s0, NNG_OPT_RECVMAXSZ, 200)); + NUTS_PASS(nng_listener_create(&l, s0, addr)); + NUTS_PASS(nng_socket_get_size(s0, NNG_OPT_RECVMAXSZ, &sz)); + NUTS_TRUE(sz == 200); + NUTS_PASS(nng_listener_set_size(l, NNG_OPT_RECVMAXSZ, 100)); + NUTS_PASS(nng_listener_start(l, 0)); + + NUTS_OPEN(s1); + NUTS_PASS(nng_dial(s1, addr, NULL, 0)); + nng_msleep(1000); + NUTS_PASS(nng_send(s1, msg, 95, 0)); + NUTS_PASS(nng_socket_set_ms(s1, NNG_OPT_SENDTIMEO, 100)); + NUTS_PASS(nng_recv(s0, buf, &sz, 0)); + NUTS_TRUE(sz == 95); + NUTS_PASS(nng_send(s1, msg, 150, 0)); + NUTS_FAIL(nng_recv(s0, buf, &sz, 0), NNG_ETIMEDOUT); + NUTS_PASS(nng_close(s0)); + NUTS_CLOSE(s1); +} + +NUTS_TESTS = { + + { "udp wild card connect fail", test_udp_wild_card_connect_fail }, + { "udp wild card bind", test_udp_wild_card_bind }, + { "udp port zero bind", test_udp_port_zero_bind }, + { "udp local address connect", test_udp_local_address_connect }, + { "udp non-local address", test_udp_non_local_address }, + { "udp malformed address", test_udp_malformed_address }, + { "udp recv max", test_udp_recv_max }, + { NULL, NULL }, +}; From 8b8aacca5449538024c78c1116e0e1f8e2fbc3f8 Mon Sep 17 00:00:00 2001 From: Garrett D'Amore Date: Sat, 5 Oct 2024 18:35:22 -0700 Subject: [PATCH 003/222] test: support UDP urls for marry --- src/testing/marry.c | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/src/testing/marry.c b/src/testing/marry.c index d39cf583a..7441468ff 100644 --- a/src/testing/marry.c +++ b/src/testing/marry.c @@ -1,5 +1,5 @@ // -// Copyright 2021 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 @@ -46,7 +46,8 @@ nuts_scratch_addr(const char *scheme, size_t sz, char *addr) } if ((strncmp(scheme, "tcp", 3) == 0) || - (strncmp(scheme, "tls", 3) == 0)) { + (strncmp(scheme, "tls", 3) == 0) || + (strncmp(scheme, "udp", 3) == 0)) { (void) snprintf( addr, sz, "%s://127.0.0.1:%u", scheme, nuts_next_port()); return; @@ -84,6 +85,7 @@ nuts_scratch_addr(const char *scheme, size_t sz, char *addr) } // We should not be here. + nng_log_err("NUTS", "Unknown scheme"); abort(); } From 5ab46c47fb4ea9156d7cbba1bc5e3fe13494761f Mon Sep 17 00:00:00 2001 From: jan-ruzicka-c <83418213+jan-ruzicka-c@users.noreply.github.com> Date: Wed, 18 Sep 2024 12:40:51 -0400 Subject: [PATCH 004/222] Update README.adoc fix link to TLS build instructions file. It was renamed from docs/BUILD_TLS.adoc to docs/BUILD_TLS.md in commit 6e5cf29 --- README.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.adoc b/README.adoc index 5408e1ba5..1fd042eb9 100644 --- a/README.adoc +++ b/README.adoc @@ -128,7 +128,7 @@ system (pass "-G Ninja" to CMake) when you can. blindingly fast and has made our lives as developers measurably better.) If you want to build with TLS support you will also need -https://tls.mbed.org[Mbed TLS]. See <> for details. +https://tls.mbed.org[Mbed TLS]. See <> for details. == Quick Start From 8633294b0a5ef4ef4bce4046fcbb4f4c61e65516 Mon Sep 17 00:00:00 2001 From: Garrett D'Amore Date: Sat, 5 Oct 2024 22:57:57 -0700 Subject: [PATCH 005/222] README update for development vs. stable Signed-off-by: jaylin --- README.adoc | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/README.adoc b/README.adoc index 1fd042eb9..c0791c282 100644 --- a/README.adoc +++ b/README.adoc @@ -22,6 +22,15 @@ image:https://img.shields.io/static/v1?label=&message=docs&logo=asciidoctor&logo image:https://img.shields.io/github/license/nanomsg/nng.svg?logoColor=silver&logo=open-source-initiative&label=&color=blue[MIT License,link="https://github.com/nanomsg/nng/blob/master/LICENSE.txt"] image:https://img.shields.io/github/v/tag/nanomsg/nng.svg?logo=github&label=[Latest version,link="https://github.com/nanomsg/nng/releases"] +<<<<<<< HEAD +======= +Please see <> for an important message for the people of Russia. + +NOTE: THIS IS THE DEVELOPMENT BRANCH FOR NNG. The content here is +under development and may not be stable. Please use the `stable` branch +for the latest stable release. + +>>>>>>> 4ae376e82 (README update for development vs. stable) NOTE: If you are looking for the legacy version of nanomsg, please see the https://github.com/nanomsg/nanomsg[nanomsg] repository. From 81b1d82d715a6be3540bb3954841939a339210a3 Mon Sep 17 00:00:00 2001 From: Garrett D'Amore Date: Sun, 6 Oct 2024 10:58:54 -0700 Subject: [PATCH 006/222] posix: add getentropy() based RNG XPG8 defines getentropy() as the only good source for random numbers. However, real world use a bit more nuanced. On BSD systems, we would prefer to use arc4random as it avoids unnecessary system calls. On Linux however, getentropy is implemented in terms of getrandom, and should be used directly when available. --- src/platform/posix/CMakeLists.txt | 4 +++ src/platform/posix/posix_rand_getentropy.c | 39 ++++++++++++++++++++++ 2 files changed, 43 insertions(+) create mode 100644 src/platform/posix/posix_rand_getentropy.c diff --git a/src/platform/posix/CMakeLists.txt b/src/platform/posix/CMakeLists.txt index 2212c8c86..6f3dfcafa 100644 --- a/src/platform/posix/CMakeLists.txt +++ b/src/platform/posix/CMakeLists.txt @@ -26,6 +26,7 @@ if (NNG_PLATFORM_POSIX) nng_check_func(lockf NNG_HAVE_LOCKF) nng_check_func(flock NNG_HAVE_FLOCK) + nng_check_func(getentropy NNG_HAVE_GETENTROPY) nng_check_func(getrandom NNG_HAVE_GETRANDOM) nng_check_func(arc4random_buf NNG_HAVE_ARC4RANDOM) @@ -69,6 +70,7 @@ if (NNG_PLATFORM_POSIX) nng_check_sym(socketpair sys/socket.h NNG_HAVE_SOCKETPAIR) nng_check_sym(AF_INET6 netinet/in.h NNG_HAVE_INET6) nng_check_sym(timespec_get time.h NNG_HAVE_TIMESPEC_GET) + nng_check_sym(getentropy sys/random.h NNG_HAVE_SYS_RANDOM) nng_sources( posix_impl.h @@ -111,6 +113,8 @@ if (NNG_PLATFORM_POSIX) if (NNG_HAVE_ARC4RANDOM) nng_sources(posix_rand_arc4random.c) + elseif (NNG_HAVE_GETENTROPY) + nng_sources(posix_rand_getentropy.c) elseif (NNG_HAVE_GETRANDOM) nng_sources(posix_rand_getrandom.c) else () diff --git a/src/platform/posix/posix_rand_getentropy.c b/src/platform/posix/posix_rand_getentropy.c new file mode 100644 index 000000000..6f7fbcd7e --- /dev/null +++ b/src/platform/posix/posix_rand_getentropy.c @@ -0,0 +1,39 @@ +// +// Copyright 2024 Staysail Systems, Inc. +// +// This software is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +// getrandom is not as nice as arc4random, but on platforms where it +// exists and arc4random does not, we should use it. +// +// getrandom will block only if the urandom device is not seeded yet. +// That can only happen during very early boot (earlier than we should +// normally be running. This is the only time it can fail with correct +// arguments, and then only if it is interrupted with a signal. + +#include +#include +#include +#ifdef NNG_HAVE_SYS_RANDOM +#include +#endif + +#include "core/panic.h" + +#ifdef NNG_HAVE_GETENTROPY + +uint32_t +nni_random(void) +{ + uint32_t val; + if (getentropy(&val, sizeof(val)) != 0) { + nni_panic("getentropy failed"); + } + return (val); +} + +#endif From 66d1afa18aaae351695745519bb4468d3dd77c3d Mon Sep 17 00:00:00 2001 From: Garrett D'Amore Date: Sun, 6 Oct 2024 11:49:39 -0700 Subject: [PATCH 007/222] Flag build packages as 2.0.0-dev. Signed-off-by: jaylin --- CMakeLists.txt | 6 ++++-- include/nng/nng.h | 7 ++++--- 2 files changed, 8 insertions(+), 5 deletions(-) diff --git a/CMakeLists.txt b/CMakeLists.txt index cc5e1f795..6ee146bcd 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -58,8 +58,10 @@ set(NNG_MINOR_VERSION ${CMAKE_MATCH_1}) string(REGEX MATCH "NNG_PATCH_VERSION ([0-9]*)" _ ${nng_ver_h}) set(NNG_PATCH_VERSION ${CMAKE_MATCH_1}) string(REGEX MATCH "NNG_RELEASE_SUFFIX \"([a-z0-9]*)\"" _ ${nng_ver_h}) -if (NOT ("${CMAKE_MATCH_1}" STREQUAL "")) - set(NNG_PRERELEASE "-${CMAKE_MATCH_1}") +set(NNG_DEV_VERSION ${CMAKE_MATCH_1}) +if (NNG_DEV_VERSION) + message(STATUS "This is a prelease.") + set(NNG_PRERELEASE "-${NNG_DEV_VERSION}") endif () set(NNG_ABI_SOVERSION 1) diff --git a/include/nng/nng.h b/include/nng/nng.h index 8e72c06c2..9fea280b8 100644 --- a/include/nng/nng.h +++ b/include/nng/nng.h @@ -56,11 +56,12 @@ extern "C" { // NNG Library & API version. // We use SemVer, and these versions are about the API, and // may not necessarily match the ABI versions. -#define NNG_MAJOR_VERSION 1 -#define NNG_MINOR_VERSION 10 +#define NNG_MAJOR_VERSION 2 +#define NNG_MINOR_VERSION 0 #define NNG_PATCH_VERSION 0 + // if non-empty (i.e. "pre"), this is a pre-release -#define NNG_RELEASE_SUFFIX "" +#define NNG_RELEASE_SUFFIX "dev" // Maximum length of a socket address. This includes the terminating NUL. // This limit is built into other implementations, so do not change it. From bf8e56ed975e37d7a2087d9be0ce5d60f62638e3 Mon Sep 17 00:00:00 2001 From: Garrett D'Amore Date: Sun, 6 Oct 2024 12:11:19 -0700 Subject: [PATCH 008/222] Convert README to markdown Signed-off-by: jaylin --- README.adoc | 192 ------------------------------------------------- README.md | 200 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 200 insertions(+), 192 deletions(-) delete mode 100644 README.adoc create mode 100644 README.md diff --git a/README.adoc b/README.adoc deleted file mode 100644 index c0791c282..000000000 --- a/README.adoc +++ /dev/null @@ -1,192 +0,0 @@ -This is NNG repo of NanoMQ project. I have updated it to support MQTT protocol. - - - - -ifdef::env-github[] -:note-caption: :information_source: -:important-caption: :heavy_exclamation_mark: -endif::[] -= nng - nanomsg-next-gen - -// Note: This README is optimized for display with Asciidoctor, or -// on the GitHub project page at https://github.com/nanomsg/nng. - -image:https://raw.githubusercontent.com/vshymanskyy/StandWithUkraine/main/badges/StandWithUkraine.svg[Stand With Ukraine,link="https://stand-with-ukraine.pp.ua"] -image:https://img.shields.io/github/actions/workflow/status/nanomsg/nng/linux.yml?branch=stable&logoColor=grey&logo=ubuntu&label=[Linux Status,link="https://github.com/nanomsg/nng/actions"] -image:https://img.shields.io/github/actions/workflow/status/nanomsg/nng/windows.yml?branch=stable&logoColor=grey&logo=windows&label=[Windows Status,link="https://github.com/nanomsg/nng/actions"] -image:https://img.shields.io/github/actions/workflow/status/nanomsg/nng/darwin.yml?branch=stable&logoColor=grey&logo=apple&label=[macOS Status,link="https://github.com/nanomsg/nng/actions"] -image:https://img.shields.io/codecov/c/github/nanomsg/nng/branch/stable?logo=codecov&logoColor=grey&label=[Coverage,link="https://codecov.io/gh/nanomsg/nng"] -image:https://img.shields.io/discord/639573728212156478?label=&logo=discord[Discord,link="https://discord.gg/Xnac6b9"] -image:https://img.shields.io/static/v1?label=&message=docs&logo=asciidoctor&logoColor=silver&color=blue[Manual,link="https://nng.nanomsg.org/man"] -image:https://img.shields.io/github/license/nanomsg/nng.svg?logoColor=silver&logo=open-source-initiative&label=&color=blue[MIT License,link="https://github.com/nanomsg/nng/blob/master/LICENSE.txt"] -image:https://img.shields.io/github/v/tag/nanomsg/nng.svg?logo=github&label=[Latest version,link="https://github.com/nanomsg/nng/releases"] - -<<<<<<< HEAD -======= -Please see <> for an important message for the people of Russia. - -NOTE: THIS IS THE DEVELOPMENT BRANCH FOR NNG. The content here is -under development and may not be stable. Please use the `stable` branch -for the latest stable release. - ->>>>>>> 4ae376e82 (README update for development vs. stable) -NOTE: If you are looking for the legacy version of nanomsg, please -see the https://github.com/nanomsg/nanomsg[nanomsg] repository. - -This project is a rewrite of the Scalability Protocols -library known as https://github.com/nanomsg/nanomsg[libnanomsg], -and adds significant new capabilities, while retaining -compatibility with the original. - -It may help to think of this as "nanomsg-next-generation". - -== NNG: Lightweight Messaging Library - -NNG, like its predecessors http://nanomsg.org[nanomsg] (and to some extent -http://zeromq.org/[ZeroMQ]), is a lightweight, broker-less library, -offering a simple API to solve common recurring messaging problems, -such as publish/subscribe, RPC-style request/reply, or service discovery. -The API frees the programmer from worrying about details like connection -management, retries, and other common considerations, so that they -can focus on the application instead of the plumbing. - -NNG is implemented in C, requiring only C99 and CMake to build. -It can be built as a shared or a static library, and is readily -embeddable. It is also designed to be easy to port to new platforms -if your platform is not already supported. - -== License - -NNG is licensed under a liberal, and commercial friendly, MIT license. -The goal to the license is to minimize friction in adoption, use, and -contribution. - -== Enhancements (Relative to nanomsg) - -Here are areas where this project improves on "nanomsg": - -[horizontal] -*Reliability*:: NNG is designed for production use from the beginning. Every -error case is considered, and it is designed to avoid crashing except in cases -of gross developer error. (Hopefully we don't have any of these in our own -code.) - -*Scalability*:: NNG scales out to engage multiple cores using a bespoke -asynchronous I/O framework, using thread pools to spread load without -exceeding typical system limits. - -*Maintainability*:: NNG's architecture is designed to be modular and -easily grasped by developers unfamiliar with the code base. The code -is also well documented. - -*Extensibility*:: Because it avoids ties to file descriptors, and avoids -confusing interlocking state machines, it is easier to add new protocols -and transports to NNG. This was demonstrated by the addition of the -TLS and ZeroTier transports. - -*Security*:: NNG provides TLS 1.2 and ZeroTier transports, offering -support for robust and industry standard authentication and encryption. -In addition, it is hardened to be resilient against malicious attackers, -with special consideration given to use in a hostile Internet. - -*Usability*:: NNG eschews slavish adherence parts of the more complex and -less well understood POSIX APIs, while adopting the semantics that are -familiar and useful. New APIs are intuitive, and the optional support -for separating protocol context and state from sockets makes creating -concurrent applications vastly simpler than previously possible. - -== Compatibility - -This project offers both wire compatibility and API compatibility, -so most nanomsg users can begin using NNG right away. - -Existing nanomsg and https://github.com/nanomsg/mangos[mangos] applications -can inter-operate with NNG applications automatically. - -That said, there are some areas where legacy nanomsg still offers -capabilities NNG lacks -- specifically enhanced observability with -statistics, and tunable prioritization of different destinations -are missing, but will be added in a future release. - -Additionally, some API capabilities that are useful for foreign -language bindings are not implemented yet. - -Some simple single threaded, synchronous applications may perform better under -legacy nanomsg than under NNG. (We believe that these applications are the -least commonly deployed, and least interesting from a performance perspective. -NNG's internal design is slightly less efficient in such scenarios, but it -greatly benefits when concurrency or when multiple sockets or network peers -are involved.) - -== Supported Platforms - -NNG supports Linux, macOS, Windows (Vista or better), illumos, Solaris, -FreeBSD, Android, and iOS. Most other POSIX platforms should work out of -the box but have not been tested. Very old versions of otherwise supported -platforms might not work. - -== Requirements - -To build this project, you will need a C99 compatible compiler and -http://www.cmake.org[CMake] version 3.13 or newer. - -We recommend using the https://ninja-build.org[Ninja] build -system (pass "-G Ninja" to CMake) when you can. -(And not just because Ninja sounds like "NNG" -- it's also -blindingly fast and has made our lives as developers measurably better.) - -If you want to build with TLS support you will also need -https://tls.mbed.org[Mbed TLS]. See <> for details. - -== Quick Start - -With a Linux or UNIX environment: - -[source,sh] ----- - $ mkdir build - $ cd build - $ cmake -G Ninja .. - $ ninja - $ ninja test - $ ninja install ----- - -== API Documentation - -The API documentation is provided in Asciidoc format in the -`docs/man` subdirectory, and also -https://nanomsg.github.io/nng[online]. -The <> page provides a conceptual overview and links to -manuals for various patterns. -The <> page is a good starting point for the API reference. - -You can also purchase a copy of the -http://staysail.tech/books/nng_reference/index.html[__NNG Reference Manual__]. -(It is published in both electronic and printed formats.) -Purchases of the book help fund continued development of NNG. - -== Example Programs - -Some demonstration programs have been created to help serve as examples. -These are located in the `demo` directory. - -== Legacy Compatibility - -A legacy `libnanomsg` compatible API is available, and while it offers -less capability than the modern NNG API, it may serve as a transition aid. -Please see <> for details. - -== Commercial Support - -Commercial support for NNG is available. - -Please contact mailto:info@staysail.tech[Staysail Systems, Inc.] to -inquire further. - -== Commercial Sponsors - -The development of NNG has been made possible through the generous -sponsorship of https://www.capitar.com[Capitar IT Group BV] and -http://staysail.tech[Staysail Systems, Inc.]. diff --git a/README.md b/README.md new file mode 100644 index 000000000..cc0504a37 --- /dev/null +++ b/README.md @@ -0,0 +1,200 @@ +# nng - nanomsg-next-gen + +[![Stand With Ukraine](https://raw.githubusercontent.com/vshymanskyy/StandWithUkraine/main/badges/StandWithUkraine.svg)](https://stand-with-ukraine.pp.ua) +[![Linux Status](https://img.shields.io/github/actions/workflow/status/nanomsg/nng/linux.yml?branch=dev2.0&logoColor=grey&logo=ubuntu&label=)](https://github.com/nanomsg/nng/actions) +[![Windows Status](https://img.shields.io/github/actions/workflow/status/nanomsg/nng/windows.yml?branch=dev2.0&logoColor=grey&logo=data:image/svg%2bxml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCA0ODc1IDQ4NzUiPjxwYXRoIGZpbGw9ImdyZXkiIGQ9Ik0wIDBoMjMxMXYyMzEwSDB6bTI1NjQgMGgyMzExdjIzMTBIMjU2NHpNMCAyNTY0aDIzMTF2MjMxMUgwem0yNTY0IDBoMjMxMXYyMzExSDI1NjQiLz48L3N2Zz4=&label=)](https://github.com/nanomsg/nng/actions) +[![macOS Status](https://img.shields.io/github/actions/workflow/status/nanomsg/nng/darwin.yml?branch=dev2.0&logoColor=grey&logo=apple&label=)](https://github.com/nanomsg/nng/actions) +[![Coverage](https://img.shields.io/codecov/c/github/nanomsg/nng?logo=codecov&logoColor=grey&label=)](https://codecov.io/gh/nanomsg/nng) +[![Discord](https://img.shields.io/discord/639573728212156478?label=&logo=discord)](https://discord.gg/Xnac6b9) +[![Manual](https://img.shields.io/static/v1?label=&message=docs&logo=asciidoctor&logoColor=silver&color=blue)](https://nng.nanomsg.org/man) +[![MIT License](https://img.shields.io/github/license/nanomsg/nng.svg?logoColor=silver&logo=open-source-initiative&label=&color=blue)](https://github.com/nanomsg/nng/blob/dev2.0/LICENSE.txt) +[![Latest Version](https://img.shields.io/github/v/tag/nanomsg/nng.svg?logo=github&label=)](https://github.com/nanomsg/nng/releases) + +Please see [here](UKRAINE) for an important message for the people of Russia. + +> [!NOTE] > _THIS IS THE DEVELOPMENT BRANCH FOR NNG._ The content here is +> under development and may not be suitable for production use. +> Please use the [`stable`](https://github.com/nanomsg/nng/tree/stable) branch +> for the latest stable release. + +> [!NOTE] +> If you are looking for the legacy version of nanomsg, please +> see the [libnanomsg](https://github.com/nanomsg/nanomsg) repository. + +This project is a rewrite of the Scalability Protocols +library known as [nanomsg](https://github.com/nanomsg/nanomsg), +and adds significant new capabilities, while retaining +compatibility with the original. + +It may help to think of this as "nanomsg-next-generation". + +## NNG: Lightweight Messaging Library + +NNG, like its predecessors [nanomsg](http://nanomsg.org) (and to some extent +[ZeroMQ](http://zeromq.org/)), is a lightweight, broker-less library, +offering a simple API to solve common recurring messaging problems, +such as publish/subscribe, RPC-style request/reply, or service discovery. +The API frees the programmer from worrying about details like connection +management, retries, and other common considerations, so that they +can focus on the application instead of the plumbing. + +NNG is implemented in C, requiring only C99 and CMake to build. +It can be built as a shared or a static library, and is readily +embeddable. It is also designed to be easy to port to new platforms +if your platform is not already supported. + +## License + +NNG is licensed under a liberal, and commercial friendly, MIT license. +The goal to the license is to minimize friction in adoption, use, and +contribution. + +## Enhancements (Relative to nanomsg) + +Here are areas where this project improves on "nanomsg": + +- _Reliability_ + + NNG is designed for production use from the beginning. + Every error case is considered, and it is designed to avoid crashing except + in cases of gross developer error. + (Hopefully we don't have any of these in our own code.) + +- _Scalability_ + + NNG scales out to engage multiple cores using a bespoke asynchronous I/O + framework, using thread pools to spread load without exceeding typical + system limits. + +- _Maintainability_ + + NNG's architecture is designed to be modular and easily grasped by developers + unfamiliar with the code base. The code is also well documented. + +- _Extensibility_ + + Because it avoids ties to file descriptors, and avoids confusing interlocking + state machines, it is easier to add new protocols and transports to NNG. + This was demonstrated by the addition of the TLS and ZeroTier transports. + +- _Security_ + + NNG provides TLS (1.2 and optionally 1.3) and ZeroTier transports, offering + support for robust and industry standard authentication and encryption. + In addition, it is hardened to be resilient against malicious attackers, + with special consideration given to use in a hostile Internet. + +- _Usability_ + + NNG eschews slavish adherence parts of the more complex and less well + understood POSIX APIs, while adopting the semantics that are familiar and + useful. New APIs are intuitive, and the optional support for separating + protocol context and state from sockets makes creating concurrent + applications vastly simpler than previously possible. + +## Compatibility + +This project offers both wire compatibility and API compatibility, +so most nanomsg users can begin using NNG right away. + +Existing nanomsg and https://github.com/nanomsg/mangos[mangos] applications +can inter-operate with NNG applications automatically. + +That said, there are some areas where legacy nanomsg still offers +capabilities NNG lacks -- specifically enhanced observability with +statistics, and tunable prioritization of different destinations +are missing, but will be added in a future release. + +Additionally, some API capabilities that are useful for foreign +language bindings are not implemented yet. + +Some simple single threaded, synchronous applications may perform better under +legacy nanomsg than under NNG. (We believe that these applications are the +least commonly deployed, and least interesting from a performance perspective. +NNG's internal design is slightly less efficient in such scenarios, but it +greatly benefits when concurrency or when multiple sockets or network peers +are involved.) + +## Supported Platforms + +NNG supports Linux, macOS, Windows (Vista or better), illumos, Solaris, +FreeBSD, Android, and iOS. Most other POSIX platforms should work out of +the box but have not been tested. Very old versions of otherwise supported +platforms might not work. + +Officially, NNG only supports operating systems that are supported by +their vendors. For example, Windows versions 8.1 and lower are no longer +officially supported. + +## Requirements + +To build this project, you will need a C99 compatible compiler and +[CMake](http://www.cmake.org) version 3.15 or newer. + +We recommend using the [Ninja](https://ninja-build.org) build +system (pass `-G Ninja` to CMake) when you can. +(And not just because Ninja sounds like "NNG" -- it's also +blindingly fast and has made our lives as developers measurably better.) + +If you want to build with TLS support you will also need +[Mbed TLS](https://tls.mbed.org). +See the [build instructions](docs/BUILD_TLS.md) for details. + +## Quick Start + +With a Linux or UNIX environment: + +```sh +$ mkdir build +$ cd build +$ cmake -G Ninja .. +$ ninja +$ ninja test +$ ninja install +``` + +## API Documentation + +The API documentation is provided in Asciidoc format in the +`docs/man` subdirectory, and also +[online](https://nanomsg.github.io/nng). + +> [!NOTE] +> However, an effort to convert the documentation to Markdown using `mdbook` +> is underway. + +The [_nng_(7)](docs/man/nng.7.adoc) page provides a conceptual overview and links to +manuals for various patterns. +The [_libnng_(3)](docs/man/libnng.3.adoc) page is a good starting point for the API reference. + +You can also purchase a copy of the +[**NNG Reference Manual**](http://staysail.tech/books/nng_reference/index.html). +(It is published in both electronic and printed formats.) +Purchases of the book help fund continued development of NNG. + +## Example Programs + +Some demonstration programs have been created to help serve as examples. +These are located in the `demo` directory. + +## Legacy Compatibility + +A legacy `libnanomsg` compatible API is available, and while it offers +less capability than the modern NNG API, it may serve as a transition aid. +Please see [_nng_compat_(3)](docs/man/nng_compat.3compat.adoc) for details. + +## Commercial Support + +Commercial support for NNG is available. + +Please contact +[Staysail Systems, Inc.](mailto:info@staysail.tech) +to inquire further. + +## Commercial Sponsors + +The development of NNG has been made possible through the generous +sponsorship of +[Capitar IT Group BV](https://www.capitar.com) +and +[Staysail Systems, Inc.](http://staysail.tech). From 8fc6ad79971e7b352274fc157925c7a3a1177701 Mon Sep 17 00:00:00 2001 From: jaylin Date: Tue, 18 Feb 2025 15:09:28 +0800 Subject: [PATCH 009/222] update comments in README Signed-off-by: jaylin --- README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/README.md b/README.md index cc0504a37..8048da2c2 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,5 @@ +This is NNG repo of NanoMQ project. I have updated it to support MQTT protocol. + # nng - nanomsg-next-gen [![Stand With Ukraine](https://raw.githubusercontent.com/vshymanskyy/StandWithUkraine/main/badges/StandWithUkraine.svg)](https://stand-with-ukraine.pp.ua) From 1643830b86b13988e20f4a773ff33b7e62f5af7f Mon Sep 17 00:00:00 2001 From: Garrett D'Amore Date: Sun, 6 Oct 2024 12:12:51 -0700 Subject: [PATCH 010/222] Markup fix (messed up by Prettier). --- README.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 8048da2c2..bff380f31 100644 --- a/README.md +++ b/README.md @@ -14,7 +14,8 @@ This is NNG repo of NanoMQ project. I have updated it to support MQTT protocol. Please see [here](UKRAINE) for an important message for the people of Russia. -> [!NOTE] > _THIS IS THE DEVELOPMENT BRANCH FOR NNG._ The content here is +> [!NOTE] _THIS IS THE DEVELOPMENT BRANCH FOR NNG._ +> The content here is > under development and may not be suitable for production use. > Please use the [`stable`](https://github.com/nanomsg/nng/tree/stable) branch > for the latest stable release. From ab2f413fae5d3c2b7a0fe3bf467623a0adc81f48 Mon Sep 17 00:00:00 2001 From: Garrett D'Amore Date: Sun, 6 Oct 2024 12:13:44 -0700 Subject: [PATCH 011/222] More markup tweak. --- README.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index bff380f31..047a26835 100644 --- a/README.md +++ b/README.md @@ -14,7 +14,8 @@ This is NNG repo of NanoMQ project. I have updated it to support MQTT protocol. Please see [here](UKRAINE) for an important message for the people of Russia. -> [!NOTE] _THIS IS THE DEVELOPMENT BRANCH FOR NNG._ +> [!NOTE] +> This is the development branch for NNG. > The content here is > under development and may not be suitable for production use. > Please use the [`stable`](https://github.com/nanomsg/nng/tree/stable) branch From 74c3f2d5aef5fe14010a7ca355d4e38f097f48fd Mon Sep 17 00:00:00 2001 From: Garrett D'Amore Date: Sun, 6 Oct 2024 12:18:23 -0700 Subject: [PATCH 012/222] docs: Provide migration guidance. --- README.md | 5 +- docs/migrating/nanomsg.md | 115 ++++++++++++++++++++++++++++++++++++++ docs/migrating/nng1.md | 50 +++++++++++++++++ 3 files changed, 167 insertions(+), 3 deletions(-) create mode 100644 docs/migrating/nanomsg.md create mode 100644 docs/migrating/nng1.md diff --git a/README.md b/README.md index 047a26835..c7d7f8e5b 100644 --- a/README.md +++ b/README.md @@ -183,9 +183,8 @@ These are located in the `demo` directory. ## Legacy Compatibility -A legacy `libnanomsg` compatible API is available, and while it offers -less capability than the modern NNG API, it may serve as a transition aid. -Please see [_nng_compat_(3)](docs/man/nng_compat.3compat.adoc) for details. +Migration from `libnanomsg` APIs is fairly straight-forward for most applications. +A [migration guide](docs/migration/nanomsg.md) is available to assist. ## Commercial Support diff --git a/docs/migrating/nanomsg.md b/docs/migrating/nanomsg.md new file mode 100644 index 000000000..e4c7b1848 --- /dev/null +++ b/docs/migrating/nanomsg.md @@ -0,0 +1,115 @@ +# Migrating from libnanomsg + +Previous version of NNG offered direct API compatibility with _libnanomsg_, +but that support is no longer offered in this version. + +If your application is still using legacy _libnanomsg_ APIs, you will need to +update it for this version of NNG. + +## Header Files + +Most applications can replace all `#include ` statements with `#include `. + +## Link Libraries + +Replace `-lnanomsg` with `-lnng`. +It may be necessary to include additional system libraries, such as `-lpthread`, depending on your system. + +## Types + +Sockets, dialers, and listeners in _libnanomsg_ are simple integers. +In NNG, these are `struct` types. + +Messages are quite different in NNG, with the absence of the POSIX message control +headers. + +The `struct nn_msghdr` structure has no equivalent. See `nng_msg` for the +NNG approach to messages. Likewise there is no `struct nn_cmsghdr` equivalent. + +## API Conversions + +| Nanomsg API | NNG Equivalent | Notes | +| ------------------- | ------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------- | +| `nn_strerror` | `nng_strerror` | +| `nn_errno` | No equivalent. Errors are redirectly rather than through `errno`. | +| `nn_socket` | Use the appropriate protocol constructor, such as `nng_req0_open`. | +| `nn_close` | `nng_close` | +| `nn_bind` | `nng_listen`, `nng_listener_create` | Allocating a listener with `nng_lister_create` and configuring it offers more capabilities. | +| `nn_connect` | `nng_dial`, `nng_dialer_create` | Allocating a dialer with `nng_dialer_create` and configuring it offers more capabilities. | +| `nn_shutdown` | `nng_lister_close`, `nng_dialer_close` | +| `nn_allocmsg` | `nng_msg_alloc` | There are significant semantic differences. | +| `nn_freemsg` | `nng_msg_free` | +| `nn_reallocmsg` | `nng_msg_realloc` | +| `nn_send` | `nng_send` | +| `nn_recv` | `nng_recv` | +| `nn_sendmsg` | `nng_sendmsg` | +| `nn_getsockopt` | `nng_socket_get` | NNG has typed accessors for options, and also separate functions for dialers and listeners. | +| `nn_setsockopt` | `nng_socket_set` | +| `nn_device` | `nng_device` | +| `nn_poll` | None | Can be constructed using `nng_aio`. Few if any applications ever used this API. | +| `nn_term` | None | The `nng_fini` API can do this, but is not recommended except when debugging memory leaks. | +| `nn_get_statistic` | `nng_stats_get` | The statistics in NNG are completely different, with different semantics and no stability guarantees. | +| `NN_POLLIN` | None | Used only with `nn_poll`. | +| `NN_POLLOUT` | None | Used only with `nn_poll`. | +| `NN_MSG` | `NNG_FLAG_ALLOC` | See `nng_send` and `nng_recv` for details. | +| `NN_CMSG_ALIGN` | None | +| `NN_CMSG_FIRSTHDR` | None | +| `NN_CMSG_NXTHDR` | None | +| `NN_CMSG_DATA` | None | +| `NN_CMSG_LEN` | None | +| `NN_CMSG_SPACE` | None | +| `struct nn_iovec` | `nng_iov` | +| `struct nn_msghdr` | `nng_msg` | +| `struct nn_cmsghdr` | `nng_msg` and `nng_msg_header` | + +## Options + +The following options are changed. + +| Nanomsg Option | NNG Eqvaivalent | Notes | +| ---------------------- | -------------------- | ------------------------------------------------------- | +| `NN_LINGER` | None | NNG does not support tuning this. | +| `NN_SNDBUF` | `NNG_OPT_SENDBUF` | NNG value is given in messages, not bytes. | +| `NN_RCVBUF` | `NNG_OPT_RECVBUF` | NNG value is given in messages, not bytes. | +| `NN_SNDTIMEO` | `NNG_OPT_SENDTIMEO` | +| `NN_RCVTIMEO` | `NNG_OPT_RECVTIMEO` | +| `NN_RECONNECT_IVL` | `NNG_OPT_RECONNMINT` | +| `NN_RECONNECT_IVL_MAX` | `NNG_OPT_RECONNMAXT` | +| `NN_SNDPRIO` | None | Not supported in NNG yet. | +| `NN_RCVPRIO` | None | Not supported in NNG yet. | +| `NN_RCVFD` | `NNG_OPT_RECVFD` | +| `NN_SNDFD` | `NNG_OPT_SENDFD` | +| `NN_DOMAIN` | None | NNG options are not divided by domain or protocol. | +| `NN_PROTOCOL` | `NNG_OPT_PROTO` | See also `NNG_OPT_PROTONAME`. | +| `NN_IPV4ONLY` | None | Use URL such as `tcp4://` to obtain this functionality. | +| `NN_SOCKET_NAME` | `NNG_OPT_SOCKNAME` | +| `NN_MAXTTL` | `NNG_OPT_MAXTTL` | + +## Error Codes + +Most of the error codes have similar names in NNG, just prefixed with `NNG_`. +There are some exceptions. Be aware that the numeric values are _not_ the same. + +| Nanomsg Error | NNG Error | Notes | +| -------------- | ------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------- | +| `EINTR` | `NNG_EINTR` | | +| `ENOMEM` | `NNG_ENOMEM` | | +| `EINVAL` | `NNG_EINVAL`, `NNG_EADDRINVAL`, `NNG_EBADTYPE`, `NNG_EAMBIGUOUS` | NNG discrimates between different types of errors. | +| `EBUSY` | `NNG_EBUSY` | | +| `ETIMEDOUT` | `NNG_ETIMEDOUT` | | +| `ECONNREFUSED` | `NNG_ECONNREFUSED` | | +| `EBADF` | `NNG_ECLOSED`, `NNG_ECANCELED` | Canceling an operation returns differently than using an invalid or closed object. | +| `EAGAIN` | `NNG_EAGAIN` | +| `ENOTSUP` | `NNG_ENOTSUP` | +| `EADDRINUSE` | `NNG_EADDRINUSE` | +| `EFSM` | `NNG_ESTATE` | Not a legal POSIX _errno_ value. | +| `ENOENT` | `NNG_ENOENT` | +| `EPROTO` | `NNG_EPROTO` | +| `EHOSTUNREACH` | `NNG_EUNREACHABLE` | +| `EACCCES` | `NNG_EPERM`, `NNG_EWRITEONLY`, `NNG_EREADONLY`, `NNG_ECRYPTO`, `NNG_EPEERAUTH` | NNG has more fine grained reasons for access failures. | +| `EMSGSIZE` | `NNG_EMSGSIZE` | +| `ECONNABORTED` | `NNG_ECONNABORTED` | +| `ECONNRESET` | `NNG_ECONNRESET` | +| `EEXIST` | `NNG_EEXIST` | +| `EMFILE` | `NNG_ENOFILES` | +| `ENOSPC` | `NNG_ENOSPC` | diff --git a/docs/migrating/nng1.md b/docs/migrating/nng1.md new file mode 100644 index 000000000..b0afb8885 --- /dev/null +++ b/docs/migrating/nng1.md @@ -0,0 +1,50 @@ +# Migrating from NNG 1.x + +There are some incompatibities from NNG 1.x. +This guide should help in migrating applications to use NNG 2.0. + +## Nanomsg Compatibility + +Applications using the legacy `libnanomsg` API will have to be updated to native NNG interfaces. +See the [Migration Guide for libnanomsg](nanomsg.md) for details. + +## Transport Specific Functions + +Transports have not needed to be registered for a long time now, +and the functions for doing so have been removed. These functions +can be simply removed from your application: + +- `nng_inproc_register` +- `nng_ipc_register` +- `nng_tls_register` +- `nng_tcp_register` +- `nng_ws_register` +- `nng_wss_register` +- `nng_zt_register` + +Additionally, the header files containing these functions have been removed, such as +`nng/transport/ipc/ipc.h`. Simply remove `#include` references to those files. + +(Special exception: The options for ZeroTier are still located in the +`nng/transport/zerotier/zerotier.h`.) + +The `NNG_OPT_WSS_REQUEST_HEADERS` and `NNG_OPT_WSS_RESPONSE_HEADERS` aliases for +`NNG_OPT_WS_OPT_WS_REQUEST_HEADERS` and `NNG_OPT_WS_RESPONSE_HEADERS` have been removed. +Just convert any use of them to `NNG_OPT_WS_REQUST_HEADERS` or +`NNG_OPT_WS_RESPOSNE_HEADERS` as appropriate. + +## Option Functions + +The previously deprecated `nng_pipe_getopt_xxx` family of functions is removed. +Applications should use `nng_pipe_get` and related functions instead. + +The socket option function families for `nng_getopt` and `nng_setopt` have been removed as well. +In this case, use the `nng_socket_get` and `nng_socket_set` functions as appropriate. + +## Transport Options + +A number of transport options can no longer be set on the socket. Instead these +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. From f19bfc8ae05c753881b6df0ecd0a0046933bbb45 Mon Sep 17 00:00:00 2001 From: Garrett D'Amore Date: Sun, 6 Oct 2024 12:19:35 -0700 Subject: [PATCH 013/222] Fix link to migrating --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index c7d7f8e5b..e3be30eda 100644 --- a/README.md +++ b/README.md @@ -184,7 +184,7 @@ These are located in the `demo` directory. ## Legacy Compatibility Migration from `libnanomsg` APIs is fairly straight-forward for most applications. -A [migration guide](docs/migration/nanomsg.md) is available to assist. +A [migration guide](docs/migrating/nanomsg) is available to assist. ## Commercial Support From 016b500b8779c5012120a74019e8119a2c265059 Mon Sep 17 00:00:00 2001 From: Garrett D'Amore Date: Sun, 6 Oct 2024 12:21:19 -0700 Subject: [PATCH 014/222] More link fixes --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index e3be30eda..ac383b4ef 100644 --- a/README.md +++ b/README.md @@ -12,7 +12,7 @@ This is NNG repo of NanoMQ project. I have updated it to support MQTT protocol. [![MIT License](https://img.shields.io/github/license/nanomsg/nng.svg?logoColor=silver&logo=open-source-initiative&label=&color=blue)](https://github.com/nanomsg/nng/blob/dev2.0/LICENSE.txt) [![Latest Version](https://img.shields.io/github/v/tag/nanomsg/nng.svg?logo=github&label=)](https://github.com/nanomsg/nng/releases) -Please see [here](UKRAINE) for an important message for the people of Russia. +Please see [here](UKRAINE.md) for an important message for the people of Russia. > [!NOTE] > This is the development branch for NNG. @@ -184,7 +184,7 @@ These are located in the `demo` directory. ## Legacy Compatibility Migration from `libnanomsg` APIs is fairly straight-forward for most applications. -A [migration guide](docs/migrating/nanomsg) is available to assist. +A [migration guide](docs/migrating/nanomsg.md) is available to assist. ## Commercial Support From 194035cbfb64e769e924670aebaec4db8fa4a12f Mon Sep 17 00:00:00 2001 From: Garrett D'Amore Date: Sun, 6 Oct 2024 13:23:08 -0700 Subject: [PATCH 015/222] Convert CoC to markdown --- CODE_OF_CONDUCT.adoc => CODE_OF_CONDUCT.md | 36 +++++++++++----------- 1 file changed, 18 insertions(+), 18 deletions(-) rename CODE_OF_CONDUCT.adoc => CODE_OF_CONDUCT.md (77%) diff --git a/CODE_OF_CONDUCT.adoc b/CODE_OF_CONDUCT.md similarity index 77% rename from CODE_OF_CONDUCT.adoc rename to CODE_OF_CONDUCT.md index 771f4d7ed..c6a313888 100644 --- a/CODE_OF_CONDUCT.adoc +++ b/CODE_OF_CONDUCT.md @@ -1,6 +1,6 @@ -= NNG Code of Conduct +# NNG Code of Conduct -== Our Pledge +## Our Pledge In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to making participation in our project and @@ -10,29 +10,29 @@ experience, nationality, personal appearance, race, religion, or sexual identity and orientation. -== Our Standards +## Our Standards Examples of behavior that contributes to creating a positive environment include: -* Using welcoming and inclusive language -* Being respectful of differing viewpoints and experiences -* Gracefully accepting constructive criticism -* Focusing on what is best for the community -* Showing empathy towards other community members +- Using welcoming and inclusive language +- Being respectful of differing viewpoints and experiences +- Gracefully accepting constructive criticism +- Focusing on what is best for the community +- Showing empathy towards other community members Examples of unacceptable behavior by participants include: -* The use of sexualized language or imagery and unwelcome sexual attention or +- The use of sexualized language or imagery and unwelcome sexual attention or advances -* Trolling, insulting/derogatory comments, and personal or political attacks -* Public or private harassment -* Publishing others' private information, such as a physical or electronic +- Trolling, insulting/derogatory comments, and personal or political attacks +- Public or private harassment +- Publishing others' private information, such as a physical or electronic address, without explicit permission -* Other conduct which could reasonably be considered inappropriate in a +- Other conduct which could reasonably be considered inappropriate in a professional setting -== Our Responsibilities +## Our Responsibilities Project maintainers are responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective action in @@ -44,7 +44,7 @@ that are not aligned to this Code of Conduct, or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful. -== Scope +## Scope This Code of Conduct applies both within project spaces and in public spaces when an individual is representing the project or its community. Examples of @@ -53,7 +53,7 @@ address, posting via an official social media account, or acting as an appointed representative at an online or offline event. Representation of a project may be further defined and clarified by project maintainers. -== Enforcement +## Enforcement Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team at garrett@damore.org. All @@ -67,8 +67,8 @@ Project maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of the project's leadership. -== Attribution +## Attribution This Code of Conduct is adapted from the -https://www.contributor-convent.org[Contributor Covenant], version 1.4, +[Contributor Covenant](https://www.contributor-convent.org), version 1.4, available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html From 2d37c1ae77531f0eab12ff88a6c9bb2090d5f296 Mon Sep 17 00:00:00 2001 From: Garrett D'Amore Date: Sat, 7 Sep 2024 10:05:27 -0700 Subject: [PATCH 016/222] Remove the documentation for 3compat. --- docs/man/CMakeLists.txt | 29 ---- docs/man/man3compat.desc | 13 -- docs/man/man3compat.sect | 1 - docs/man/nn_allocmsg.3compat.adoc | 67 -------- docs/man/nn_bind.3compat.adoc | 68 -------- docs/man/nn_close.3compat.adoc | 51 ------ docs/man/nn_cmsg.3compat.adoc | 78 --------- docs/man/nn_connect.3compat.adoc | 67 -------- docs/man/nn_device.3compat.adoc | 59 ------- docs/man/nn_errno.3compat.adoc | 79 --------- docs/man/nn_freemsg.3compat.adoc | 49 ------ docs/man/nn_get_statistic.3compat.adoc | 46 ----- docs/man/nn_getsockopt.3compat.adoc | 228 ------------------------- docs/man/nn_poll.3compat.adoc | 102 ----------- docs/man/nn_reallocmsg.3compat.adoc | 59 ------- docs/man/nn_recv.3compat.adoc | 75 -------- docs/man/nn_recvmsg.3compat.adoc | 99 ----------- docs/man/nn_send.3compat.adoc | 74 -------- docs/man/nn_sendmsg.3compat.adoc | 107 ------------ docs/man/nn_setsockopt.3compat.adoc | 205 ---------------------- docs/man/nn_shutdown.3compat.adoc | 55 ------ docs/man/nn_socket.3compat.adoc | 78 --------- docs/man/nn_strerror.3compat.adoc | 47 ----- docs/man/nn_term.3compat.adoc | 59 ------- docs/man/nng_compat.3compat.adoc | 214 ----------------------- 25 files changed, 2009 deletions(-) delete mode 100644 docs/man/man3compat.desc delete mode 100644 docs/man/man3compat.sect delete mode 100644 docs/man/nn_allocmsg.3compat.adoc delete mode 100644 docs/man/nn_bind.3compat.adoc delete mode 100644 docs/man/nn_close.3compat.adoc delete mode 100644 docs/man/nn_cmsg.3compat.adoc delete mode 100644 docs/man/nn_connect.3compat.adoc delete mode 100644 docs/man/nn_device.3compat.adoc delete mode 100644 docs/man/nn_errno.3compat.adoc delete mode 100644 docs/man/nn_freemsg.3compat.adoc delete mode 100644 docs/man/nn_get_statistic.3compat.adoc delete mode 100644 docs/man/nn_getsockopt.3compat.adoc delete mode 100644 docs/man/nn_poll.3compat.adoc delete mode 100644 docs/man/nn_reallocmsg.3compat.adoc delete mode 100644 docs/man/nn_recv.3compat.adoc delete mode 100644 docs/man/nn_recvmsg.3compat.adoc delete mode 100644 docs/man/nn_send.3compat.adoc delete mode 100644 docs/man/nn_sendmsg.3compat.adoc delete mode 100644 docs/man/nn_setsockopt.3compat.adoc delete mode 100644 docs/man/nn_shutdown.3compat.adoc delete mode 100644 docs/man/nn_socket.3compat.adoc delete mode 100644 docs/man/nn_strerror.3compat.adoc delete mode 100644 docs/man/nn_term.3compat.adoc delete mode 100644 docs/man/nng_compat.3compat.adoc diff --git a/docs/man/CMakeLists.txt b/docs/man/CMakeLists.txt index eac11bab7..63c87f799 100644 --- a/docs/man/CMakeLists.txt +++ b/docs/man/CMakeLists.txt @@ -196,31 +196,6 @@ if (NNG_ENABLE_DOC) nng_zt_register ) - set(NNG_MAN3COMPAT - nn_allocmsg - nn_bind - nn_close - nn_cmsg - nn_connect - nn_device - nn_errno - nn_freemsg - nn_get_statistic - nn_getsockopt - nn_poll - nn_reallocmsg - nn_recv - nn_recvmsg - nn_send - nn_sendmsg - nn_setsockopt - nn_shutdown - nn_socket - nn_strerror - nn_term - nng_compat - ) - set(NNG_MAN3HTTP nng_http_client_alloc nng_http_client_connect @@ -411,10 +386,6 @@ if (NNG_ENABLE_DOC) nng_man(${F} 3) endforeach () - foreach (F ${NNG_MAN3COMPAT}) - nng_man(${F} 3compat) - endforeach () - foreach (F ${NNG_MAN3HTTP}) nng_man(${F} 3http) endforeach () diff --git a/docs/man/man3compat.desc b/docs/man/man3compat.desc deleted file mode 100644 index 2b0b4b3ff..000000000 --- a/docs/man/man3compat.desc +++ /dev/null @@ -1,13 +0,0 @@ -This section documents the _nanomsg_ 1.0 libary compatible functions. - -These functions are provided as a transition aid, for application -developers coming to _NNG_ from _libnanomsg_, and are discouraged -from use in new applications. - -TIP: While this is discouraged for long term use, as a transition aid -applications may use the value returned by the -xref:nng_socket_id.3.adoc[`nng_socket_id()`] in these functions just like a -socket descriptor (as if the socket were opened via -xref:nn_socket.3compat.adoc[`nn_socket()`]). -This sort of API intermixing should only be used during transition from -the legacy API to the new API. diff --git a/docs/man/man3compat.sect b/docs/man/man3compat.sect deleted file mode 100644 index 75a97a08c..000000000 --- a/docs/man/man3compat.sect +++ /dev/null @@ -1 +0,0 @@ -Compatible Library Functions diff --git a/docs/man/nn_allocmsg.3compat.adoc b/docs/man/nn_allocmsg.3compat.adoc deleted file mode 100644 index a53da55cf..000000000 --- a/docs/man/nn_allocmsg.3compat.adoc +++ /dev/null @@ -1,67 +0,0 @@ -= nn_allocmsg(3compat) -// -// Copyright 2018 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nn_allocmsg - allocate message (compatible API) - -== SYNOPSIS - -[source,c] ----- -#include - -void *nn_allocmsg(size_t size, int type); ----- - -== DESCRIPTION - -The `nn_allocmsg()` allocates a message structure of size _size_, and is -primarily used to support zero-copy send operations, making use of the -`NNG_MSG` special size indicator. -The value returned is a pointer to the start of the message payload buffer. - -The value of _size_ must be positive, and small enough to hold reasonable -message data plus book-keeping information. - -NOTE: This function is provided for API -xref:nng_compat.3compat.adoc[compatibility] with legacy _libnanomsg_. -Consider using the relevant xref:libnng.3.adoc[modern API] instead. - -The value of _type_ *must* be zero. -(This argument was reserved to support different kinds of memory spaces -for RDMA devices, but this was never developed in the legacy API.) - -The returned message must be disposed of by either -xref:nn_freemsg.3compat.adoc[`nn_freemsg()`] or -xref:nn_send.3compat.adoc[`nn_send()`] when the caller is finished with it. - -== RETURN VALUES - -This function returns a pointer to message buffer space, or `NULL` -on failure. - -== ERRORS - -[horizontal] -`ENOMEM`:: Insufficient memory is available. -`EINVAL`:: An invalid _size_ or _type_ was specified. -`ETERM`:: The library is shutting down. - -== SEE ALSO - -[.text-left] -xref:nn_errno.3compat.adoc[nn_errno(3compat)], -xref:nn_freemsg.3compat.adoc[nn_freemsg(3compat)], -xref:nn_reallocmsg.3compat.adoc[nn_reallocmsg(3compat)], -xref:nn_send.3compat.adoc[nn_send(3compat)], -xref:nng_compat.3compat.adoc[nng_compat(3compat)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nn_bind.3compat.adoc b/docs/man/nn_bind.3compat.adoc deleted file mode 100644 index a4ca00433..000000000 --- a/docs/man/nn_bind.3compat.adoc +++ /dev/null @@ -1,68 +0,0 @@ -= nn_bind(3compat) -// -// Copyright 2020 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nn_bind - accept connections from remote peers (compatible API) - -== SYNOPSIS - -[source, c] ----- -#include - -int nn_bind(int sock, const char *url) ----- - -== DESCRIPTION - -The `nn_bind()` function arranges for the socket _sock_ to -accept connections at the address specified by _url_. -An identifier for this socket's association with the _url_ is -returned to the caller on success. -This identfier can be used with -xref:nn_shutdown.3compat.adoc[`nn_shutdown()`] to -remove the association later. - -NOTE: This function is provided for API -xref:nng_compat.3compat.adoc[compatibility] with legacy _libnanomsg_. -Consider using the relevant xref:libnng.3.adoc[modern API] instead. - -NOTE: The bind operation is performed asynchronously, and may not have -completed before this function returns control to the caller. - -IMPORTANT: Only transports supported by legacy _libnanomsg_ may be -used with this function. -In particular, only the schemes `tcp://`, `ipc://`, `inproc://`, and `ws://` are -supported with this function. -(Use the xref:libnng.3.adoc[modern API] to use other schemes.) - -== RETURN VALUES - -This function returns a positive identifier on success, and -1 on error. - -== ERRORS - -[horizontal] -`EADDRINUSE`:: The address specified by _url_ is already in use. -`EADDRNOTAVAIL`:: The address specified by _url_ is not available. -`EBADF`:: The socket _sock_ is not open. -`EINVAL`:: An invalid _url_ was supplied. - -== SEE ALSO - -[.text-left] -xref:nn_connect.3compat.adoc[nn_connect(3compat)], -xref:nn_errno.3compat.adoc[nn_errno(3compat)], -xref:nn_shutdown.3compat.adoc[nn_shutdown(3compat)], -xref:nn_socket.3compat.adoc[nn_socket(3compat)], -xref:nng_compat.3compat.adoc[nn_compat(3compat)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nn_close.3compat.adoc b/docs/man/nn_close.3compat.adoc deleted file mode 100644 index 1970b57d7..000000000 --- a/docs/man/nn_close.3compat.adoc +++ /dev/null @@ -1,51 +0,0 @@ -= nn_close(3compat) -// -// Copyright 2018 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nn_close - close socket (compatible API) - -== SYNOPSIS - -[source,c] ----- -#include - -int nn_close(int sock); ----- - -== DESCRIPTION - -The `nn_close()` function closes the socket _sock_. -Any operations that are currently in progress will be terminated, and will -fail with error `EBADF`. - -NOTE: This function is provided for API -xref:nng_compat.3compat.adoc[compatibility] with legacy _libnanomsg_. -Consider using the relevant xref:libnng.3.adoc[modern API] instead. - -== RETURN VALUES - -This function returns zero on success, and -1 on failure. - -== ERRORS - -[horizontal] -`EBADF`:: The socket is not open. -`ETERM`:: The library is shutting down. - -== SEE ALSO - -[.text-left] -xref:nn_errno.3compat.adoc[nn_errno(3compat)], -xref:nn_socket.3compat.adoc[nn_socket(3compat)], -xref:nng_compat.3compat.adoc[nng_compat(3compat)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nn_cmsg.3compat.adoc b/docs/man/nn_cmsg.3compat.adoc deleted file mode 100644 index 32d318106..000000000 --- a/docs/man/nn_cmsg.3compat.adoc +++ /dev/null @@ -1,78 +0,0 @@ -= nn_cmsg(3compat) -// -// Copyright 2018 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nn_cmsg - message control data (compatible API) - -== SYNOPSIS - -[source,c] ----- -#include - -struct nn_cmsghdr { - size_t cmsg_len; - int cmsg_level; - int cmsg_type; -}; ----- - -== DESCRIPTION - -The `nn_cmsghdr` structure describes a block of control data that is -associated with a message either sent by xref:nn_sendmsg.3compat.adoc[`nn_sendmsg()`] -or received by xref:nn_recvmsg.3compat.adoc[`nn_recvmsg()`]. - -NOTE: This structure and supporting macros are provided for API -xref:nng_compat.3compat.adoc[compatibility] with legacy _libnanomsg_. -Consider using the relevant xref:libnng.3.adoc[modern API] instead. - -Each header is followed by `cmsg_len` bytes of data, plus any padding required -to align the structure. - -The only defined ancillary data at this time is the protocol headers used by -the protocols. -This uses `cmsg_level` set to `PROTO_SP` and the `cmsg_type` set to -`SP_HDR`. -The actual data for this will vary from depending on the protocol used. - -Convenience macros are provided to make working with these fields easier. - -`struct nn_cmsghdr *NN_CMSG_FIRSTHDR(struct nn_msghdr *__hdr__)`:: -This macro returns the first `struct nn_cmsghdr` header in _hdr_. - -`struct nn_cmsghdr *NN_CMSG_NXTHDR(struct nn_msghdr *__hdr__, struct nn_cmsghdr *__ch__)`:: -This macro returns a pointer to the next `struct nn_cmsghdr` in _hdr_ after _ch_. - -`void *NN_CMSG_DATA(struct nn_cmsghdr *__ch__)`:: -This macro returns a pointer to the header-specific data for _ch_. - -`size_t NN_CMSG_ALIGN(size_t __len__)`:: -This macro returns the length specified by _len_, plus any padding required to -provide the necessary alignment for another structure. - -`size_t NN_CMSG_SPACE(size_t __len__)`:: -This macro returns the amount of space required for a header, with _len_ -bytes of following data, and any necessary padding. - -`size_t NN_CMSG_LEN(size_t __len__)`:: -This macro evaluates to the length of the header (including alignment), -and the associated data of length _len_, but without any trailing padding -to align for another header. - -== SEE ALSO - -[.text-left] -xref:nn_recvmsg.3compat.adoc[nn_recvmsg(3compat)], -xref:nn_sendmsg.3compat.adoc[nn_sendmsg(3compat)], -xref:nng_compat.3compat.adoc[nng_compat(3compat)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nn_connect.3compat.adoc b/docs/man/nn_connect.3compat.adoc deleted file mode 100644 index e498f8d3d..000000000 --- a/docs/man/nn_connect.3compat.adoc +++ /dev/null @@ -1,67 +0,0 @@ -= nn_connect(3compat) -// -// Copyright 2018 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nn_connect - connect to remote peer (compatible API) - -== SYNOPSIS - -[source, c] ----- -#include - -int nn_connect(int sock, const char *url) ----- - -== DESCRIPTION - -The `nn_connect()` function arranges for the socket _sock_ to -initiate connection to a peer at the address specified by _url_. -An identifier for this socket's association with the _url_ is -returned to the caller on success. -This identifier can be used with -xref:nn_shutdown.3compat.adoc[`nn_shutdown()`] to -remove the association later. - -NOTE: This function is provided for API -xref:nng_compat.3compat.adoc[compatibility] with legacy _libnanomsg_. -Consider using the relevant xref:libnng.3.adoc[modern API] instead. - -NOTE: The connect operation is performed asynchronously, and may not have -completed before this function returns control to the caller. - -IMPORTANT: Only transports supported by legacy _libnanomsg_ may be -used with this function. -In particular, only the schemes `tcp://`, `ipc://`, `inproc://`, and `ws://` are -supported with this function. -(Use the xref:libnng.3.adoc[modern API] to use other schemes.) - -== RETURN VALUES - -This function returns a positive identifier success, and -1 on error. - -== ERRORS - -[horizontal] -`ECONNREFUSED`:: The connection attempt was refused. -`EBADF`:: The socket _sock_ is not open. -`EINVAL`:: An invalid _url_ was supplied. - -== SEE ALSO - -[.text-left] -xref:nn_bind.3compat.adoc[nn_bind(3compat)], -xref:nn_errno.3compat.adoc[nn_errno(3compat)], -xref:nn_shutdown.3compat.adoc[nn_shutdown(3compat)], -xref:nn_socket.3compat.adoc[nn_socket(3compat)], -xref:nng_compat.3compat.adoc[nn_compat(3compat)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nn_device.3compat.adoc b/docs/man/nn_device.3compat.adoc deleted file mode 100644 index c69e1e046..000000000 --- a/docs/man/nn_device.3compat.adoc +++ /dev/null @@ -1,59 +0,0 @@ -= nn_device(3compat) -// -// Copyright 2018 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nn_device - create forwarding device (compatible API) - -== SYNOPSIS - -[source,c] ----- -#include - -int nn_device(int sock1, int sock2); ----- - -== DESCRIPTION - -The `nn_device()` function is used to create a forwarder, where messages -received on one of the two sockets _sock1_ and _sock2_ are forwarded to -the other. - -NOTE: This function is provided for API -xref:nng_compat.3compat.adoc[compatibility] with legacy _libnanomsg_. -Consider using the relevant xref:libnng.3.adoc[modern API] instead. - -The two sockets must be compatible, and must be -xref:nng.7.adoc#raw_mode[raw mode] -sockets. -More detail about devices and how they can be used is available in the -new style xref:nng_device.3.adoc[nng_device()] documentation. - -== RETURN VALUES - -This function blocks forever, and will return -1 only when -one of the sockets is closed or an error occurs. - -== ERRORS - -[horizontal] -`EBADF`:: One of the two sockets is invalid or not open, or has -`EINVAL`:: The sockets are not compatible with each other, or not both raw. -`ENOMEM`:: Insufficient memory is available. - -== SEE ALSO - -[.text-left] -xref:nn_errno.3compat.adoc[nn_errno(3compat)], -xref:nn_socket.3compat.adoc[nn_socket(3compat)], -xref:nng_compat.3compat.adoc[nng_compat(3compat)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nn_errno.3compat.adoc b/docs/man/nn_errno.3compat.adoc deleted file mode 100644 index a048543df..000000000 --- a/docs/man/nn_errno.3compat.adoc +++ /dev/null @@ -1,79 +0,0 @@ -= nn_errno(3compat) -// -// Copyright 2018 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nn_errno - return most recent error (compatible API) - -== SYNOPSIS - -[source,c] ----- -#include - -int nn_errno(void); ----- - -== DESCRIPTION - -The `nn_errno()` function returns the error number corresponding to the -most recent failed operation by the calling thread. - -NOTE: This function is provided for API -xref:nng_compat.3compat.adoc[compatibility] with legacy _libnanomsg_. -Consider using the relevant xref:libnng.3.adoc[modern API] instead. - -IMPORTANT: The error numbers returned from this function may include -errors caused by system functions, which overlap the usual `errno` variable, -and this function simply returns the value of `errno`. -However, the values returned may include numeric values that are not -defined by the system, but are unique to _libnanomsg_, such as `EFSM`. - -This library implements the following error numbers, in addition to any others -that might be set for `errno` by the underlying system: - - -== RETURN VALUES - -This function returns the value of `errno`. -If no operation has failed, then this will be zero. - -== ERRORS - -[horizontal] -`EINTR`:: Operation interrupted. -`ENOMEM`:: Insufficient memory. -`EINVAL`:: Invalid argument. -`EBUSY`:: Resource is busy. -`ETIMEDOUT`:: Operation timed out. -`ECONNREFUSED`:: Connection refused by peer. -`EBADF`:: Invalid or closed socket. -`EAGAIN`:: Operation would block. -`ENOTSUP`:: Protocol or option not supported. -`EADDRINUSE`:: Requested address is already in use. -`EFSM`:: Protocol state incorrect. -`EPROTO`:: Protocol error. -`EHOSTUNREACH`:: Remote peer is unreachable. -`EADDRNOTAVAIL`:: Requested address is not available. -`EACCES`:: Permission denied. -`EMSGSIZE`:: Message is too large. -`ECONNABORTED`:: Connection attempt aborted. -`ECONNRESET`:: Connection reset by peer. -`EEXIST`:: Resource already exists. -`EMFILE`:: Too many open files. -`ENOSPC`:: Insufficient persistent storage. - -== SEE ALSO - -[.text-left] -xref:nn_strerror.3compat.adoc[nn_strerror(3compat)], -xref:nng_compat.3compat.adoc[nng_compat(3compat)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nn_freemsg.3compat.adoc b/docs/man/nn_freemsg.3compat.adoc deleted file mode 100644 index 61127c3d4..000000000 --- a/docs/man/nn_freemsg.3compat.adoc +++ /dev/null @@ -1,49 +0,0 @@ -= nn_freemsg(3compat) -// -// Copyright 2018 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nn_freemsg - free message (compatible API) - -== SYNOPSIS - -[source,c] ----- -#include - -int nn_freemsg(void *msg); ----- - -== DESCRIPTION - -The `nn_freemsg()` deallocates a message previously allocated with -xref:nn_allocmsg.3compat.adoc[`nn_allocmsg()`] or similar functions. - -NOTE: This function is provided for API -xref:nng_compat.3compat.adoc[compatibility] with legacy _libnanomsg_. -Consider using the relevant xref:libnng.3.adoc[modern API] instead. - -== RETURN VALUES - -This function always returns 0. - -== ERRORS - -None. - -== SEE ALSO - -[.text-left] -xref:nn_allocmsg.3compat.adoc[nn_allocmsg(3compat)], -xref:nn_freemsg.3compat.adoc[nn_freemsg(3compat)], -xref:nn_errno.3compat.adoc[nn_errno(3compat)], -xref:nng_compat.3compat.adoc[nng_compat(3compat)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nn_get_statistic.3compat.adoc b/docs/man/nn_get_statistic.3compat.adoc deleted file mode 100644 index 89b11de2b..000000000 --- a/docs/man/nn_get_statistic.3compat.adoc +++ /dev/null @@ -1,46 +0,0 @@ -= nn_get_statistic(3compat) -// -// Copyright 2018 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nn_get_statistic - get statistic (stub) - -== SYNOPSIS - -[source,c] ----- -#include - -uint64_t nn_get_statistic(int sock, int stat); ----- - -== DESCRIPTION - -The `nn_get_statistic()` function exists only as a stub, and always returns -zero. - -NOTE: This function is provided for API -xref:nng_compat.3compat.adoc[compatibility] with legacy _libnanomsg_. -Consider using the relevant xref:libnng.3.adoc[modern API] instead. - -== RETURN VALUES - -Zero. - -== ERRORS - -None. - -== SEE ALSO - -[.text-left] -xref:nng_compat.3compat.adoc[nng_compat(3compat)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nn_getsockopt.3compat.adoc b/docs/man/nn_getsockopt.3compat.adoc deleted file mode 100644 index 0c476cca4..000000000 --- a/docs/man/nn_getsockopt.3compat.adoc +++ /dev/null @@ -1,228 +0,0 @@ -= nn_getsockopt(3compat) -// -// Copyright 2018 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nn_getsockopt - get socket option (compatible API) - -== SYNOPSIS - -[source,c] ----- -#include - -int nn_getsockopt(int sock, int level, int option, void *val, size_t *szp); ----- - -== DESCRIPTION - -The `nn_getsockopt()` function gets a socket option on socket _sock_. -The option retrieved is determined by the _level_ and _option_. - -NOTE: This function is provided for API -xref:nng_compat.3compat.adoc[compatibility] with legacy _libnanomsg_. -Consider using the relevant xref:libnng.3.adoc[modern API] instead. - -The value pointed to by _szp_ must be initialized to the size of the buffer -pointed to by _val_. -No more than this many bytes of the option will be copied into the destination -buffer on success. -On success, the value pointed to by _szp_ will be updated with the actual -size of the option. - -TIP: To determine the size to receive an option, first call this function -with _val_ set to `NULL` and the value addressed by _szp_ initialized to zero. - -The _level_ determines whether the option is a generic socket option, -or is transport-specific. -The values possible for level are as follows: - -[horizontal] -`NN_SOL_SOCKET`:: Generic socket option -`NN_IPC`:: Transport specific option for IPC. -`NN_TCP`:: Transport specific option for TCP. -`NN_WS`:: Transport specific option for WebSocket. - -The following generic socket options are possible (all are of type `int` and -thus size 4, unless otherwise indicated.) - -`NN_SNDBUF`:: -Send buffer size in bytes. - -NOTE: In _NNG_ buffers are sized as a count of messages rather than -bytes; accordingly this value is the queue depth multiplied by 1024 -(representing an estimate that the average message size is 1kB). -Applications that have unusual message sizes may wish to adjust the value -used here accordingly. - -`NN_RCVBUF`:: -Receive buffer size in bytes. - -NOTE: The same caveats for `NN_SNDBUF` apply here as well. - -`NN_SNDTIMEO`:: -Send time-out in milliseconds. -Send operations will fail with `ETIMEDOUT` if no message can be received -after this many milliseconds have transpired since the operation was started. -A value of -1 means that no timeout is applied. - -`NN_RCVTIMEO`:: -Receive time-out in milliseconds. -Receive operations will fail with `ETIMEDOUT` if no message can be received -after this many milliseconds have transpired since the operation was started. -A value of -1 means that no timeout is applied. - -`NN_RCVMAXSIZE`:: -Maximum receive size in bytes. -The socket will discard messages larger than this on receive. -The default, 1MB, is intended to prevent denial-of-service attacks. -The value -1 removes any limit. - -`NN_RECONNECT_IVL`:: -Reconnect interval in milliseconds. -After an outgoing connection is closed or fails, the socket will -automatically attempt to reconnect after this many milliseconds. -This is the starting value for the time, and is used in the first -reconnection attempt after a successful connection is made. -The default is 100. - -`NN_RECONNECT_IVL_MAX`:: -Maximum reconnect interval in milliseconds. -Subsequent reconnection attempts after a failed attempt are made at -exponentially increasing intervals (back-off), but the interval is -capped by this value. -If this value is smaller than `NN_RECONNECT_IVL`, then no exponential -back-off is performed, and each reconnect interval will be determined -solely by `NN_RECONNECT_IVL`. -The default is zero. - -`NN_LINGER`:: -This option is always zero and exists only for compatibility. - -NOTE: This option was unreliable in early releases of _libnanomsg_, and -is unsupported in _NNG_ and recent _libnanomsg_ releases. -Applications needing assurance of message delivery should either include an -explicit notification (automatic with the `NN_REQ` protocol) or allow -sufficient time for the socket to drain before closing the socket or exiting. - - -`NN_SNDPRIO`:: -This option is not implemented at this time. - -`NN_RCVPRIO`:: -This option is not implemented at this time. - -`NN_IPV4ONLY`:: -This option is not implemented at this time. - -`NN_SOCKET_NAME`:: -This option is a string, and represents the socket name. -It can be changed to help with identifying different sockets with -their different application-specific purposes. - -`NN_MAXTTL`:: -Maximum number of times a message may traverse devices or proxies. -This value, if positive, provides some protection against forwarding loops in -xref:nng_device.3.adoc[device] chains. - -NOTE: Not all protocols offer this protection, so care should still be used -in configuring device forwarding. - -`NN_DOMAIN`:: -This option of type `int` represents either the value `AF_SP` or `AF_SP_RAW`, -corresponding to the value that the socket was created with. - -`NN_PROTOCOL`:: -This option option of type `int` contains the numeric protocol number -that the socket is used with. - -`NN_RCVFD`:: -This option returns a file descriptor suitable for use in with `poll()` or -`select()` (or other system-specific polling functions). -This descriptor will be readable when a message is available for receiving -at the socket. -This option is of type `int` on all systems except Windows, where it is of -type `SOCKET`. - -NOTE: The file descriptor should not be read or written by the application, -and is not the same as any underlying descriptor used for network sockets. - -`NN_SNDFD`:: -This option returns a file descriptor suitable for use in with `poll()` or -`select()` (or other system-specific polling functions). -This descriptor will be readable when the socket is able to accept a message -for sending. -This option is of type `int` on all systems except Windows, where it is of -type `SOCKET`. - -NOTE: The file descriptor should not be read or written by the application, -and is not the same as any underlying descriptor used for network sockets. -Furthermore, the file descriptor should only be polled for _readability_. - -The following option is available for `NN_REQ` sockets -using the `NN_REQ` level: - -`NN_REQ_RESEND_IVL`:: -Request retry interval in milliseconds. -If an `NN_REQ` socket does not receive a reply to a request within this -period of time, the socket will automatically resend the request. -The default value is 60000 (one minute). - -The following option is available for `NN_SURVEYOR` sockets -using the `NN_SURVEYOR` level: - -`NN_SURVEYOR_DEADLINE`:: -Survey deadline in milliseconds for `NN_SURVEYOR` sockets. -After sending a survey message, the socket will only accept responses -from respondents for this long. -Any responses arriving after this expires are silently discarded. - -In addition, the following transport specific options are offered: - -`NN_IPC_SEC_ATTR`:: -This `NN_IPC` option is not supported at this time. - -`NN_IPC_OUTBUFSZ`:: -This `NN_IPC` option is not supported at this time. - -`NN_IPC_INBUFSZE`:: -This `NN_IPC` option is not supported at this time. - -`NN_TCP_NODELAY`:: -This `NN_TCP` option is not supported at this time. - -`NN_WS_MSG_TYPE`:: -This `NN_WS` option is not supported, as _NNG_ only supports binary messages -in this implementation. - -== RETURN VALUES - -This function returns zero on success, and -1 on failure. - -== ERRORS - -[horizontal] -`EBADF`:: The socket _sock_ is not an open socket. -`ENOMEM`:: Insufficient memory is available. -`ENOPROTOOPT`:: The level and/or option is invalid. -`EINVAL`:: The option, or the value passed, is invalid. -`ETERM`:: The library is shutting down. -`EACCES`:: The option cannot be changed. - -== SEE ALSO - -[.text-left] -xref:nng_socket.5.adoc[nng_socket(5)], -xref:nn_close.3compat.adoc[nn_close(3compat)], -xref:nn_errno.3compat.adoc[nn_errno(3compat)], -xref:nn_getsockopt.3compat.adoc[nn_getsockopt(3compat)], -xref:nng_compat.3compat.adoc[nng_compat(3compat)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nn_poll.3compat.adoc b/docs/man/nn_poll.3compat.adoc deleted file mode 100644 index c115fe49f..000000000 --- a/docs/man/nn_poll.3compat.adoc +++ /dev/null @@ -1,102 +0,0 @@ -= nn_poll(3compat) -// -// Copyright 2018 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nn_poll - poll sockets (compatible API) - -== SYNOPSIS - -[source, c] ----- -#include - -#define NN_POLLIN 1 -#define NN_POLLOUT 2 - -struct nn_pollfd { - int fd; - uint16_t events; - uint16_t revents; -}; - -int nn_poll(struct nn_pollfd *pfds, int npfd, int timeout); ----- - -== DESCRIPTION - -The `nn_poll()` function polls a group of sockets for readiness to send or receive. - -NOTE: This function is provided for API -xref:nng_compat.3compat.adoc[compatibility] with legacy _libnanomsg_. -Consider using the relevant xref:libnng.3.adoc[modern API] instead. - -The array of _nfds_ sockets to poll for are passed into _pfds_. -Each member of this array is initialized with the `fd` field set to -the socket, and the `events` field set to a mask that can contain either or both -of the flags `NN_POLLIN` and `NN_POLLOUT`. - -The flag `NN_POLLIN` indicates that a socket is ready for receiving without -blocking (a message is available on the socket), and the flag `NN_POLLOUT` -indicates that a socket is ready for sending without blocking. - -Upon success, the function returns the number of updates the `revents` -field of each member of the _pfds_ array, setting it to indicate -whether the requested status is true or not. - -NOTE: The `revents` field will only have a flag set if the corresponding -flag was also set in the `events` field. - -If the _timeout_ field is positive, then this function will wait for -up the that many milliseconds. -If none of the requested events occurs before that timeout occurs, then -the function will return -1 and set the error to `ETIMEDOUT`. - -If the _timeout_ is zero, then this function will return immediately, -after updating the current status of the sockets. - -If the _timeout_ is -1, then the function waits forever, or until one of the -requested events occurs. - -IMPORTANT: This function is only suitable for use with sockets obtained with the -xref:nn_socket.3compat.adoc[`nn_socket()`] function, and is not compatible -with file descriptors obtained via any other means. -This includes file descriptors obtained using the `NN_SNDFD` or `NN_RCVFD` -options with xref:nn_getsockopt.3compat.adoc[`nn_getsockopt()`] - -NOTE: This function is significantly less efficient than other polling -or asynchronous I/O mechanisms, and is provided for API compatibility only. -It's use is discouraged. - -NOTE: This function is *not* supported on systems other than POSIX derived -platforms and Windows. - -== RETURN VALUES - -This function returns the number of sockets with events on success, or -1 on error. - -== ERRORS - -[horizontal] -`ENOMEM`:: Insufficient memory available. -`EBADF`:: One of the sockets is not open. -`ETIMEDOUT`:: Operation timed out. -`ENOTSUP`:: This function is not supported on this platform. - -== SEE ALSO - -[.text-left] -xref:nn_errno.3compat.adoc[nn_errno(3compat)], -xref:nn_recv.3compat.adoc[nn_recv(3compat)], -xref:nn_send.3compat.adoc[nn_send(3compat)], -xref:nn_socket.3compat.adoc[nn_socket(3compat)], -xref:nng_compat.3compat.adoc[nn_compat(3compat)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nn_reallocmsg.3compat.adoc b/docs/man/nn_reallocmsg.3compat.adoc deleted file mode 100644 index d48b5d403..000000000 --- a/docs/man/nn_reallocmsg.3compat.adoc +++ /dev/null @@ -1,59 +0,0 @@ -= nn_reallocmsg(3compat) -// -// Copyright 2018 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nn_reallocmsg - reallocate message (compatible API) - -== SYNOPSIS - -[source,c] ----- -#include - -void *nn_reallocmsg(void *old, size_t size); ----- - -== DESCRIPTION - -The `nn_reallocmsg()` reallocates the message _old_, making it of size _size_. - -NOTE: This function is provided for API -xref:nng_compat.3compat.adoc[compatibility] with legacy _libnanomsg_. -Consider using the relevant xref:libnng.3.adoc[modern API] instead. - -On success, the contents of _old_ are copied into the new message -(truncating if appropriate), then _old_ is deallocated, and a pointer -to the new message payload is returned. - -On failure, the _old_ message is unchanged, and the value `NULL` is returned -to the caller. - -== RETURN VALUES - -This function returns a pointer to message buffer space, or `NULL` -on failure. - -== ERRORS - -[horizontal] -`ENOMEM`:: Insufficient memory is available. -`EINVAL`:: An invalid _size_ was specified. -`ETERM`:: The library is shutting down. - -== SEE ALSO - -[.text-left] -xref:nn_allocmsg.3compat.adoc[nn_allocmsg(3compat)], -xref:nn_freemsg.3compat.adoc[nn_freemsg(3compat)], -xref:nn_errno.3compat.adoc[nn_errno(3compat)], -xref:nng_compat.3compat.adoc[nng_compat(3compat)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nn_recv.3compat.adoc b/docs/man/nn_recv.3compat.adoc deleted file mode 100644 index 2a71714de..000000000 --- a/docs/man/nn_recv.3compat.adoc +++ /dev/null @@ -1,75 +0,0 @@ -= nn_recv(3compat) -// -// Copyright 2018 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nn_recv - receive data (compatible API) - -== SYNOPSIS - -[source, c] ----- -#include - -int nn_recv(int sock, void *data, size_t size, int flags) ----- - -== DESCRIPTION - -The `nn_recv()` function receives a message from the socket _sock_. -The message body must fit within _size_ bytes, and will be stored -at the location specified by _data_, unless _size_ is the -special value `NN_MSG`, indicating a zero-copy operation. - -NOTE: This function is provided for API -xref:nng_compat.3compat.adoc[compatibility] with legacy _libnanomsg_. -Consider using the relevant xref:libnng.3.adoc[modern API] instead. - -If _size_ has the special value `NN_MSG`, then a zero-copy operation -is performed. -In this case, instead of copying the message data into the address -specified by _data_, a new message large enough to hold the message data -will be allocated (as if by the -function xref:nn_allocmsg.3compat.adoc[`nn_allocmsg()`]), and the message -payload will be stored accordingly. -In this case, the value stored at _data_ will not be message data, -but a pointer to the message itself. -In this case, on success, the caller shall take responsibility for -the final disposition of the message (such as by sending it to -another peer using xref:nn_send.3compat.adoc[`nn_send()`]) or -xref:nn_freemsg.3compat.adoc[`nn_freemsg()`]. - -The _flags_ field may contain the special flag `NN_DONTWAIT`. -In this case, if the no message is available for immediate receipt, -the operation shall not block, but instead will fail with the error `EAGAIN`. - -== RETURN VALUES - -This function returns the number of bytes sent on success, and -1 on error. - -== ERRORS - -[horizontal] -`EAGAIN`:: The operation would block. -`EBADF`:: The socket _sock_ is not open. -`EFSM`:: The socket cannot receive in this state. -`ENOTSUP`:: This protocol cannot receive. -`ETIMEDOUT`:: Operation timed out. - -== SEE ALSO - -[.text-left] -xref:nn_errno.3compat.adoc[nn_errno(3compat)], -xref:nn_recvmsg.3compat.adoc[nn_recvmsg(3compat)], -xref:nn_send.3compat.adoc[nn_send(3compat)], -xref:nn_socket.3compat.adoc[nn_socket(3compat)], -xref:nng_compat.3compat.adoc[nn_compat(3compat)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nn_recvmsg.3compat.adoc b/docs/man/nn_recvmsg.3compat.adoc deleted file mode 100644 index e0fcc758a..000000000 --- a/docs/man/nn_recvmsg.3compat.adoc +++ /dev/null @@ -1,99 +0,0 @@ -= nn_recvmsg(3compat) -// -// Copyright 2018 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nn_recvmsg - receive message (compatible API) - -== SYNOPSIS - -[source, c] ----- -#include - -int nn_recvmsg(int sock, struct nn_msghdr *hdr, int flags); ----- - -== DESCRIPTION - -The `nn_recvmsg()` function receives a message into the header described by -_hdr_ using the socket _sock_. - -NOTE: This function is provided for API -xref:nng_compat.3compat.adoc[compatibility] with legacy _libnanomsg_. -Consider using the relevant xref:libnng.3.adoc[modern API] instead. - -The _flags_ field may contain the special flag `NN_DONTWAIT`. -In this case, if no message is ready for receiving on _sock_, -the operation shall not block, but instead will fail with the error `EAGAIN`. - -The _hdr_ points to a structure of type `struct nn_msghdr`, which has the -following definition: - -[source, c] ----- -struct nn_iovec { - void * iov_base; - size_t iov_len; -}; - -struct nn_msghdr { - struct nn_iovec *msg_iov; - int msg_iovlen; - void * msg_control; - size_t msg_controllen; -}; ----- - -The `msg_iov` is an array of scatter items, permitting the message -to be spread into different memory blocks. -There are `msg_iovlen` elements in this array, each of which -has the base address (`iov_base`) and length (`iov_len`) indicated. - -The last member of this array may have the `iov_len` field set to `NN_MSG`, -in which case the function shall allocate a message buffer, and store the -pointer to it at the address indicated by `iov_base`. -This can help save an extra copy operation. -The buffer should be deallocated by xref:nn_freemsg.3compat.adoc[`nn_freemsg()`] -or similar when it is no longer needed. - -The values of `msg_control` and `msg_controllen` describe a buffer -of ancillary data associated with the message. -This is currently only useful to obtain the message headers -used with xref:nng.7.adoc#raw_mode[raw mode] sockets. -In all other circumstances these fields should be zero. -Details about this structure are covered in -xref:nn_cmsg.3compat.adoc[`nn_cmsg(3compat)`]. - -== RETURN VALUES - -This function returns the number of bytes received on success, and -1 on error. - -== ERRORS - -[horizontal] -`EAGAIN`:: The operation would block. -`EBADF`:: The socket _sock_ is not open. -`EFSM`:: The socket cannot receive in this state. -`EINVAL`:: The _hdr_ is invalid. -`ENOTSUP`:: This protocol cannot receive. -`ETIMEDOUT`:: Operation timed out. - -== SEE ALSO - -[.text-left] -xref:nn_cmsg.3compat.adoc[nn_cmsg(3compat)], -xref:nn_errno.3compat.adoc[nn_errno(3compat)], -xref:nn_recv.3compat.adoc[nn_recv(3compat)], -xref:nn_send.3compat.adoc[nn_send(3compat)], -xref:nn_socket.3compat.adoc[nn_socket(3compat)], -xref:nng_compat.3compat.adoc[nn_compat(3compat)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nn_send.3compat.adoc b/docs/man/nn_send.3compat.adoc deleted file mode 100644 index 050bea178..000000000 --- a/docs/man/nn_send.3compat.adoc +++ /dev/null @@ -1,74 +0,0 @@ -= nn_send(3compat) -// -// Copyright 2018 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nn_send - send data (compatible API) - -== SYNOPSIS - -[source, c] ----- -#include - -int nn_send(int sock, const void *data, size_t size, int flags) ----- - -== DESCRIPTION - -The `nn_send()` function creates a message containing _data_ (of size _size_), -and sends using the socket _sock_. - -NOTE: This function is provided for API -xref:nng_compat.3compat.adoc[compatibility] with legacy _libnanomsg_. -Consider using the relevant xref:libnng.3.adoc[modern API] instead. - -If _size_ has the special value `NN_MSG`, then a zero-copy operation -is performed. -In this case, _data_ points not to the message content itself, but instead -is a pointer to the pointer, an extra level of pointer indirection. -The message must have been previously allocated by -xref:nn_allocmsg.3compat.adoc[`nn_allocmsg()`] or -xref:nn_recvmsg.3compat.adoc[`nn_recvmsg()`]`, using the same `NN_MSG` size. -In this case, the ownership of the message shall remain with -the caller, unless the function returns 0, indicating that the -function has taken responsibility for delivering or disposing of the -message. - -The _flags_ field may contain the special flag `NN_DONTWAIT`. -In this case, if the socket is unable to accept more data for sending, -the operation shall not block, but instead will fail with the error `EAGAIN`. - -NOTE: The send operation is performed asynchronously, and may not have -completed before this function returns control to the caller. - -== RETURN VALUES - -This function returns the number of bytes sent on success, and -1 on error. - -== ERRORS - -[horizontal] -`EAGAIN`:: The operation would block. -`EBADF`:: The socket _sock_ is not open. -`EFSM`:: The socket cannot send in this state. -`ENOTSUP`:: This protocol cannot send. -`ETIMEDOUT`:: Operation timed out. - -== SEE ALSO - -[.text-left] -xref:nn_errno.3compat.adoc[nn_errno(3compat)], -xref:nn_recv.3compat.adoc[nn_recv(3compat)], -xref:nn_sendmsg.3compat.adoc[nn_sendmsg(3compat)], -xref:nn_socket.3compat.adoc[nn_socket(3compat)], -xref:nng_compat.3compat.adoc[nn_compat(3compat)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nn_sendmsg.3compat.adoc b/docs/man/nn_sendmsg.3compat.adoc deleted file mode 100644 index b339bfe66..000000000 --- a/docs/man/nn_sendmsg.3compat.adoc +++ /dev/null @@ -1,107 +0,0 @@ -= nn_sendmsg(3compat) -// -// Copyright 2018 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nn_sendmsg - send message (compatible API) - -== SYNOPSIS - -[source, c] ----- -#include - -int nn_sendmsg(int sock, const struct nn_msghdr *hdr, int flags); ----- - -== DESCRIPTION - -The `nn_sendmsg()` function sends the message described by _hdr_ using the -socket _sock_. - -NOTE: This function is provided for API -xref:nng_compat.3compat.adoc[compatibility] with legacy _libnanomsg_. -Consider using the relevant xref:libnng.3.adoc[modern API] instead. - -The _flags_ field may contain the special flag `NN_DONTWAIT`. -In this case, if the socket is unable to accept more data for sending, -the operation shall not block, but instead will fail with the error `EAGAIN`. - -The _hdr_ points to a structure of type `struct nn_msghdr`, which has the -following definition: - -[source, c] ----- -struct nn_iovec { - void * iov_base; - size_t iov_len; -}; - -struct nn_msghdr { - struct nn_iovec *msg_iov; - int msg_iovlen; - void * msg_control; - size_t msg_controllen; -}; ----- - -The `msg_iov` is an array of gather items, permitting the message -to be spread into different memory blocks. -There are `msg_iovlen` elements in this array, each of which -has the base address (`iov_base`) and length (`iov_len`) indicated. - -For buffers allocated for zero copy -(such as by xref:nn_allocmsg.3compat.adoc[`nn_allocmsg()`]), the value -of `iov_base` should be the address of the pointer to the buffer, -rather than the address of the buffer itself. -In this case, the value of `iov_len` should be `NN_MSG`, -as the length is inferred from the allocated message. -If the `msg_iovlen` field is `NN_MSG`, then this function will free -the associated buffer after it is done with it, if it returns successfully. -(If the function returns with an error, then the caller retains ownership -of the associated buffer and may retry the operation or free the buffer -at its choice.) - -The values of `msg_control` and `msg_controllen` describe a buffer -of ancillary data to send the message. -This is currently only useful to provide the message headers -used with xref:nng.7.adoc#raw_mode[raw mode] sockets. -In all other circumstances these fields should be zero. -Details about this structure are covered in -xref:nn_cmsg.3compat.adoc[`nn_cmsg(3compat)`]. - -NOTE: The send operation is performed asynchronously, and may not have -completed before this function returns control to the caller. - -== RETURN VALUES - -This function returns the number of bytes sent on success, and -1 on error. - -== ERRORS - -[horizontal] -`EAGAIN`:: The operation would block. -`EBADF`:: The socket _sock_ is not open. -`EFSM`:: The socket cannot send in this state. -`EINVAL`:: The _hdr_ is invalid. -`ENOTSUP`:: This protocol cannot send. -`ETIMEDOUT`:: Operation timed out. - -== SEE ALSO - -[.text-left] -xref:nn_cmsg.3compat.adoc[nn_cmsg(3compat)], -xref:nn_errno.3compat.adoc[nn_errno(3compat)], -xref:nn_recv.3compat.adoc[nn_recv(3compat)], -xref:nn_send.3compat.adoc[nn_send(3compat)], -xref:nn_socket.3compat.adoc[nn_socket(3compat)], -xref:nng_compat.3compat.adoc[nn_compat(3compat)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nn_setsockopt.3compat.adoc b/docs/man/nn_setsockopt.3compat.adoc deleted file mode 100644 index 860d522ec..000000000 --- a/docs/man/nn_setsockopt.3compat.adoc +++ /dev/null @@ -1,205 +0,0 @@ -= nn_setsockopt(3compat) -// -// Copyright 2018 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nn_setsockopt - set socket option (compatible API) - -== SYNOPSIS - -[source,c] ----- -#include - -int nn_setsockopt(int sock, int level, int option, const void *val, size_t sz); ----- - -== DESCRIPTION - -The `nn_setsockopt()` function sets a socket option on socket _sock_, -affecting the behavior of the socket. -The option set is determined by the _level_ and _option_. -The value of the option is set by _val_, and _sz_, which are pointers to -the actual value and the size of the value, respectively. - -NOTE: This function is provided for API -xref:nng_compat.3compat.adoc[compatibility] with legacy _libnanomsg_. -Consider using the relevant xref:libnng.3.adoc[modern API] instead. - -The _level_ determines whether the option is a generic socket option, -or is transport-specific. -The values possible for level are as follows: - -[horizontal] -`NN_SOL_SOCKET`:: Generic socket option -`NN_IPC`:: Transport specific option for IPC. -`NN_TCP`:: Transport specific option for TCP. -`NN_WS`:: Transport specific option for WebSocket. - -The following generic socket options are possible (all are of type `int` and -thus size 4, unless otherwise indicated.) - -`NN_SNDBUF`:: -Send buffer size in bytes. - -NOTE: In _NNG_ buffers are sized as a count of messages rather than -bytes, and so an attempt to estimate a conversion based upon a predetermined -message size of 1kB is made. -The value supplied is rounded up to the nearest value divisible by 1024, and -then divided by 1024 to convert to a message count. -Applications that have unusual message sizes may wish to adjust the value -used here accordingly. - -`NN_RCVBUF`:: -Receive buffer size in bytes. - -NOTE: The same caveats for `NN_SNDBUF` apply here as well. - -`NN_SNDTIMEO`:: -Send time-out in milliseconds. -Send operations will fail with `ETIMEDOUT` if no message can be received -after this many milliseconds have transpired since the operation was started. -A value of -1 means that no timeout is applied. - -`NN_RCVTIMEO`:: -Receive time-out in milliseconds. -Receive operations will fail with `ETIMEDOUT` if no message can be received -after this many milliseconds have transpired since the operation was started. -A value of -1 means that no timeout is applied. - -`NN_RCVMAXSIZE`:: -Maximum receive size in bytes. -The socket will discard messages larger than this on receive. -The default, 1MB, is intended to prevent denial-of-service attacks. -The value -1 removes any limit. - -`NN_RECONNECT_IVL`:: -Reconnect interval in milliseconds. -After an outgoing connection is closed or fails, the socket will -automatically attempt to reconnect after this many milliseconds. -This is the starting value for the time, and is used in the first -reconnection attempt after a successful connection is made. -The default is 100. - -`NN_RECONNECT_IVL_MAX`:: -Maximum reconnect interval in milliseconds. -Subsequent reconnection attempts after a failed attempt are made at -exponentially increasing intervals (back-off), but the interval is -capped by this value. -If this value is smaller than `NN_RECONNECT_IVL`, then no exponential -back-off is performed, and each reconnect interval will be determined -solely by `NN_RECONNECT_IVL`. -The default is zero. - -`NN_LINGER`:: -This option is ignored, and exists only for compatibility. - -NOTE: This option was unreliable in early releases of _libnanomsg_, and -is unsupported in _NNG_ and recent _libnanomsg_ releases. -Applications needing assurance of message delivery should either include an -explicit notification (automatic with the `NN_REQ` protocol) or allow -sufficient time for the socket to drain before closing the socket or exiting. - -`NN_SNDPRIO`:: -This option is not implemented at this time. - -`NN_RCVPRIO`:: -This option is not implemented at this time. - -`NN_IPV4ONLY`:: -This option is not implemented at this time. - -`NN_SOCKET_NAME`:: -This option is a string, and represents the socket name. -It can be changed to help with identifying different sockets with -their different application-specific purposes. - -`NN_MAXTTL`:: -Maximum number of times a message may traverse devices or proxies. -This value, if positive, provides some protection against forwarding loops in -xref:nng_device.3.adoc[device] chains. - -NOTE: Not all protocols offer this protection, so care should still be used -in configuring device forwarding. - -The following option is available for `NN_REQ` sockets -using the `NN_REQ` level: - -`NN_REQ_RESEND_IVL`:: -Request retry interval in milliseconds. -If an `NN_REQ` socket does not receive a reply to a request within this -period of time, the socket will automatically resend the request. -The default value is 60000 (one minute). - -The following options are available for `NN_SUB` sockets using the `NN_SUB` level: - -`NN_SUB_SUBSCRIBE`:: -Subscription topic, for `NN_SUB` sockets. -This sets a subscription topic. -When a message from a publisher arrives, it is compared against all -subscriptions. -If the first _sz_ bytes of the message are not identical to _val_, -then the message is silently discarded. - -TIP: To receive all messages, subscribe to an empty topic (_sz_ equal to zero). - -`NN_SUB_UNSUBSCRIBE`:: -Removes a subscription topic that was earlier established. - -The following option is available for `NN_SURVEYOR` sockets -using the `NN_SURVEYOR` level: - -`NN_SURVEYOR_DEADLINE`:: -Survey deadline in milliseconds for `NN_SURVEYOR` sockets. -After sending a survey message, the socket will only accept responses -from respondents for this long. -Any responses arriving after this expires are silently discarded. - -In addition, the following transport specific options are offered: - -`NN_IPC_SEC_ATTR`:: -This `NN_IPC` option is not supported at this time. - -`NN_IPC_OUTBUFSZ`:: -This `NN_IPC` option is not supported at this time. - -`NN_IPC_INBUFSZE`:: -This `NN_IPC` option is not supported at this time. - -`NN_TCP_NODELAY`:: -This `NN_TCP` option is not supported at this time. - -`NN_WS_MSG_TYPE`:: -This `NN_WS` option is not supported at this time. - -== RETURN VALUES - -This function returns zero on success, and -1 on failure. - -== ERRORS - -[horizontal] -`EBADF`:: The socket _sock_ is not an open socket. -`ENOMEM`:: Insufficient memory is available. -`ENOPROTOOPT`:: The level and/or option is invalid. -`EINVAL`:: The option, or the value passed, is invalid. -`ETERM`:: The library is shutting down. -`EACCES`:: The option cannot be changed. - -== SEE ALSO - -[.text-left] -xref:nng_socket.5.adoc[nng_socket(5)], -xref:nn_close.3compat.adoc[nn_close(3compat)], -xref:nn_errno.3compat.adoc[nn_errno(3compat)], -xref:nn_getsockopt.3compat.adoc[nn_getsockopt(3compat)], -xref:nng_compat.3compat.adoc[nng_compat(3compat)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nn_shutdown.3compat.adoc b/docs/man/nn_shutdown.3compat.adoc deleted file mode 100644 index 06a5cd5a8..000000000 --- a/docs/man/nn_shutdown.3compat.adoc +++ /dev/null @@ -1,55 +0,0 @@ -= nn_shutdown(3compat) -// -// Copyright 2020 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nn_shutdown - shut down endpoint (compatible API) - -== SYNOPSIS - -[source, c] ----- -#include - -int nn_shutdown(int sock, int ep) ----- - -== DESCRIPTION - -The `nn_shutdown()` shuts down the endpoint _ep_, which is either a listener or -a dialer) on the socket _sock_. -This will stop the socket from either accepting new connections, or establishing -old ones. -Additionally, any established connections associated with _ep_ will be closed. - -NOTE: This function is provided for API -xref:nng_compat.3compat.adoc[compatibility] with legacy _libnanomsg_. -Consider using the relevant xref:libnng.3.adoc[modern API] instead. - -== RETURN VALUES - -This function returns zero on success, and -1 on error. - -== ERRORS - -[horizontal] -`EBADF`:: The socket _sock_ is not open. -`EINVAL`:: An invalid _ep_ was supplied. - -== SEE ALSO - -[.text-left] -xref:nn_bind.3compat.adoc[nn_bind(3compat)], -xref:nn_connect.3compat.adoc[nn_connect(3compat)], -xref:nn_errno.3compat.adoc[nn_errno(3compat)], -xref:nn_socket.3compat.adoc[nn_socket(3compat)], -xref:nng_compat.3compat.adoc[nn_compat(3compat)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nn_socket.3compat.adoc b/docs/man/nn_socket.3compat.adoc deleted file mode 100644 index c4bbb70ac..000000000 --- a/docs/man/nn_socket.3compat.adoc +++ /dev/null @@ -1,78 +0,0 @@ -= nn_socket(3compat) -// -// Copyright 2018 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nn_socket - create socket (compatible API) - -== SYNOPSIS - -[source,c] ----- -#include - -int nn_socket(int af, int proto); ----- - -== DESCRIPTION - -The `nn_socket()` function creates socket using the address family _af_ and -protocol _proto_ and returns it. - -NOTE: This function is provided for API -xref:nng_compat.3compat.adoc[compatibility] with legacy _libnanomsg_. -Consider using the relevant xref:libnng.3.adoc[modern API] instead. - -IMPORTANT: Mixing the compatibility API and the modern API is not supported -on a given socket. - -NOTE: Some protocols, transports, and features are only available in the modern API. - -The address family _af_ can be one of two values: - -[horizontal] -`AF_SP`:: Normal socket. -`AF_SP_RAW`:: xref:nng.7.adoc#raw_mode[Raw mode] socket. - -The protocol indicates the protocol to be used when creating the socket. -The following protocols are defined: - -[horizontal] -`NN_PAIR`:: xref:nng_pair.7.adoc[Pair] protocol. -`NN_PUB`:: xref:nng_pub.7.adoc[Publisher] protocol. -`NN_SUB`:: xref:nng_sub.7.adoc[Subscriber] protocol. -`NN_REQ`:: xref:nng_req.7.adoc[Requestor] protocol. -`NN_REP`:: xref:nng_rep.7.adoc[Replier] protocol. -`NN_PUSH`:: xref:nng_push.7.adoc[Push] protocol. -`NN_PULL`:: xref:nng_pull.7.adoc[Pull] protocol. -`NN_SURVEYOR`:: xref:nng_surveyor.7.adoc[Surveyor] protocol. -`NN_RESPONDENT`:: xref:nng_respondent.7.adoc[Respondent] protocol. -`NN_BUS`:: xref:nng_bus.7.adoc[Bus] protocol. - -== RETURN VALUES - -This function returns a valid socket number on success, and -1 on failure. - -== ERRORS - -[horizontal] -`ENOMEM`:: Insufficient memory is available. -`ENOTSUP`:: The protocol is not supported. -`ETERM`:: The library is shutting down. - -== SEE ALSO - -[.text-left] -xref:nng_socket.5.adoc[nng_socket(5)], -xref:nn_close.3compat.adoc[nn_close(3compat)], -xref:nn_errno.3compat.adoc[nn_errno(3compat)], -xref:nng_compat.3compat.adoc[nng_compat(3compat)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nn_strerror.3compat.adoc b/docs/man/nn_strerror.3compat.adoc deleted file mode 100644 index 3fc2dc299..000000000 --- a/docs/man/nn_strerror.3compat.adoc +++ /dev/null @@ -1,47 +0,0 @@ -= nn_strerror(3compat) -// -// Copyright 2018 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nn_strerror - return message for error (compatible API) - -== SYNOPSIS - -[source,c] ----- -#include - -const char *nn_strerror(int err); ----- - -== DESCRIPTION - -The `nn_strerror()` function returns a human readable message corresponding -to the given error number _err_. - -NOTE: This function is provided for API -xref:nng_compat.3compat.adoc[compatibility] with legacy _libnanomsg_. -Consider using the relevant xref:libnng.3.adoc[modern API] instead. - -== RETURN VALUES - -This function returns the message corresponding to _err_. - -== ERRORS - -None. - -== SEE ALSO - -[.text-left] -xref:nn_errno.3compat.adoc[nn_errno(3compat)], -xref:nng_compat.3compat.adoc[nng_compat(3compat)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nn_term.3compat.adoc b/docs/man/nn_term.3compat.adoc deleted file mode 100644 index 79b6a1e37..000000000 --- a/docs/man/nn_term.3compat.adoc +++ /dev/null @@ -1,59 +0,0 @@ -= nn_term(3compat) -// -// Copyright 2018 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nn_term - terminate library (compatible API) - -== SYNOPSIS - -[source,c] ----- -#include - -void nn_term(void); ----- - -== DESCRIPTION - -The `nn_term()` function closes any open sockets, and frees all resources -allocated by the library. -Any operations that are currently in progress will be terminated, and will -fail with error `EBADF` or `ETERM`. - -NOTE: This function is provided for API -xref:nng_compat.3compat.adoc[compatibility] with legacy _libnanomsg_. -Consider using the relevant xref:libnng.3.adoc[modern API] instead. - -IMPORTANT: This function is not thread-safe, and is not suitable for use -in library calls. -The intended purpose of this is to clean up at application termination; for -example by registering this function with `atexit()`. -This can help prevent false leak reports caused when memory checkers notice -global resources allocated by the library. -Libraries should never use this function, but should explicitly close their -own sockets directly. - -== RETURN VALUES - -None. - -== ERRORS - -None. - -== SEE ALSO - -[.text-left] -xref:nn_errno.3compat.adoc[nn_errno(3compat)], -xref:nn_socket.3compat.adoc[nn_socket(3compat)], -xref:nng_compat.3compat.adoc[nng_compat(3compat)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_compat.3compat.adoc b/docs/man/nng_compat.3compat.adoc deleted file mode 100644 index bd9865976..000000000 --- a/docs/man/nng_compat.3compat.adoc +++ /dev/null @@ -1,214 +0,0 @@ -= nng_compat(3compat) -// -// Copyright 2018 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_compat - compatibility with nanomsg 1.0 - -== SYNOPSIS - -[source, c] ----- -#include - -#include -#include -#include -#include -#include -#include - -#include -#include -#include -#include ----- - -== DESCRIPTION - -(((compatibility layer))) -xref:nng.7.adoc[_NNG_] provides source-level compatibility for -most _libnanomsg_ 1.0 applications. - -IMPORTANT: This is intended to facilitate converting ((legacy applications)) to -use _NNG_. -New applications should use the newer xref:nng.7.adoc[_NNG_] API instead. - -Applications making use of this must take care -to link with xref:libnng.3.adoc[_libnng_] instead of _libnn_. - -TIP: While not recommended for long term use, the value returned by -xref:nng_socket_id.3.adoc[`nng_socket_id()`] can be used with these functions -just like a value returned by xref:nn_socket.3compat.adoc[`nn_socket()`]. -This can be way to facilitate incremental transition to the new API. - -NOTE: Some capabilities, protocols, and transports, will not be accessible -using this API, as the compatible API has no provision for expression -of certain concepts introduced in the new API. - -NOTE: While reasonable efforts have been made to provide for compatibility, -some things may behave differently, and some less common parts of the -_libnanomsg_ 1.0 API are not supported at this time, including certain -options and the statistics API. -See the <> section below. - -=== Compiling - -When compiling legacy _nanomsg_ applications, it will generally be -necessary to change the include search path to add the `compat` subdirectory -of the directory where headers were installed. -For example, if _NNG_ is installed in `$prefix`, then header files will -normally be located in `$prefix/include/nng`. -In this case, to build legacy _nanomsg_ apps against _NNG_ you would -add `$prefix/include/nng/compat` to your compiler's search path. - -Alternatively, you can change your source code so that `#include` statements -referring to `` instead refer to ``. -For example, instead of: - -[source,c] ----- -#include -#include ----- - -you would have this: - -[source,c] ----- -#include -#include ----- - -Legacy applications built using these methods should be linked against _libnng_ -instead of _libnn_, just like any other _NNG_ application. - -=== Functions - -The following functions are provided: - -// For PDF, we don't have horizontal lists, so we have to conditionalize -// this and use tables there -- it looks ugly otherwise. -ifndef::backend-pdf[] -[horizontal] -xref:nn_socket.3compat.adoc[`nn_socket()`]:: create socket -xref:nn_getsockopt.3compat.adoc[`nn_getsockopt()`]:: get socket option -xref:nn_setsockopt.3compat.adoc[`nn_setsockopt()`]:: set socket option -xref:nn_bind.3compat.adoc[`nn_bind()`]:: accept connections from remote peers -xref:nn_connect.3compat.adoc[`nn_connect()`]:: connect to remote peer -xref:nn_send.3compat.adoc[`nn_send()`]:: send data -xref:nn_recv.3compat.adoc[`nn_recv()`]:: receive data -xref:nn_shutdown.3compat.adoc[`nn_shutdown()`]:: shut down endpoint -xref:nn_close.3compat.adoc[`nn_close()`]:: close socket -xref:nn_poll.3compat.adoc[`nn_poll()`]:: poll sockets -xref:nn_device.3compat.adoc[`nn_device()`]:: create forwarding device -xref:nn_recvmsg.3compat.adoc[`nn_recvmsg()`]:: receive message -xref:nn_sendmsg.3compat.adoc[`nn_sendmsg()`]:: send message -xref:nn_cmsg.3compat.adoc[`nn_cmsg()`]:: message control data -xref:nn_get_statistic.3compat.adoc[`nn_get_statistic()`]:: get statistic (stub) -xref:nn_allocmsg.3compat.adoc[`nn_allocmsg()`]:: allocate message -xref:nn_reallocmsg.3compat.adoc[`nn_reallocmsg()`]:: reallocate message -xref:nn_freemsg.3compat.adoc[`nn_freemsg()`]:: free message -xref:nn_errno.3compat.adoc[`nn_errno()`]:: return most recent error -xref:nn_strerror.3compat.adoc[`nn_strerror()`]:: return message for error -xref:nn_term.3compat.adoc[`nn_term()`]:: terminate library -endif::[] -ifdef::backend-pdf[] -// Add links for the following as they are written. -[.hdlist,width=90%, grid=rows,cols="1,2", align="center"] -|=== -|xref:nn_socket.3compat.adoc[`nn_socket()`]|create socket -|xref:nn_getsockopt.3compat.adoc[`nn_getsockopt()`]|get socket option -|xref:nn_setsockopt.3compat.adoc[`nn_setsockopt()`]|set socket option -|xref:nn_bind.3compat.adoc[`nn_bind()`]|accept connections from remote peers -|xref:nn_connect.3compat.adoc[`nn_connect()`]|connect to remote peer -|xref:nn_send.3compat.adoc[`nn_send()`]|send data -|xref:nn_recv.3compat.adoc[`nn_recv()`]|receive data -|xref:nn_shutdown.3compat.adoc[`nn_shutdown()`]|shut down endpoint -|xref:nn_close.3compat.adoc[`nn_close()`]|close socket -|xref:nn_poll.3compat.adoc[`nn_poll()`]|poll sockets -|xref:nn_device.3compat.adoc[`nn_device()`]|create forwarding device -|xref:nn_recvmsg.3compat.adoc[`nn_recvmsg()`]|receive message -|xref:nn_sendmsg.3compat.adoc[`nn_sendmsg()`]|send message -|xref:nn_cmsg.3compat.adoc[`nn_cmsg()`]|message control data -|xref:nn_get_statistic.3compat.adoc[`nn_get_statistic()`]|get statistic (stub) -|xref:nn_allocmsg.3compat.adoc[`nn_allocmsg()`]|allocate message -|xref:nn_reallocmsg.3compat.adoc[`nn_reallocmsg()`]|reallocate message -|xref:nn_freemsg.3compat.adoc[`nn_freemsg()`]|free message -|xref:nn_errno.3compat.adoc[`nn_errno()`]|return most recent error -|xref:nn_strerror.3compat.adoc[`nn_strerror()`]|return message for error -|xref:nn_term.3compat.adoc[`nn_term()`]|terminate library -|=== -endif::[] - -=== Caveats - -The following caveats apply when using the legacy API with _NNG_. - -* Socket numbers can be quite large. - The legacy _libnanomsg_ attempted to reuse socket numbers, like - file descriptors in UNIX systems. - _NNG_ avoids this to prevent accidental reuse or - collision after a descriptor is closed. - Consequently, socket numbers can become quite large, and should - probably not be used for array indices. - -* The following options (`nn_getsockopt`) are unsupported: - `NN_SNDPRIO`, `NN_RCVPRIO`, `NN_IPV4ONLY`. - The priority options may be supported in the future, when - the underlying capability is present in _NNG_. - -* Access to statistics using this legacy API - (xref:nn_get_statistic.3compat.adoc[`nn_get_statistic()`]) is unsupported. - -* Some transports can support longer URLs than legacy _libnanomsg_ can. - It is a good idea to use short pathnames in URLs if interoperability - is a concern. - -* Only absolute paths are supported in `ipc://` URLs. - For example, `ipc:///tmp/mysocket` is acceptable, but `ipc://mysocket` is not. - -* The WebSocket transport in this implementation (`ws://` URLs) - only supports BINARY frames. - -* Some newer transports are unusable from this mode. - In particular, this legacy API offers no way to configure - TLS or ZeroTier parameters that may be required for use. - -* ABI versioning of the compatibility layer is not supported, - and the `NN_VERSION_` macros are not present. - -* Runtime symbol information is not implemented. - Specifically, there is no `nn_symbol()` function yet. - (This may be addressed later if there is a need.) - -* The TCP transport (`tcp://` URLs) does not support specifying the local - address or interface when binding. (This could be fixed in the future, - but most likely this will be available only using the new API.) - -* The values of `NN_RCVMAXSIZE` are constrained. - Specifically, values set larger than 2GB using the new API will be reported - as unlimited (`-1`) in the new API, and the value `0` will disable any - enforcement, just like `-1`. - (There is no practical reason to ever want to limit the receive size to - zero.) - -* This implementation counts buffers in terms of messages rather than bytes. - As a result, the buffer sizes accessed with `NN_SNDBUF` and `NN_RCVBUF` are - rounded up to a whole number of kilobytes, then divided by 1024, in order - to approximate buffering assuming 1 KB messages. - Few applications should need to adjust the default values. - -== SEE ALSO - -[.text-left] -xref:libnng.3.adoc[libnng(3)], -xref:nng.7.adoc[nng(7)] From cc0b2a6db144d4f81c6295e257b90261885177fb Mon Sep 17 00:00:00 2001 From: Garrett D'Amore Date: Sat, 7 Sep 2024 11:33:05 -0700 Subject: [PATCH 017/222] Remove the legacy transport registration functions. This also allows to remove most of the transport headers. Only zerotier.h sticks around, and only for now. (We expect to eject it into a separate module.) Signed-off-by: jaylin --- docs/man/CMakeLists.txt | 7 -- docs/man/libnng.3.adoc | 17 --- docs/man/nng_inproc.7.adoc | 17 +-- docs/man/nng_inproc_register.3.adoc | 47 -------- docs/man/nng_ipc.7.adoc | 16 +-- docs/man/nng_ipc_register.3.adoc | 47 -------- docs/man/nng_tcp.7.adoc | 16 +-- docs/man/nng_tcp_register.3.adoc | 47 -------- docs/man/nng_tls.7.adoc | 17 +-- docs/man/nng_tls_register.3.adoc | 44 ------- docs/man/nng_ws.7.adoc | 21 +--- docs/man/nng_ws_register.3.adoc | 47 -------- docs/man/nng_wss_register.3.adoc | 47 -------- docs/man/nng_zerotier.7.adoc | 18 --- docs/man/nng_zt_register.3.adoc | 47 -------- include/nng/transport/inproc/inproc.h | 29 ----- include/nng/transport/ipc/ipc.h | 31 ----- include/nng/transport/tcp/tcp.h | 30 ----- include/nng/transport/tls/tls.h | 30 ----- include/nng/transport/ws/websocket.h | 35 ------ include/nng/transport/zerotier/zerotier.h | 4 - src/sp/transport/inproc/CMakeLists.txt | 5 +- src/sp/transport/ipc/CMakeLists.txt | 5 +- src/sp/transport/ipc/ipc.c | 2 - src/sp/transport/tcp/CMakeLists.txt | 3 +- src/sp/transport/tls/CMakeLists.txt | 1 - src/sp/transport/tls/tls.c | 1 - src/sp/transport/ws/CMakeLists.txt | 4 - src/sp/transport/ws/websocket.c | 1 - src/sp/transport/zerotier/zerotier.c | 140 ++++++++++------------ src/supplemental/websocket/websocket.c | 6 +- src/testing/nuts.h | 1 - tests/ipc.c | 15 +-- tests/multistress.c | 4 - tests/reqstress.c | 4 - tests/tls.c | 10 +- tests/trantest.h | 7 -- tests/ws.c | 13 +- tests/wss.c | 6 +- 39 files changed, 92 insertions(+), 750 deletions(-) delete mode 100644 docs/man/nng_inproc_register.3.adoc delete mode 100644 docs/man/nng_ipc_register.3.adoc delete mode 100644 docs/man/nng_tcp_register.3.adoc delete mode 100644 docs/man/nng_tls_register.3.adoc delete mode 100644 docs/man/nng_ws_register.3.adoc delete mode 100644 docs/man/nng_wss_register.3.adoc delete mode 100644 docs/man/nng_zt_register.3.adoc delete mode 100644 include/nng/transport/inproc/inproc.h delete mode 100644 include/nng/transport/ipc/ipc.h delete mode 100644 include/nng/transport/tcp/tcp.h delete mode 100644 include/nng/transport/tls/tls.h delete mode 100644 include/nng/transport/ws/websocket.h diff --git a/docs/man/CMakeLists.txt b/docs/man/CMakeLists.txt index 63c87f799..93780c0d1 100644 --- a/docs/man/CMakeLists.txt +++ b/docs/man/CMakeLists.txt @@ -104,8 +104,6 @@ if (NNG_ENABLE_DOC) nng_dialer_start nng_free nng_getopt - nng_inproc_register - nng_ipc_register nng_listen nng_listener_close nng_listener_create @@ -185,15 +183,10 @@ if (NNG_ENABLE_DOC) nng_strfree nng_sub_open nng_surveyor_open - nng_tcp_register - nng_tls_register nng_url_clone nng_url_free nng_url_parse nng_version - nng_ws_register - nng_wss_register - nng_zt_register ) set(NNG_MAN3HTTP diff --git a/docs/man/libnng.3.adoc b/docs/man/libnng.3.adoc index c110654a7..6f0def11b 100644 --- a/docs/man/libnng.3.adoc +++ b/docs/man/libnng.3.adoc @@ -208,22 +208,6 @@ The following functions are used to construct a socket with a specific protocol: |xref:nng_surveyor_open.3.adoc[nng_surveyor_open]|open a surveyor socket |=== -=== Transports - -The following functions are used to register a transport for use. -This is no longer necessary, and applications should not call these -functions anymore. - -|=== -| xref:nng_inproc_register.3.adoc[nng_inproc_register]|register inproc transport (DEPRECATED) -| xref:nng_ipc_register.3.adoc[nng_ipc_register]|register IPC transport (DEPRECATED) -| xref:nng_tcp_register.3.adoc[nng_tcp_register]|register TCP transport (DEPRECATED) -| xref:nng_tls_register.3.adoc[nng_tls_register]|register TLS transport (DEPRECATED) -| xref:nng_ws_register.3.adoc[nng_ws_register]|register WebSocket transport (DEPRECATED) -| xref:nng_wss_register.3.adoc[nng_wss_register]|register WebSocket Secure transport (DEPRECATED) -| xref:nng_zt_register.3.adoc[nng_zt_register]|register ZeroTier transport (DEPRECATED) -|=== - === Protocol Contexts The following functions are useful to separate the protocol processing @@ -515,5 +499,4 @@ These functions are intended for use with MQTT client applications. == SEE ALSO [.text-left] -xref:nng_compat.3compat.adoc[nng_compat(3compat)], xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_inproc.7.adoc b/docs/man/nng_inproc.7.adoc index 833ba3537..6cdb07b13 100644 --- a/docs/man/nng_inproc.7.adoc +++ b/docs/man/nng_inproc.7.adoc @@ -1,6 +1,6 @@ = nng_inproc(7) // -// Copyright 2019 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 @@ -13,15 +13,6 @@ nng_inproc - intra-process transport -== SYNOPSIS - -[source,c] ----- -#include - -int nng_inproc_register(void); ----- - == DESCRIPTION (((transport, _inproc_))) @@ -34,12 +25,8 @@ to slower transports when data must be moved within the same process. This transport tries hard to avoid copying data, and thus is very light-weight. -=== Registration - -This transport is generally built-in to the core, so -no extra steps to use it should be necessary. - === URI Format + (((URI, `inproc://`))) This transport uses URIs using the scheme `inproc://`, followed by an arbitrary string of text, terminated by a `NUL` byte. diff --git a/docs/man/nng_inproc_register.3.adoc b/docs/man/nng_inproc_register.3.adoc deleted file mode 100644 index 8379a4e88..000000000 --- a/docs/man/nng_inproc_register.3.adoc +++ /dev/null @@ -1,47 +0,0 @@ -= nng_inproc_register(3) -// -// Copyright 2021 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_inproc_register - register inproc transport - -== SYNOPSIS - -[source,c] ----- -#include - -int nng_inproc_register(void); ----- - -== DESCRIPTION - -The `nng_inproc_register()` function registers the -((_inproc_ transport))(((transport, _inproc_))) for use. - -NOTE: This function is deprecated, and may be removed from a future release. -It is no longer necessary to explicitly register transports. - -== RETURN VALUES - -This function returns 0 on success, and non-zero otherwise. - -== ERRORS - -[horizontal] -`NNG_ENOMEM`:: Insufficient memory is available. -`NNG_ENOTSUP`:: The transport is not supported. - -== SEE ALSO - -[.text-left] -xref:nng_inproc.7.adoc[nng_inproc(5)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_ipc.7.adoc b/docs/man/nng_ipc.7.adoc index c085e4d20..456ea5473 100644 --- a/docs/man/nng_ipc.7.adoc +++ b/docs/man/nng_ipc.7.adoc @@ -1,6 +1,6 @@ = nng_ipc(7) // -// Copyright 2023 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 @@ -13,15 +13,6 @@ nng_ipc - IPC transport -== SYNOPSIS - -[source,c] ----- -#include - -int nng_ipc_register(void); ----- - == DESCRIPTION (((IPC)))(((transport, _ipc_))) @@ -33,11 +24,6 @@ Other platforms may have different implementation strategies. // We need to insert a reference to the nanomsg RFC. -=== Registration - -This transport is generally built-in to the core, so -no extra steps to use it should be necessary. - === URI Formats ==== Traditional Names diff --git a/docs/man/nng_ipc_register.3.adoc b/docs/man/nng_ipc_register.3.adoc deleted file mode 100644 index 64da4b00e..000000000 --- a/docs/man/nng_ipc_register.3.adoc +++ /dev/null @@ -1,47 +0,0 @@ -= nng_ipc_register(3) -// -// Copyright 2021 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_ipc_register - register ipc transport - -== SYNOPSIS - -[source,c] ----- -#include - -int nng_ipc_register(void); ----- - -== DESCRIPTION - -The `nng_ipc_register()` function registers the -((_ipc_ transport))(((transport, _ipc_))) for use. - -NOTE: This function is deprecated, and may be removed from a future release. -It is no longer necessary to explicitly register transports. - -== RETURN VALUES - -This function returns 0 on success, and non-zero otherwise. - -== ERRORS - -[horizontal] -`NNG_ENOMEM`:: Insufficient memory is available. -`NNG_ENOTSUP`:: The transport is not supported. - -== SEE ALSO - -[.text-left] -xref:nng_ipc.7.adoc[nng_ipc(5)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_tcp.7.adoc b/docs/man/nng_tcp.7.adoc index c1b9a4395..a5855f773 100644 --- a/docs/man/nng_tcp.7.adoc +++ b/docs/man/nng_tcp.7.adoc @@ -1,6 +1,6 @@ = nng_tcp(7) // -// Copyright 2019 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 @@ -13,15 +13,6 @@ nng_tcp - TCP/IP transport -== SYNOPSIS - -[source,c] ----- -#include - -int nng_tcp_register(void); ----- - == DESCRIPTION (((transport, _tcp_))) @@ -31,11 +22,6 @@ Both IPv4 and IPv6 are supported when the underlying platform also supports it. // We need to insert a reference to the nanomsg RFC. -=== Registration - -This transport is generally built-in to the core of _NNG_, so -no extra steps to use it should be necessary. - === URI Format (((URI, `tcp://`))) diff --git a/docs/man/nng_tcp_register.3.adoc b/docs/man/nng_tcp_register.3.adoc deleted file mode 100644 index 3da671a9b..000000000 --- a/docs/man/nng_tcp_register.3.adoc +++ /dev/null @@ -1,47 +0,0 @@ -= nng_tcp_register(3) -// -// Copyright 2021 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_tcp_register - register tcp transport - -== SYNOPSIS - -[source,c] ----- -#include - -int nng_tcp_register(void); ----- - -== DESCRIPTION - -The `nng_tcp_register()` function registers the -((_tcp_ transport))(((transport, _tcp_))) for use. - -NOTE: This function is deprecated, and may be removed from a future release. -It is no longer necessary to explicitly register transports. - -== RETURN VALUES - -This function returns 0 on success, and non-zero otherwise. - -== ERRORS - -[horizontal] -`NNG_ENOMEM`:: Insufficient memory is available. -`NNG_ENOTSUP`:: The transport is not supported. - -== SEE ALSO - -[.text-left] -xref:nng_tcp.7.adoc[nng_tcp(7)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_tls.7.adoc b/docs/man/nng_tls.7.adoc index 017af4fc9..0da590ac8 100644 --- a/docs/man/nng_tls.7.adoc +++ b/docs/man/nng_tls.7.adoc @@ -1,6 +1,6 @@ = nng_tls(7) // -// Copyright 2019 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 @@ -13,15 +13,6 @@ nng_tls - TLS transport -== SYNOPSIS - -[source,c] ----- -#include - -int nng_tls_register(void); ----- - == DESCRIPTION (((TLS)))(((Transport Layer Security)))(((transport, _tls_))) @@ -34,12 +25,6 @@ Both IPv4 and IPv6 are supported when the underlying platform also supports it. The protocol details are documented in http://nanomsg.org/rfcs/sp-tls-v1.html[TLS Mapping for Scalability Protocols]. -=== Registration - -Depending upon how the library was built, it may be necessary to -register the transport by calling -xref:nng_tls_register.3.adoc[`nng_tls_register()`]. - === Availability The _tls_ transport depends on the use of an external library. diff --git a/docs/man/nng_tls_register.3.adoc b/docs/man/nng_tls_register.3.adoc deleted file mode 100644 index bfe27e054..000000000 --- a/docs/man/nng_tls_register.3.adoc +++ /dev/null @@ -1,44 +0,0 @@ -= nng_tls_register(3) -// -// Copyright 2018 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_tls_register - register tls transport - -== SYNOPSIS - -[source,c] ----- -#include - -int nng_tls_register(void); ----- - -== DESCRIPTION - -The `nng_tls_register()` function registers the -((_tls_ transport))(((transport, _tls_))) for use. - -== RETURN VALUES - -This function returns 0 on success, and non-zero otherwise. - -== ERRORS - -[horizontal] -`NNG_ENOMEM`:: Insufficient memory is available. -`NNG_ENOTSUP`:: The transport is not supported. - -== SEE ALSO - -[.text-left] -xref:nng_tls.7.adoc[nng_tls(7)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_ws.7.adoc b/docs/man/nng_ws.7.adoc index 171ec9341..b63041ad4 100644 --- a/docs/man/nng_ws.7.adoc +++ b/docs/man/nng_ws.7.adoc @@ -1,6 +1,6 @@ = nng_ws(7) // -// Copyright 2020 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 @@ -13,16 +13,6 @@ nng_ws - WebSocket transport -== SYNOPSIS - -[source,c] ----- -#include - -int nng_ws_register(void); -int nng_wss_register(void); ----- - == DESCRIPTION (((WebSocket)))(((transport, _ws_ and _wss_))) @@ -34,15 +24,6 @@ Both IPv4 and IPv6 are supported when the underlying platform also supports it. The protocol details are documented in http://nanomsg.org/rfcs/sp-websocket-v1.html[WebSocket Mapping for Scalability Protocols]. -=== Registration - -Depending upon how the library was built, it may be necessary to -register the transport by calling xref:nng_ws_register.3.adoc[`nng_ws_register()`]. - -If ((TLS)) support is enabled in the library, secure WebSockets (over TLS v1.2) -can be used as well, but the secure transport may have to be registered using -the xref:nng_wss_register.3.adoc[`nng_wss_register()`] function. - === URI Format (((URI, `ws://`))) diff --git a/docs/man/nng_ws_register.3.adoc b/docs/man/nng_ws_register.3.adoc deleted file mode 100644 index 7a9cc1f30..000000000 --- a/docs/man/nng_ws_register.3.adoc +++ /dev/null @@ -1,47 +0,0 @@ -= nng_ws_register(3) -// -// Copyright 2021 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_ws_register - register WebSocket transport - -== SYNOPSIS - -[source,c] ----- -#include - -int nng_ws_register(void); ----- - -== DESCRIPTION - -The `nng_ws_register()` function registers the -((_ws_ transport))(((transport, _ws_))) for use. - -NOTE: This function is deprecated, and may be removed from a future release. -It is no longer necessary to explicitly register transports. - -== RETURN VALUES - -This function returns 0 on success, and non-zero otherwise. - -== ERRORS - -[horizontal] -`NNG_ENOMEM`:: Insufficient memory is available. -`NNG_ENOTSUP`:: The transport is not supported. - -== SEE ALSO - -[.text-left] -xref:nng_ws.7.adoc[nng_ws(7)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_wss_register.3.adoc b/docs/man/nng_wss_register.3.adoc deleted file mode 100644 index 856fe1c0d..000000000 --- a/docs/man/nng_wss_register.3.adoc +++ /dev/null @@ -1,47 +0,0 @@ -= nng_wss_register(3) -// -// Copyright 2021 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_wss_register - register WebSocket secure transport - -== SYNOPSIS - -[source,c] ----- -#include - -int nng_wss_register(void); ----- - -== DESCRIPTION - -The `nng_wss_register()` function registers the -((_wss_ transport))(((transport, _wss_))) for use. - -NOTE: This function is deprecated, and may be removed from a future release. -It is no longer necessary to explicitly register transports. - -== RETURN VALUES - -This function returns 0 on success, and non-zero otherwise. - -== ERRORS - -[horizontal] -`NNG_ENOMEM`:: Insufficient memory is available. -`NNG_ENOTSUP`:: The transport is not supported. - -== SEE ALSO - -[.text-left] -xref:nng_ws.7.adoc[nng_ws(7)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_zerotier.7.adoc b/docs/man/nng_zerotier.7.adoc index fa8762bf6..36cf7f0ec 100644 --- a/docs/man/nng_zerotier.7.adoc +++ b/docs/man/nng_zerotier.7.adoc @@ -13,15 +13,6 @@ nng_zerotier - ZeroTier transport -== SYNOPSIS - -[source,c] ----- -#include - -int nng_zt_register(void); ----- - == DESCRIPTION (((ZeroTier)))(((transport, _zt_))) @@ -56,15 +47,6 @@ network. NOTE: This document assumes that the reader is familiar with ZeroTier concepts and administration. -=== Registration - -Depending upon how the library was built, it may be necessary to -register the transport by calling -xref:nng_zt_register.3.adoc[`nng_zt_register()`]. -This function -returns zero on success, or an nng error value if the transport -cannot be initialized for any reason. - === URI Format (((URI, `zt://`))) diff --git a/docs/man/nng_zt_register.3.adoc b/docs/man/nng_zt_register.3.adoc deleted file mode 100644 index 9c4a4ac42..000000000 --- a/docs/man/nng_zt_register.3.adoc +++ /dev/null @@ -1,47 +0,0 @@ -= nng_zt_register(3) -// -// Copyright 2021 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_zt_register - register ZeroTier transport - -== SYNOPSIS - -[source,c] ----- -#include - -int nng_zt_register(void); ----- - -== DESCRIPTION - -The `nng_zt_register()` function registers the -((_zt_ transport))(((transport, _zt_))) for use. - -NOTE: This function is deprecated, and may be removed from a future release. -It is no longer necessary to explicitly register transports. - -== RETURN VALUES - -This function returns 0 on success, and non-zero otherwise. - -== ERRORS - -[horizontal] -`NNG_ENOMEM`:: Insufficient memory is available. -`NNG_ENOTSUP`:: The transport is not supported. - -== SEE ALSO - -[.text-left] -xref:nng_zerotier.7.adoc[nng_zerotier(7)], -xref:nng.7.adoc[nng(7)] diff --git a/include/nng/transport/inproc/inproc.h b/include/nng/transport/inproc/inproc.h deleted file mode 100644 index 0c633620a..000000000 --- a/include/nng/transport/inproc/inproc.h +++ /dev/null @@ -1,29 +0,0 @@ -// -// Copyright 2021 Staysail Systems, Inc. -// Copyright 2017 Capitar IT Group BV -// -// This software is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -#ifndef NNG_TRANSPORT_INPROC_INPROC_H -#define NNG_TRANSPORT_INPROC_INPROC_H - -#include - -#ifdef __cplusplus -extern "C" { -#endif - -// inproc transport. This is used for intra-process communication. -#ifndef NNG_ELIDE_DEPRECATED -NNG_DECL int nng_inproc_register(void); -#endif - -#ifdef __cplusplus -} -#endif - -#endif // NNG_TRANSPORT_INPROC_INPROC_H diff --git a/include/nng/transport/ipc/ipc.h b/include/nng/transport/ipc/ipc.h deleted file mode 100644 index cccef9a1a..000000000 --- a/include/nng/transport/ipc/ipc.h +++ /dev/null @@ -1,31 +0,0 @@ -// -// Copyright 2021 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This software is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -#ifndef NNG_TRANSPORT_IPC_IPC_H -#define NNG_TRANSPORT_IPC_IPC_H - -#include - -#ifdef __cplusplus -extern "C" { -#endif - -// ipc transport. This is used for inter-process communication on -// the same host computer. - -#ifndef NNG_ELIDE_DEPRECATED -NNG_DECL int nng_ipc_register(void); -#endif - -#ifdef __cplusplus -} -#endif - -#endif // NNG_TRANSPORT_IPC_IPC_H diff --git a/include/nng/transport/tcp/tcp.h b/include/nng/transport/tcp/tcp.h deleted file mode 100644 index e236c2710..000000000 --- a/include/nng/transport/tcp/tcp.h +++ /dev/null @@ -1,30 +0,0 @@ -// -// Copyright 2021 Staysail Systems, Inc. -// Copyright 2017 Capitar IT Group BV -// -// This software is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -#ifndef NNG_TRANSPORT_TCP_TCP_H -#define NNG_TRANSPORT_TCP_TCP_H - -#include - -#ifdef __cplusplus -extern "C" { -#endif - -// TCP transport. This is used for communication over TCP/IP. - -#ifndef NNG_ELIDE_DEPRECATED -NNG_DECL int nng_tcp_register(void); -#endif - -#ifdef __cplusplus -} -#endif - -#endif // NNG_TRANSPORT_TCP_TCP_H diff --git a/include/nng/transport/tls/tls.h b/include/nng/transport/tls/tls.h deleted file mode 100644 index 5e99372bd..000000000 --- a/include/nng/transport/tls/tls.h +++ /dev/null @@ -1,30 +0,0 @@ -// -// Copyright 2019 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This software is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -#ifndef NNG_TRANSPORT_TLS_TLS_H -#define NNG_TRANSPORT_TLS_TLS_H - -#include - -#ifdef __cplusplus -extern "C" { -#endif - -// TLS transport. This is used for communication via TLS v1.2 over TCP/IP. - -#ifndef NNG_ELIDE_DEPRECATED -NNG_DECL int nng_tls_register(void); -#endif - -#ifdef __cplusplus -} -#endif - -#endif // NNG_TRANSPORT_TLS_TLS_H diff --git a/include/nng/transport/ws/websocket.h b/include/nng/transport/ws/websocket.h deleted file mode 100644 index a5f97d468..000000000 --- a/include/nng/transport/ws/websocket.h +++ /dev/null @@ -1,35 +0,0 @@ -// -// Copyright 2021 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This software is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -#ifndef NNG_TRANSPORT_WS_WEBSOCKET_H -#define NNG_TRANSPORT_WS_WEBSOCKET_H - -#include - -#ifdef __cplusplus -extern "C" { -#endif - -// WebSocket transport. This is used for communication via WebSocket. - -// These aliases are for WSS naming consistency. -#define NNG_OPT_WSS_REQUEST_HEADERS NNG_OPT_WS_REQUEST_HEADERS -#define NNG_OPT_WSS_RESPONSE_HEADERS NNG_OPT_WS_RESPONSE_HEADERS - -#ifndef NNG_ELIDE_DEPRECATED -NNG_DECL int nng_ws_register(void); -NNG_DECL int nng_wss_register(void); -#endif - -#ifdef __cplusplus -} -#endif - -#endif // NNG_TRANSPORT_WS_WEBSOCKET_H diff --git a/include/nng/transport/zerotier/zerotier.h b/include/nng/transport/zerotier/zerotier.h index b8745dbdc..178bbfa65 100644 --- a/include/nng/transport/zerotier/zerotier.h +++ b/include/nng/transport/zerotier/zerotier.h @@ -150,10 +150,6 @@ enum nng_zt_status { NNG_ZT_STATUS_UNKNOWN, }; -#ifndef NNG_ELIDE_DEPRECATED -NNG_DECL int nng_zt_register(void); -#endif - #ifdef __cplusplus } #endif diff --git a/src/sp/transport/inproc/CMakeLists.txt b/src/sp/transport/inproc/CMakeLists.txt index 317686bbb..b84ab01e3 100644 --- a/src/sp/transport/inproc/CMakeLists.txt +++ b/src/sp/transport/inproc/CMakeLists.txt @@ -1,5 +1,5 @@ # -# Copyright 2020 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 @@ -12,5 +12,4 @@ nng_directory(inproc) nng_sources_if(NNG_TRANSPORT_INPROC inproc.c) -nng_headers_if(NNG_TRANSPORT_INPROC nng/transport/inproc/inproc.h) -nng_defines_if(NNG_TRANSPORT_INPROC NNG_TRANSPORT_INPROC) \ No newline at end of file +nng_defines_if(NNG_TRANSPORT_INPROC NNG_TRANSPORT_INPROC) diff --git a/src/sp/transport/ipc/CMakeLists.txt b/src/sp/transport/ipc/CMakeLists.txt index c9927f754..7353c4f33 100644 --- a/src/sp/transport/ipc/CMakeLists.txt +++ b/src/sp/transport/ipc/CMakeLists.txt @@ -1,5 +1,5 @@ # -# Copyright 2020 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 @@ -12,6 +12,5 @@ nng_directory(ipc) nng_sources_if(NNG_TRANSPORT_IPC ipc.c) -nng_headers_if(NNG_TRANSPORT_IPC nng/transport/ipc/ipc.h) nng_defines_if(NNG_TRANSPORT_IPC NNG_TRANSPORT_IPC) -nng_test_if(NNG_TRANSPORT_IPC ipc_test) \ No newline at end of file +nng_test_if(NNG_TRANSPORT_IPC ipc_test) diff --git a/src/sp/transport/ipc/ipc.c b/src/sp/transport/ipc/ipc.c index 85ccd6581..124c148a9 100644 --- a/src/sp/transport/ipc/ipc.c +++ b/src/sp/transport/ipc/ipc.c @@ -13,8 +13,6 @@ #include "core/nng_impl.h" -#include - // IPC transport. Platform specific IPC operations must be // supplied as well. Normally the IPC is UNIX domain sockets or // Windows named pipes. Other platforms could use other mechanisms, diff --git a/src/sp/transport/tcp/CMakeLists.txt b/src/sp/transport/tcp/CMakeLists.txt index c892c72c3..fea821c26 100644 --- a/src/sp/transport/tcp/CMakeLists.txt +++ b/src/sp/transport/tcp/CMakeLists.txt @@ -1,5 +1,5 @@ # -# Copyright 2020 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 @@ -12,6 +12,5 @@ nng_directory(tcp) nng_sources_if(NNG_TRANSPORT_TCP tcp.c) -nng_headers_if(NNG_TRANSPORT_TCP nng/transport/tcp/tcp.h) nng_defines_if(NNG_TRANSPORT_TCP NNG_TRANSPORT_TCP) nng_test(tcp_test) diff --git a/src/sp/transport/tls/CMakeLists.txt b/src/sp/transport/tls/CMakeLists.txt index c2d84c091..f55340a9b 100644 --- a/src/sp/transport/tls/CMakeLists.txt +++ b/src/sp/transport/tls/CMakeLists.txt @@ -12,6 +12,5 @@ nng_directory(tls) nng_sources_if(NNG_TRANSPORT_TLS tls.c) -nng_headers_if(NNG_TRANSPORT_TLS nng/transport/tls/tls.h) nng_defines_if(NNG_TRANSPORT_TLS NNG_TRANSPORT_TLS) nng_test_if(NNG_ENABLE_TLS tls_tran_test) diff --git a/src/sp/transport/tls/tls.c b/src/sp/transport/tls/tls.c index 89e9afa69..b6214938b 100644 --- a/src/sp/transport/tls/tls.c +++ b/src/sp/transport/tls/tls.c @@ -15,7 +15,6 @@ #include "core/nng_impl.h" #include "nng/supplemental/tls/tls.h" -#include "nng/transport/tls/tls.h" // TLS over TCP transport. Platform specific TCP operations must be // supplied as well, and uses the supplemental TLS v1.2 code. It is not diff --git a/src/sp/transport/ws/CMakeLists.txt b/src/sp/transport/ws/CMakeLists.txt index 5450484e9..a1bcc960f 100644 --- a/src/sp/transport/ws/CMakeLists.txt +++ b/src/sp/transport/ws/CMakeLists.txt @@ -18,8 +18,4 @@ endif() nng_defines_if(NNG_TRANSPORT_WS NNG_TRANSPORT_WS) nng_defines_if(NNG_TRANSPORT_WSS NNG_TRANSPORT_WSS) nng_sources_if(WS_ON websocket.c) -nng_headers_if(WS_ON nng/transport/ws/websocket.h) - nng_test_if(WS_ON ws_test) - - diff --git a/src/sp/transport/ws/websocket.c b/src/sp/transport/ws/websocket.c index 3def08d38..0e377e4b8 100644 --- a/src/sp/transport/ws/websocket.c +++ b/src/sp/transport/ws/websocket.c @@ -17,7 +17,6 @@ #include "supplemental/websocket/websocket.h" #include -#include typedef struct ws_dialer ws_dialer; typedef struct ws_listener ws_listener; diff --git a/src/sp/transport/zerotier/zerotier.c b/src/sp/transport/zerotier/zerotier.c index 967d13e42..295dda5dc 100644 --- a/src/sp/transport/zerotier/zerotier.c +++ b/src/sp/transport/zerotier/zerotier.c @@ -146,23 +146,23 @@ enum zt_errors { struct zt_node { char zn_path[NNG_MAXADDRLEN]; // ought to be sufficient nni_file_lockh *zn_flock; - ZT_Node * zn_znode; + ZT_Node *zn_znode; uint64_t zn_self; nni_list_node zn_link; bool zn_closed; - nni_plat_udp * zn_udp4; - nni_plat_udp * zn_udp6; + nni_plat_udp *zn_udp4; + nni_plat_udp *zn_udp6; nni_list zn_eplist; nni_list zn_plist; - zt_hash * zn_ports; - zt_hash * zn_eps; - zt_hash * zn_lpipes; - zt_hash * zn_rpipes; - nni_aio * zn_rcv4_aio; - uint8_t * zn_rcv4_buf; + zt_hash *zn_ports; + zt_hash *zn_eps; + zt_hash *zn_lpipes; + zt_hash *zn_rpipes; + nni_aio *zn_rcv4_aio; + uint8_t *zn_rcv4_buf; nng_sockaddr zn_rcv4_addr; - nni_aio * zn_rcv6_aio; - uint8_t * zn_rcv6_buf; + nni_aio *zn_rcv6_aio; + uint8_t *zn_rcv6_buf; nng_sockaddr zn_rcv6_addr; nni_thr zn_bgthr; int64_t zn_bgtime; @@ -178,15 +178,15 @@ struct zt_fraglist { int fl_ready; // we have all messages size_t fl_fragsz; unsigned int fl_nfrags; - uint8_t * fl_missing; + uint8_t *fl_missing; size_t fl_missingsz; - nni_msg * fl_msg; + nni_msg *fl_msg; }; struct zt_pipe { nni_list_node zp_link; - zt_node * zp_ztn; - nni_pipe * zp_npipe; + zt_node *zp_ztn; + nni_pipe *zp_npipe; uint64_t zp_nwid; uint64_t zp_laddr; uint64_t zp_raddr; @@ -195,15 +195,15 @@ struct zt_pipe { uint16_t zp_next_msgid; size_t zp_rcvmax; size_t zp_mtu; - nni_aio * zp_user_rxaio; + nni_aio *zp_user_rxaio; nni_time zp_last_recv; zt_fraglist zp_recvq[zt_recvq]; int zp_ping_try; int zp_ping_tries; bool zp_closed; nni_duration zp_ping_time; - nni_aio * zp_ping_aio; - uint8_t * zp_send_buf; + nni_aio *zp_ping_aio; + uint8_t *zp_send_buf; nni_atomic_flag zp_reaped; nni_reap_node zp_reap; }; @@ -218,15 +218,15 @@ struct zt_creq { struct zt_ep { nni_list_node ze_link; char ze_home[NNG_MAXADDRLEN]; // should be enough - zt_node * ze_ztn; + zt_node *ze_ztn; uint64_t ze_nwid; bool ze_running; uint64_t ze_raddr; // remote node address uint64_t ze_laddr; // local node address uint16_t ze_proto; size_t ze_rcvmax; - nni_aio * ze_aio; - nni_aio * ze_creq_aio; + nni_aio *ze_aio; + nni_aio *ze_creq_aio; bool ze_creq_active; int ze_creq_try; nni_list ze_aios; @@ -244,7 +244,7 @@ struct zt_ep { zt_creq ze_creqs[zt_listenq]; int ze_creq_head; int ze_creq_tail; - nni_dialer * ze_ndialer; + nni_dialer *ze_ndialer; nni_listener *ze_nlistener; }; @@ -332,11 +332,11 @@ zt_node_resched(zt_node *ztn, int64_t msec) static void zt_node_rcv4_cb(void *arg) { - zt_node * ztn = arg; - nni_aio * aio = ztn->zn_rcv4_aio; + zt_node *ztn = arg; + nni_aio *aio = ztn->zn_rcv4_aio; struct sockaddr_storage sa; - struct sockaddr_in * sin; - nng_sockaddr_in * nsin; + struct sockaddr_in *sin; + nng_sockaddr_in *nsin; int64_t now; if (nni_aio_result(aio) != 0) { @@ -384,10 +384,10 @@ zt_node_rcv4_cb(void *arg) static void zt_node_rcv6_cb(void *arg) { - zt_node * ztn = arg; - nni_aio * aio = ztn->zn_rcv6_aio; + zt_node *ztn = arg; + nni_aio *aio = ztn->zn_rcv6_aio; struct sockaddr_storage sa; - struct sockaddr_in6 * sin6; + struct sockaddr_in6 *sin6; struct nng_sockaddr_in6 *nsin6; int64_t now; @@ -502,7 +502,7 @@ zt_virtual_config(ZT_Node *node, void *userptr, void *thr, uint64_t nwid, const ZT_VirtualNetworkConfig *config) { zt_node *ztn = userptr; - zt_ep * ep; + zt_ep *ep; NNI_ARG_UNUSED(thr); NNI_ARG_UNUSED(netptr); @@ -822,7 +822,7 @@ zt_pipe_recv_data(zt_pipe *p, const uint8_t *data, size_t len) int i; int slot; uint8_t bit; - uint8_t * body; + uint8_t *body; if (len < zt_size_data) { // Runt frame. Drop it and close pipe with a protocol error. @@ -1033,14 +1033,14 @@ zt_virtual_recv(ZT_Node *node, void *userptr, void *thr, uint64_t nwid, void **netptr, uint64_t srcmac, uint64_t dstmac, unsigned int ethertype, unsigned int vlanid, const void *payload, unsigned int len) { - zt_node * ztn = userptr; + zt_node *ztn = userptr; uint8_t op; const uint8_t *data = payload; uint16_t version; uint32_t rport; uint32_t lport; - zt_ep * ep; - zt_pipe * p; + zt_ep *ep; + zt_pipe *p; uint64_t raddr; uint64_t laddr; @@ -1166,7 +1166,7 @@ static const char *zt_files[] = { static struct { size_t len; - void * data; + void *data; } zt_ephemeral_state[ZT_STATE_OBJECT_NETWORK_CONFIG + 1]; static void @@ -1175,7 +1175,7 @@ zt_state_put(ZT_Node *node, void *userptr, void *thr, int len) { zt_node *ztn = userptr; - char * path; + char *path; const char *template; char fname[32]; @@ -1196,8 +1196,8 @@ zt_state_put(ZT_Node *node, void *userptr, void *thr, // all in the same place, but it does not matter since we don't // really persist them anyway. if (strlen(ztn->zn_path) == 0) { - void * ndata = NULL; - void * odata = zt_ephemeral_state[objtype].data; + void *ndata = NULL; + void *odata = zt_ephemeral_state[objtype].data; size_t olen = zt_ephemeral_state[objtype].len; if ((len >= 0) && ((ndata = nni_alloc(len)) != NULL)) { memcpy(ndata, data, len); @@ -1232,11 +1232,11 @@ zt_state_get(ZT_Node *node, void *userptr, void *thr, unsigned int len) { zt_node *ztn = userptr; - char * path; + char *path; char fname[32]; const char *template; size_t sz; - void * buf; + void *buf; NNI_ARG_UNUSED(node); NNI_ARG_UNUSED(thr); @@ -1292,14 +1292,14 @@ zt_wire_packet_send(ZT_Node *node, void *userptr, void *thr, int64_t socket, const struct sockaddr_storage *remaddr, const void *data, unsigned int len, unsigned int ttl) { - nni_aio * aio; + nni_aio *aio; nni_sockaddr addr; - struct sockaddr_in * sin = (void *) remaddr; + struct sockaddr_in *sin = (void *) remaddr; struct sockaddr_in6 *sin6 = (void *) remaddr; - zt_node * ztn = userptr; - nni_plat_udp * udp; - uint8_t * buf; - zt_send_hdr * hdr; + zt_node *ztn = userptr; + nni_plat_udp *udp; + uint8_t *buf; + zt_send_hdr *hdr; nni_iov iov; NNI_ARG_UNUSED(node); @@ -1418,7 +1418,7 @@ zt_node_destroy(zt_node *ztn) static int zt_node_create(zt_node **ztnp, const char *path) { - zt_node * ztn; + zt_node *ztn; nng_sockaddr sa4; nng_sockaddr sa6; int rv; @@ -1519,9 +1519,9 @@ zt_node_create(zt_node **ztnp, const char *path) static int zt_walk_moons(const char *path, void *arg) { - zt_node * ztn = arg; + zt_node *ztn = arg; const char *bn = nni_file_basename(path); - char * end; + char *end; uint64_t moonid; if (strncmp(bn, "moon.", 5) != 0) { @@ -1537,7 +1537,7 @@ zt_walk_moons(const char *path, void *arg) static int zt_node_find(zt_ep *ep) { - zt_node * ztn; + zt_node *ztn; int rv; ZT_VirtualNetworkConfig *cf; @@ -1958,7 +1958,7 @@ zt_pipe_dorecv(zt_pipe *p) for (int i = 0; i < zt_recvq; i++) { zt_fraglist *fl = &p->zp_recvq[i]; - nni_msg * msg; + nni_msg *msg; if (now > (fl->fl_time + zt_recv_stale)) { // fragment list is stale, clean it. @@ -2197,7 +2197,7 @@ static int zt_ep_init(void **epp, nni_url *url, nni_sock *sock, nni_dialer *ndialer, nni_listener *nlistener) { - zt_ep * ep; + zt_ep *ep; uint64_t node; uint64_t port; int rv; @@ -2286,7 +2286,7 @@ zt_listener_init(void **epp, nni_url *url, nni_listener *l) static void zt_ep_close(void *arg) { - zt_ep * ep = arg; + zt_ep *ep = arg; zt_node *ztn; nni_aio *aio; @@ -2488,7 +2488,7 @@ zt_ep_conn_req_cancel(nni_aio *aio, void *arg, int rv) static void zt_ep_conn_req_cb(void *arg) { - zt_ep * ep = arg; + zt_ep *ep = arg; zt_pipe *p; nni_aio *aio = ep->ze_creq_aio; nni_aio *uaio; @@ -2670,7 +2670,7 @@ static int zt_ep_get_url(void *arg, void *data, size_t *szp, nni_type t) { char ustr[64]; // more than plenty - zt_ep * ep = arg; + zt_ep *ep = arg; uint64_t addr; nni_mtx_lock(&zt_lk); @@ -2688,7 +2688,7 @@ zt_ep_set_orbit(void *arg, const void *data, size_t sz, nni_type t) { uint64_t moonid; uint64_t peerid; - zt_ep * ep = arg; + zt_ep *ep = arg; int rv; enum ZT_ResultCode zrv; @@ -2721,7 +2721,7 @@ static int zt_ep_set_deorbit(void *arg, const void *data, size_t sz, nni_type t) { uint64_t moonid; - zt_ep * ep = arg; + zt_ep *ep = arg; int rv; if ((rv = nni_copyin_u64(&moonid, data, sz, t)) == 0) { @@ -2743,15 +2743,15 @@ static int zt_ep_set_add_local_addr(void *arg, const void *data, size_t sz, nni_type t) { nng_sockaddr sa; - zt_ep * ep = arg; + zt_ep *ep = arg; int rv; if ((rv = nni_copyin_sockaddr(&sa, data, sz, t)) == 0) { enum ZT_ResultCode zrv; - zt_node * ztn; + zt_node *ztn; struct sockaddr_storage ss; - struct sockaddr_in * sin; - struct sockaddr_in6 * sin6; + struct sockaddr_in *sin; + struct sockaddr_in6 *sin6; memset(&ss, 0, sizeof(ss)); switch (sa.s_family) { @@ -2878,7 +2878,7 @@ zt_ep_get_nw_status(void *arg, void *buf, size_t *szp, nni_type t) static int zt_ep_set_ping_time(void *arg, const void *data, size_t sz, nni_type t) { - zt_ep * ep = arg; + zt_ep *ep = arg; nng_duration val; int rv; @@ -2932,7 +2932,7 @@ zt_ep_get_ping_tries(void *arg, void *data, size_t *szp, nni_type t) static int zt_ep_set_conn_time(void *arg, const void *data, size_t sz, nni_type t) { - zt_ep * ep = arg; + zt_ep *ep = arg; nng_duration val; int rv; @@ -2986,7 +2986,7 @@ zt_ep_get_conn_tries(void *arg, void *data, size_t *szp, nni_type t) static int zt_ep_get_locaddr(void *arg, void *data, size_t *szp, nni_type t) { - zt_ep * ep = arg; + zt_ep *ep = arg; nng_sockaddr sa; memset(&sa, 0, sizeof(sa)); @@ -3002,7 +3002,7 @@ zt_ep_get_locaddr(void *arg, void *data, size_t *szp, nni_type t) static int zt_pipe_get_locaddr(void *arg, void *data, size_t *szp, nni_type t) { - zt_pipe * p = arg; + zt_pipe *p = arg; nng_sockaddr sa; memset(&sa, 0, sizeof(sa)); @@ -3016,7 +3016,7 @@ zt_pipe_get_locaddr(void *arg, void *data, size_t *szp, nni_type t) static int zt_pipe_get_remaddr(void *arg, void *data, size_t *szp, nni_type t) { - zt_pipe * p = arg; + zt_pipe *p = arg; nng_sockaddr sa; memset(&sa, 0, sizeof(sa)); @@ -3243,14 +3243,6 @@ static struct nni_sp_tran zt_tran = { .tran_fini = zt_tran_fini, }; -#ifndef NNG_ELIDE_DEPRECATED -int -nng_zt_register(void) -{ - return (nni_init()); -} -#endif - void nni_sp_zt_register(void) { diff --git a/src/supplemental/websocket/websocket.c b/src/supplemental/websocket/websocket.c index 53a262c52..daecbb31c 100644 --- a/src/supplemental/websocket/websocket.c +++ b/src/supplemental/websocket/websocket.c @@ -1,5 +1,5 @@ // -// Copyright 2023 Staysail Systems, Inc. +// Copyright 2024 Staysail Systems, Inc. // Copyright 2018 Capitar IT Group BV // Copyright 2019 Devolutions // @@ -18,8 +18,6 @@ #include "supplemental/http/http_api.h" #include "supplemental/sha1/sha1.h" -#include - #include "websocket.h" // This should be removed or handled differently in the future. @@ -1327,7 +1325,7 @@ ws_http_cb_dialer(nni_ws *ws, nni_aio *aio) // There is a race between the dialer closing and any connections // that were in progress completing. - if (d->closed){ + if (d->closed) { rv = NNG_ECLOSED; goto err; } diff --git a/src/testing/nuts.h b/src/testing/nuts.h index 1a4246ab4..708184ab4 100644 --- a/src/testing/nuts.h +++ b/src/testing/nuts.h @@ -44,7 +44,6 @@ extern void nng_fini(void); #include #include #include -#include #include #ifdef __cplusplus diff --git a/tests/ipc.c b/tests/ipc.c index 4f5de38b4..4011f2aed 100644 --- a/tests/ipc.c +++ b/tests/ipc.c @@ -19,7 +19,6 @@ #include #include -#include #include "convey.h" #include "trantest.h" @@ -49,10 +48,8 @@ check_props(nng_msg *msg) So(nng_pipe_get(p, NNG_OPT_REMADDR, &ra, &z) == NNG_EINVAL); #ifdef _WIN32 - So(nng_pipe_get_uint64(p, NNG_OPT_IPC_PEER_UID, &id) == - NNG_ENOTSUP); - So(nng_pipe_get_uint64(p, NNG_OPT_IPC_PEER_GID, &id) == - NNG_ENOTSUP); + So(nng_pipe_get_uint64(p, NNG_OPT_IPC_PEER_UID, &id) == NNG_ENOTSUP); + So(nng_pipe_get_uint64(p, NNG_OPT_IPC_PEER_GID, &id) == NNG_ENOTSUP); So(nng_pipe_get_uint64(p, NNG_OPT_IPC_PEER_ZONEID, &id) == NNG_ENOTSUP); So(nng_pipe_get_uint64(p, NNG_OPT_IPC_PEER_PID, &id) == 0); @@ -68,8 +65,7 @@ check_props(nng_msg *msg) So(nng_pipe_get_uint64(p, NNG_OPT_IPC_PEER_PID, &id) == 0); So(id == (uint64_t) getpid()); #else - So(nng_pipe_get_uint64(p, NNG_OPT_IPC_PEER_PID, &id) == - NNG_ENOTSUP); + So(nng_pipe_get_uint64(p, NNG_OPT_IPC_PEER_PID, &id) == NNG_ENOTSUP); #endif #ifdef NNG_HAVE_GETPEERUCRED @@ -83,6 +79,5 @@ check_props(nng_msg *msg) return (0); } -TestMain("IPC Transport", { - trantest_test_extended("ipc:///tmp/nng_ipc_test_%u", check_props); -}) +TestMain("IPC Transport", + { trantest_test_extended("ipc:///tmp/nng_ipc_test_%u", check_props); }) diff --git a/tests/multistress.c b/tests/multistress.c index e4fa1f2fa..261fb31d0 100644 --- a/tests/multistress.c +++ b/tests/multistress.c @@ -24,10 +24,6 @@ #include #include #include -#include -#include -#include -#include #include "convey.h" #include "stubs.h" diff --git a/tests/reqstress.c b/tests/reqstress.c index 89190c645..afab45016 100644 --- a/tests/reqstress.c +++ b/tests/reqstress.c @@ -16,10 +16,6 @@ #include #include #include -#include -#include -#include -#include #include "convey.h" #include "stubs.h" diff --git a/tests/tls.c b/tests/tls.c index 545d2da26..abfed60d5 100644 --- a/tests/tls.c +++ b/tests/tls.c @@ -1,6 +1,6 @@ // // Copyright 2018 Capitar IT Group BV -// Copyright 2022 Staysail Systems, Inc. +// Copyright 2024 Staysail Systems, Inc. // // This software 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 @@ #include #include #include -#include #include "convey.h" #include "stubs.h" @@ -286,14 +285,10 @@ TestMain("TLS Transport", { trantest_test(&tt); - Convey("We can register the TLS transport", - { So(nng_tls_register() == 0); }); - Convey("We cannot connect to wild cards", { nng_socket s; char addr[NNG_MAXADDRLEN]; - So(nng_tls_register() == 0); So(nng_pair_open(&s) == 0); Reset({ nng_close(s); }); trantest_next_address(addr, "tls+tcp://*:"); @@ -307,7 +302,6 @@ TestMain("TLS Transport", { nng_listener l; nng_dialer d; - So(nng_tls_register() == 0); So(nng_pair_open(&s1) == 0); So(nng_pair_open(&s2) == 0); Reset({ @@ -334,7 +328,6 @@ TestMain("TLS Transport", { nng_dialer d; char * addr; - So(nng_tls_register() == 0); So(nng_pair_open(&s1) == 0); So(nng_pair_open(&s2) == 0); Reset({ @@ -356,7 +349,6 @@ TestMain("TLS Transport", { Convey("Malformed TLS addresses do not panic", { nng_socket s1; - So(nng_tls_register() == 0); So(nng_pair_open(&s1) == 0); Reset({ nng_close(s1); }); diff --git a/tests/trantest.h b/tests/trantest.h index 8a2e11d43..d497b51fd 100644 --- a/tests/trantest.h +++ b/tests/trantest.h @@ -134,13 +134,6 @@ extern void trantest_test(trantest *tt); extern void trantest_test_extended(const char *addr, trantest_proptest_t f); extern void trantest_test_all(const char *addr); -#ifndef NNG_TRANSPORT_ZEROTIER -#define nng_zt_register notransport -#endif -#ifndef NNG_TRANSPORT_WSS -#define nng_wss_register notransport -#endif - void fatal(const char *msg, int rv) { diff --git a/tests/ws.c b/tests/ws.c index b4e087187..d2ae7f9bc 100644 --- a/tests/ws.c +++ b/tests/ws.c @@ -1,5 +1,5 @@ // -// Copyright 2022 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 @@ -14,7 +14,6 @@ #include #include -#include #include "convey.h" #include "stubs.h" @@ -27,7 +26,7 @@ check_props_v4(nng_msg *msg) size_t z; nng_sockaddr la; nng_sockaddr ra; - char * buf; + char *buf; size_t len; p = nng_msg_get_pipe(msg); @@ -49,8 +48,7 @@ check_props_v4(nng_msg *msg) // Request Header z = 0; buf = NULL; - So(nng_pipe_get(p, NNG_OPT_WS_REQUEST_HEADERS, buf, &z) == - NNG_EINVAL); + So(nng_pipe_get(p, NNG_OPT_WS_REQUEST_HEADERS, buf, &z) == NNG_EINVAL); So(z > 0); len = z; So((buf = nng_alloc(len)) != NULL); @@ -81,6 +79,5 @@ check_props_v4(nng_msg *msg) return (0); } -TestMain("WebSocket Transport", { - trantest_test_extended("ws://127.0.0.1:", check_props_v4); -}) +TestMain("WebSocket Transport", + { trantest_test_extended("ws://127.0.0.1:", check_props_v4); }) diff --git a/tests/wss.c b/tests/wss.c index 6d7bc0034..660ede3ba 100644 --- a/tests/wss.c +++ b/tests/wss.c @@ -15,7 +15,6 @@ #include #include #include -#include #include "convey.h" #include "stubs.h" @@ -136,7 +135,7 @@ check_props(nng_msg *msg) size_t z; nng_sockaddr la; nng_sockaddr ra; - char * buf; + char *buf; size_t len; p = nng_msg_get_pipe(msg); @@ -155,8 +154,7 @@ check_props(nng_msg *msg) // Request header z = 0; buf = NULL; - So(nng_pipe_get(p, NNG_OPT_WS_REQUEST_HEADERS, buf, &z) == - NNG_EINVAL); + So(nng_pipe_get(p, NNG_OPT_WS_REQUEST_HEADERS, buf, &z) == NNG_EINVAL); So(z > 0); len = z; So((buf = nng_alloc(len)) != NULL); From 29faf211f76f4b76a8178e4636efd565d6cd0ebe Mon Sep 17 00:00:00 2001 From: jaylin Date: Tue, 18 Feb 2025 15:53:52 +0800 Subject: [PATCH 018/222] * MDF [tests] disable nng_log_err Signed-off-by: jaylin --- src/testing/marry.c | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/testing/marry.c b/src/testing/marry.c index 7441468ff..9ecfbe3c9 100644 --- a/src/testing/marry.c +++ b/src/testing/marry.c @@ -85,7 +85,7 @@ nuts_scratch_addr(const char *scheme, size_t sz, char *addr) } // We should not be here. - nng_log_err("NUTS", "Unknown scheme"); + // nng_log_err("NUTS", "Unknown scheme"); abort(); } From 8815e49155492d699d58045d4e7dcd17fb6becd8 Mon Sep 17 00:00:00 2001 From: Garrett D'Amore Date: Sun, 6 Oct 2024 14:01:46 -0700 Subject: [PATCH 019/222] Point to NNG 1 migration guide --- README.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/README.md b/README.md index ac383b4ef..9cd637677 100644 --- a/README.md +++ b/README.md @@ -20,6 +20,10 @@ Please see [here](UKRAINE.md) for an important message for the people of Russia. > under development and may not be suitable for production use. > Please use the [`stable`](https://github.com/nanomsg/nng/tree/stable) branch > for the latest stable release. +> +> As a major release, there are some breaking API changes, +> but a [migration guide](docs/migrating/nng1.md) is +> available to help with migrating from NNG 1.x. > [!NOTE] > If you are looking for the legacy version of nanomsg, please From 476aa4644a60289863c51833e23c65f07db77a5a Mon Sep 17 00:00:00 2001 From: Garrett D'Amore Date: Sat, 7 Sep 2024 13:35:25 -0700 Subject: [PATCH 020/222] Remove deprecated `nng_pipe_getopt` and friends. Signed-off-by: jaylin --- docs/man/CMakeLists.txt | 1 - docs/man/libnng.3.adoc | 51 +++++----- docs/man/nng_getopt.3.adoc | 1 - docs/man/nng_msg_get_pipe.3.adoc | 4 +- docs/man/nng_msg_set_pipe.3.adoc | 2 +- docs/man/nng_pipe.5.adoc | 2 +- docs/man/nng_pipe_getopt.3.adoc | 155 ------------------------------- include/nng/nng.h | 19 ---- src/nng_legacy.c | 64 +------------ 9 files changed, 33 insertions(+), 266 deletions(-) delete mode 100644 docs/man/nng_pipe_getopt.3.adoc diff --git a/docs/man/CMakeLists.txt b/docs/man/CMakeLists.txt index 93780c0d1..d55df4151 100644 --- a/docs/man/CMakeLists.txt +++ b/docs/man/CMakeLists.txt @@ -137,7 +137,6 @@ if (NNG_ENABLE_DOC) nng_pipe_close nng_pipe_dialer nng_pipe_get - nng_pipe_getopt nng_pipe_id nng_pipe_listener nng_pipe_notify diff --git a/docs/man/libnng.3.adoc b/docs/man/libnng.3.adoc index 6f0def11b..88ab46567 100644 --- a/docs/man/libnng.3.adoc +++ b/docs/man/libnng.3.adoc @@ -66,32 +66,31 @@ The following functions are used with either listeners, or dialers. Listeners accept incoming connection requests, and dialers make them. |=== -|xref:nng_dial.3.adoc[nng_dial]|create and start dialer -|xref:nng_dialer_close.3.adoc[nng_dialer_close]|close dialer -|xref:nng_dialer_create.3.adoc[nng_dialer_create]|create dialer -|xref:nng_dialer_get.3.adoc[nng_dialer_get]|get dialer option -|xref:nng_dialer_getopt.3.adoc[nng_dialer_getopt]|get dialer option (DEPRECATED) -|xref:nng_dialer_id.3.adoc[nng_dialer_id]|get numeric dialer identifier -|xref:nng_dialer_set.3.adoc[nng_dialer_set]|set dialer option -|xref:nng_dialer_setopt.3.adoc[nng_dialer_setopt]|set dialer option (DEPRECATED) -|xref:nng_dialer_start.3.adoc[nng_dialer_start]|start dialer -|xref:nng_listen.3.adoc[nng_listen]|create and start listener -|xref:nng_listener_close.3.adoc[nng_listener_close]|close listener -|xref:nng_listener_create.3.adoc[nng_listener_create]|create listener -|xref:nng_listener_get.3.adoc[nng_listener_get]|get listener option -|xref:nng_listener_getopt.3.adoc[nng_listener_getopt]|get listener option (DEPRECATED) -|xref:nng_listener_id.3.adoc[nng_listener_id]|get numeric listener identifier -|xref:nng_listener_set.3.adoc[nng_listener_set]|set listener option -|xref:nng_listener_setopt.3.adoc[nng_listener_setopt]|set listener option (DEPRECATED) -|xref:nng_listener_start.3.adoc[nng_listener_start]|start listener -|xref:nng_pipe_close.3.adoc[nng_pipe_close]|close pipe -|xref:nng_pipe_dialer.3.adoc[nng_pipe_dialer]|return dialer that created pipe -|xref:nng_pipe_get.3.adoc[nng_pipe_get]|get pipe option -|xref:nng_pipe_getopt.3.adoc[nng_pipe_getopt]|get pipe option (DEPRECATED) -|xref:nng_pipe_id.3.adoc[nng_pipe_id]|get numeric pipe identifier -|xref:nng_pipe_listener.3.adoc[nng_pipe_listener]|return listener that created pipe -|xref:nng_pipe_notify.3.adoc[nng_pipe_notify]|register pipe notification callback -|xref:nng_pipe_socket.3.adoc[nng_pipe_socket]|return owning socket for pipe +|xref:nng_dial.3.adoc[nng_dial()]|create and start dialer +|xref:nng_dialer_close.3.adoc[nng_dialer_close()]|close dialer +|xref:nng_dialer_create.3.adoc[nng_dialer_create()]|create dialer +|xref:nng_dialer_get.3.adoc[nng_dialer_get()]|get dialer option +|xref:nng_dialer_getopt.3.adoc[nng_dialer_getopt()]|get dialer option +|xref:nng_dialer_id.3.adoc[nng_dialer_id()]|get numeric dialer identifier +|xref:nng_dialer_set.3.adoc[nng_dialer_set()]|set dialer option +|xref:nng_dialer_setopt.3.adoc[nng_dialer_setopt()]|set dialer option +|xref:nng_dialer_start.3.adoc[nng_dialer_start()]|start dialer +|xref:nng_listen.3.adoc[nng_listen()]|create and start listener +|xref:nng_listener_close.3.adoc[nng_listener_close()]|close listener +|xref:nng_listener_create.3.adoc[nng_listener_create()]|create listener +|xref:nng_listener_get.3.adoc[nng_listener_get()]|get listener option +|xref:nng_listener_getopt.3.adoc[nng_listener_getopt()]|get listener option +|xref:nng_listener_id.3.adoc[nng_listener_id()]|get numeric listener identifier +|xref:nng_listener_set.3.adoc[nng_listener_set()]|set listener option +|xref:nng_listener_setopt.3.adoc[nng_listener_setopt()]|set listener option +|xref:nng_listener_start.3.adoc[nng_listener_start()]|start listener +|xref:nng_pipe_close.3.adoc[nng_pipe_close()]|close pipe +|xref:nng_pipe_dialer.3.adoc[nng_pipe_dialer()]|return dialer that created pipe +|xref:nng_pipe_get.3.adoc[nng_pipe_get()]|get pipe option +|xref:nng_pipe_id.3.adoc[nng_pipe_id()]|get numeric pipe identifier +|xref:nng_pipe_listener.3.adoc[nng_pipe_listener()]|return listener that created pipe +|xref:nng_pipe_notify.3.adoc[nng_pipe_notify()]|register pipe notification callback +|xref:nng_pipe_socket.3.adoc[nng_pipe_socket()]|return owning socket for pipe |=== === Message Handling Functions diff --git a/docs/man/nng_getopt.3.adoc b/docs/man/nng_getopt.3.adoc index 364d8f719..b4f117cfc 100644 --- a/docs/man/nng_getopt.3.adoc +++ b/docs/man/nng_getopt.3.adoc @@ -134,7 +134,6 @@ These functions return 0 on success, and non-zero otherwise. [.text-left] xref:nng_dialer_getopt.3.adoc[nng_dialer_getopt(3)], xref:nng_listener_getopt.3.adoc[nng_listener_getopt(3)], -xref:nng_pipe_getopt.3.adoc[nng_pipe_getopt(3)], xref:nng_setopt.3.adoc[nng_setopt(3)], xref:nng_strdup.3.adoc[nng_strdup(3)], xref:nng_strerror.3.adoc[nng_strerror(3)], diff --git a/docs/man/nng_msg_get_pipe.3.adoc b/docs/man/nng_msg_get_pipe.3.adoc index 154f4c433..ed387395b 100644 --- a/docs/man/nng_msg_get_pipe.3.adoc +++ b/docs/man/nng_msg_get_pipe.3.adoc @@ -36,7 +36,7 @@ The most usual use case for this is to obtain information about the peer from which the message was received. This can be used to provide different behaviors for different peers, such as a higher level of authentication for peers located on an untrusted network. -The xref:nng_pipe_getopt.3.adoc[`nng_pipe_getopt()`] function +The xref:nng_pipe_get.3.adoc[`nng_pipe_get()`] function is useful in this situation. @@ -56,5 +56,5 @@ None. [.text-left] xref:nng_msg_alloc.3.adoc[nng_msg_alloc(3)], xref:nng_msg_set_pipe.3.adoc[nng_msg_set_pipe(3)], -xref:nng_pipe_getopt.3.adoc[nng_pipe_getopt(3)], +xref:nng_pipe_get.3.adoc[nng_pipe_get(3)], xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_msg_set_pipe.3.adoc b/docs/man/nng_msg_set_pipe.3.adoc index c95cc83f3..9edcc516b 100644 --- a/docs/man/nng_msg_set_pipe.3.adoc +++ b/docs/man/nng_msg_set_pipe.3.adoc @@ -45,6 +45,6 @@ None. [.text-left] xref:nng_msg_alloc.3.adoc[nng_msg_alloc(3)], xref:nng_msg_get_pipe.3.adoc[nng_msg_get_pipe(3)], -xref:nng_pipe_getopt.3.adoc[nng_pipe_getopt(3)], +xref:nng_pipe_get.3.adoc[nng_pipe_get(3)], xref:nng_msg.5.adoc[nng_msg(5)], xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_pipe.5.adoc b/docs/man/nng_pipe.5.adoc index 920fb2c0b..79530dfd3 100644 --- a/docs/man/nng_pipe.5.adoc +++ b/docs/man/nng_pipe.5.adoc @@ -68,7 +68,7 @@ nng_pipe p = NNG_PIPE_INITIALIZER; [.text-left] xref:nng_msg_get_pipe.3.adoc[nng_msg_get_pipe(3)], xref:nng_pipe_close.3.adoc[nng_pipe_close(3)], -xref:nng_pipe_getopt.3.adoc[nng_pipe_getopt(3)], +xref:nng_pipe_get.3.adoc[nng_pipe_get(3)], xref:nng_pipe_dialer.3.adoc[nng_pipe_dialer(3)], xref:nng_pipe_id.3.adoc[nng_pipe_id(3)], xref:nng_pipe_listener.3.adoc[nng_pipe_listener(3)], diff --git a/docs/man/nng_pipe_getopt.3.adoc b/docs/man/nng_pipe_getopt.3.adoc deleted file mode 100644 index 648abbcca..000000000 --- a/docs/man/nng_pipe_getopt.3.adoc +++ /dev/null @@ -1,155 +0,0 @@ -= nng_pipe_getopt(3) -// -// Copyright 2019 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_pipe_getopt - get pipe option - -== SYNOPSIS - -[source, c] ----- -#include - -int nng_pipe_getopt(nng_pipe p, const char *opt, void *val, size_t *valszp); - -int nng_pipe_getopt_bool(nng_pipe p, const char *opt, bool *bvalp); - -int nng_pipe_getopt_int(nng_pipe p, const char *opt, int *ivalp); - -int nng_pipe_getopt_ms(nng_pipe p, const char *opt, nng_duration *durp); - -int nng_pipe_getopt_ptr(nng_pipe p, const char *opt, void **ptr); - -int nng_pipe_getopt_sockaddr(nng_pipe p, const char *opt, nng_sockaddr *sap); - -int nng_pipe_getopt_string(nng_pipe p, const char *opt, char **strp); - -int nng_pipe_getopt_size(nng_pipe p, const char *opt, size_t *zp); - -int nng_pipe_getopt_uint64(nng_pipe p, const char *opt, uint64_t *u64p); - ----- - -== DESCRIPTION - -NOTE: These functions are deprecated. Please see xref:nng_pipe_get.3.adoc[nng_pipe_get]. - -(((options, pipe))) -The `nng_pipe_getopt()` functions are used to retrieve option values for -the xref:nng_pipe.5.adoc[pipe] _p_. -The actual options that may be retrieved in this way -vary, and many are documented in xref:nng_options.5.adoc[nng_options(5)]. -Additionally some transport-specific options and protocol-specific options are -documented with the transports and protocols themselves. - -NOTE: All options on a pipe are read-only values. -Modification of options may be done before the pipe is created using -xref:nng_listener_setopt.3.adoc[`nng_listener_setopt()`] or -xref:nng_dialer_getopt.3.adoc[`nng_dialer_setopt()`]. - -Any option that is set on a dialer or listener will normally be retrievable -from pipes created by that dialer or listener. - -=== Forms - -In all of these forms, the option _opt_ is retrieved from the pipe _p_. - -The details of the type, size, and semantics of the option will depend -on the actual option, and will be documented with the option itself. - -`nng_pipe_getopt()`:: -This is untyped, and can be used to retrieve the value of any option. -A pointer to a buffer to receive the value in _val_, and the size of the -buffer shall be stored at the location referenced by _valszp_. + - + -When the function returns, the actual size of the data copied (or that -would have been copied if sufficient space were present) is stored at -the location referenced by _valszp_. -If the caller's buffer is not large enough to hold the entire object, -then the copy is truncated. -Therefore the caller should check for truncation by verifying that the -size returned in _valszp_ does not exceed the original buffer size. + - + -It is acceptable to pass `NULL` for _val_ if the value in _valszp_ is zero. -This can be used to determine the size of the buffer needed to receive -the object. - -TIP: It may be easier to use one of the typed forms of this function. - -`nng_pipe_getopt_bool()`:: -This function is for options which take a Boolean (`bool`). -The value will be stored at _bvalp_. - -`nng_pipe_getopt_int()`:: -This function is for options which take an integer (`int`). -The value will be stored at _ivalp_. - -`nng_pipe_getopt_ms()`:: -This function is used to retrieve time durations -(xref:nng_duration.5.adoc[`nng_duration`]) in milliseconds, which are stored in -_durp_. - -`nng_pipe_getopt_ptr()`:: -This function is used to retrieve a pointer, _ptr_, to structured data. -The data referenced by _ptr_ is generally managed using other functions. -Note that this form is somewhat special in that the object is generally -not copied, but instead the *pointer* to the object is copied. - -`nng_pipe_getopt_size()`:: -This function is used to retrieve a size into the pointer _zp_, -typically for buffer sizes, message maximum sizes, and similar options. - -`nng_pipe_getopt_sockaddr()`:: -This function is used to retrieve an xref:nng_sockaddr.5.adoc[`nng_sockaddr`] -into _sap_. - -`nng_pipe_getopt_string()`:: -This function is used to retrieve a string into _strp_. -This string is created from the source using xref:nng_strdup.3.adoc[`nng_strdup()`] -and consequently must be freed by the caller using -xref:nng_strfree.3.adoc[`nng_strfree()`] when it is no longer needed. - -`nng_pipe_getopt_uint64()`:: -This function is used to retrieve a 64-bit unsigned value into the value -referenced by _u64p_. -This is typically used for options -related to identifiers, network numbers, and similar. - -== RETURN VALUES - -These functions return 0 on success, and non-zero otherwise. - -== ERRORS - -[horizontal] -`NNG_EBADTYPE`:: Incorrect type for option. -`NNG_ECLOSED`:: Parameter _p_ does not refer to an open pipe. -`NNG_ENOTSUP`:: The option _opt_ is not supported. -`NNG_ENOMEM`:: Insufficient memory exists. -`NNG_EINVAL`:: Size of destination _val_ too small for object. -`NNG_EWRITEONLY`:: The option _opt_ is write-only. - -== SEE ALSO - -[.text-left] -xref:nng_dialer_setopt.3.adoc[nng_dialer_setopt(3)] -xref:nng_getopt.3.adoc[nng_getopt(3)], -xref:nng_listener_setopt.3.adoc[nng_listener_setopt(3)] -xref:nng_msg_get_pipe.3.adoc[nng_msg_get_pipe(3)] -xref:nng_strdup.3.adoc[nng_strdup(3)], -xref:nng_strerror.3.adoc[nng_strerror(3)], -xref:nng_strfree.3.adoc[nng_strfree(3)], -xref:nng_duration.5.adoc[nng_duration(5)], -xref:nng_options.5.adoc[nng_options(5)], -xref:nng_pipe.5.adoc[nng_pipe(5)], -xref:nng_sockaddr.5.adoc[nng_sockaddr(5)], -xref:nng.7.adoc[nng(7)] diff --git a/include/nng/nng.h b/include/nng/nng.h index 9fea280b8..e4ee3f173 100644 --- a/include/nng/nng.h +++ b/include/nng/nng.h @@ -1526,25 +1526,6 @@ NNG_DECL int nng_listener_setopt_ptr( NNG_DECL int nng_listener_setopt_string( nng_listener, const char *, const char *) NNG_DEPRECATED; -// Pipe options. Use nng_pipe_get instead. -NNG_DECL int nng_pipe_getopt( - nng_pipe, const char *, void *, size_t *) NNG_DEPRECATED; -NNG_DECL int nng_pipe_getopt_bool( - nng_pipe, const char *, bool *) NNG_DEPRECATED; -NNG_DECL int nng_pipe_getopt_int(nng_pipe, const char *, int *) NNG_DEPRECATED; -NNG_DECL int nng_pipe_getopt_ms( - nng_pipe, const char *, nng_duration *) NNG_DEPRECATED; -NNG_DECL int nng_pipe_getopt_size( - nng_pipe, const char *, size_t *) NNG_DEPRECATED; -NNG_DECL int nng_pipe_getopt_sockaddr( - nng_pipe, const char *, nng_sockaddr *) NNG_DEPRECATED; -NNG_DECL int nng_pipe_getopt_uint64( - nng_pipe, const char *, uint64_t *) NNG_DEPRECATED; -NNG_DECL int nng_pipe_getopt_ptr( - nng_pipe, const char *, void **) NNG_DEPRECATED; -NNG_DECL int nng_pipe_getopt_string( - nng_pipe, const char *, char **) NNG_DEPRECATED; - // nng_closeall closes all open sockets. Do not call this from // a library; it will affect all sockets. NNG_DECL void nng_closeall(void) NNG_DEPRECATED; diff --git a/src/nng_legacy.c b/src/nng_legacy.c index a041cc06b..65ac7354e 100644 --- a/src/nng_legacy.c +++ b/src/nng_legacy.c @@ -63,7 +63,8 @@ nng_getopt_ms(nng_socket id, const char *n, nng_duration *v) return (nng_socket_get_ms(id, n, v)); } -int nng_getopt_ptr(nng_socket id, const char *n, void **v) +int +nng_getopt_ptr(nng_socket id, const char *n, void **v) { return (nng_socket_get_ptr(id, n, v)); } @@ -241,8 +242,7 @@ nng_dialer_getopt_sockaddr(nng_dialer id, const char *n, nng_sockaddr *v) } int -nng_dialer_setopt( - nng_dialer id, const char *name, const void *v, size_t sz) +nng_dialer_setopt(nng_dialer id, const char *name, const void *v, size_t sz) { return (nng_dialer_set(id, name, v, sz)); } @@ -394,66 +394,10 @@ nng_listener_setopt_string(nng_listener id, const char *n, const char *v) return (nng_listener_set_string(id, n, v)); } -// Pipes - -int -nng_pipe_getopt(nng_pipe id, const char *n, void *v, size_t *sz) -{ - return (nng_pipe_get(id, n, v, sz)); -} - -int -nng_pipe_getopt_int(nng_pipe id, const char *n, int *v) -{ - return (nng_pipe_get_int(id, n, v)); -} - -int -nng_pipe_getopt_bool(nng_pipe id, const char *n, bool *v) -{ - return (nng_pipe_get_bool(id, n, v)); -} - -int -nng_pipe_getopt_size(nng_pipe id, const char *n, size_t *v) -{ - return (nng_pipe_get_size(id, n, v)); -} - -int -nng_pipe_getopt_uint64(nng_pipe id, const char *n, uint64_t *v) -{ - return (nng_pipe_get_uint64(id, n, v)); -} - -int -nng_pipe_getopt_string(nng_pipe id, const char *n, char **v) -{ - return (nng_pipe_get_string(id, n, v)); -} - -int -nng_pipe_getopt_ptr(nng_pipe id, const char *n, void **v) -{ - return (nng_pipe_get_ptr(id, n, v)); -} - -int -nng_pipe_getopt_ms(nng_pipe id, const char *n, nng_duration *v) -{ - return (nng_pipe_get_ms(id, n, v)); -} - -int -nng_pipe_getopt_sockaddr(nng_pipe id, const char *n, nng_sockaddr *v) -{ - return (nng_pipe_get_addr(id, n, v)); -} - void nng_closeall(void) { nni_sock_closeall(); } -#endif // NNG_ELIDE_DEPRECATED \ No newline at end of file +#endif // NNG_ELIDE_DEPRECATED From 761c4af3fda6381943b76f898d11adaf36d1b074 Mon Sep 17 00:00:00 2001 From: Garrett D'Amore Date: Sun, 6 Oct 2024 14:07:30 -0700 Subject: [PATCH 021/222] Remove unused legacy nng_closeall. Signed-off-by: jaylin --- include/nng/nng.h | 12 ------------ src/nng_legacy.c | 8 +------- 2 files changed, 1 insertion(+), 19 deletions(-) diff --git a/include/nng/nng.h b/include/nng/nng.h index e4ee3f173..0082c84eb 100644 --- a/include/nng/nng.h +++ b/include/nng/nng.h @@ -1526,18 +1526,6 @@ NNG_DECL int nng_listener_setopt_ptr( NNG_DECL int nng_listener_setopt_string( nng_listener, const char *, const char *) NNG_DEPRECATED; -// nng_closeall closes all open sockets. Do not call this from -// a library; it will affect all sockets. -NNG_DECL void nng_closeall(void) NNG_DEPRECATED; - -// THese functions are deprecated, but they really serve no useful purpose. -NNG_DECL int nng_stream_set_addr( - nng_stream *, const char *, const nng_sockaddr *) NNG_DEPRECATED; -NNG_DECL int nng_ctx_get_addr( - nng_ctx, const char *, nng_sockaddr *) NNG_DEPRECATED; -NNG_DECL int nng_ctx_set_addr( - nng_ctx, const char *, const nng_sockaddr *) NNG_DEPRECATED; - #endif // NNG_ELIDE_DEPRECATED // nng_init_parameter is used by applications to change a tunable setting. diff --git a/src/nng_legacy.c b/src/nng_legacy.c index 65ac7354e..3dadc4e38 100644 --- a/src/nng_legacy.c +++ b/src/nng_legacy.c @@ -1,5 +1,5 @@ // -// Copyright 2020 Staysail Systems, Inc. +// Copyright 2024 Staysail Systems, Inc. // // This software is supplied under the terms of the MIT License, a // copy of which should be located in the distribution where this @@ -394,10 +394,4 @@ nng_listener_setopt_string(nng_listener id, const char *n, const char *v) return (nng_listener_set_string(id, n, v)); } -void -nng_closeall(void) -{ - nni_sock_closeall(); -} - #endif // NNG_ELIDE_DEPRECATED From de9ae1a149818b3c73ce38ed92971eba03c25972 Mon Sep 17 00:00:00 2001 From: Garrett D'Amore Date: Sat, 7 Sep 2024 14:35:46 -0700 Subject: [PATCH 022/222] Drop unused nng_msg_getopt --- include/nng/nng.h | 4 ---- src/nng_legacy.c | 13 ------------- 2 files changed, 17 deletions(-) diff --git a/include/nng/nng.h b/include/nng/nng.h index 0082c84eb..d9dbabdbc 100644 --- a/include/nng/nng.h +++ b/include/nng/nng.h @@ -1406,10 +1406,6 @@ NNG_DECL int nng_udp_multicast_membership( // These are legacy APIs that have been deprecated. // Their use is strongly discouraged. -// nng_msg_getopt is defunct, and should not be used by programs. It -// always returns NNG_ENOTSUP. -NNG_DECL int nng_msg_getopt(nng_msg *, int, void *, size_t *) NNG_DEPRECATED; - // Socket options. Use nng_socket_get and nng_socket_set instead. NNG_DECL int nng_getopt( nng_socket, const char *, void *, size_t *) NNG_DEPRECATED; diff --git a/src/nng_legacy.c b/src/nng_legacy.c index 3dadc4e38..bbaba36f0 100644 --- a/src/nng_legacy.c +++ b/src/nng_legacy.c @@ -14,19 +14,6 @@ // Eventually they will likely be removed. For now we have // to continue to provide them for compatibility. -// This function is not supported, but we keep it around to -// satisfy link dependencies in old programs. It has never done -// anything useful. -int -nng_msg_getopt(nng_msg *msg, int opt, void *ptr, size_t *szp) -{ - NNI_ARG_UNUSED(msg); - NNI_ARG_UNUSED(opt); - NNI_ARG_UNUSED(ptr); - NNI_ARG_UNUSED(szp); - return (NNG_ENOTSUP); -} - int nng_getopt(nng_socket id, const char *n, void *v, size_t *sz) { From 12a7f2129c523e2c0a5f6d9f8e921764fa7d4dcf Mon Sep 17 00:00:00 2001 From: Garrett D'Amore Date: Sat, 7 Sep 2024 14:20:27 -0700 Subject: [PATCH 023/222] Remove dialer legacy option functions --- docs/man/CMakeLists.txt | 2 - docs/man/libnng.3.adoc | 2 - docs/man/nng_dialer.5.adoc | 4 +- docs/man/nng_dialer_create.3.adoc | 6 +- docs/man/nng_dialer_getopt.3.adoc | 149 ----------------------------- docs/man/nng_dialer_setopt.3.adoc | 134 -------------------------- docs/man/nng_getopt.3.adoc | 1 - docs/man/nng_pipe_get.3.adoc | 153 ------------------------------ docs/man/nng_setopt.3.adoc | 1 - include/nng/nng.h | 36 ------- src/nng_legacy.c | 104 -------------------- 11 files changed, 5 insertions(+), 587 deletions(-) delete mode 100644 docs/man/nng_dialer_getopt.3.adoc delete mode 100644 docs/man/nng_dialer_setopt.3.adoc delete mode 100644 docs/man/nng_pipe_get.3.adoc diff --git a/docs/man/CMakeLists.txt b/docs/man/CMakeLists.txt index d55df4151..f596e530c 100644 --- a/docs/man/CMakeLists.txt +++ b/docs/man/CMakeLists.txt @@ -97,10 +97,8 @@ if (NNG_ENABLE_DOC) nng_dialer_close nng_dialer_create nng_dialer_get - nng_dialer_getopt nng_dialer_id nng_dialer_set - nng_dialer_setopt nng_dialer_start nng_free nng_getopt diff --git a/docs/man/libnng.3.adoc b/docs/man/libnng.3.adoc index 88ab46567..0280d033e 100644 --- a/docs/man/libnng.3.adoc +++ b/docs/man/libnng.3.adoc @@ -70,10 +70,8 @@ Listeners accept incoming connection requests, and dialers make them. |xref:nng_dialer_close.3.adoc[nng_dialer_close()]|close dialer |xref:nng_dialer_create.3.adoc[nng_dialer_create()]|create dialer |xref:nng_dialer_get.3.adoc[nng_dialer_get()]|get dialer option -|xref:nng_dialer_getopt.3.adoc[nng_dialer_getopt()]|get dialer option |xref:nng_dialer_id.3.adoc[nng_dialer_id()]|get numeric dialer identifier |xref:nng_dialer_set.3.adoc[nng_dialer_set()]|set dialer option -|xref:nng_dialer_setopt.3.adoc[nng_dialer_setopt()]|set dialer option |xref:nng_dialer_start.3.adoc[nng_dialer_start()]|start dialer |xref:nng_listen.3.adoc[nng_listen()]|create and start listener |xref:nng_listener_close.3.adoc[nng_listener_close()]|close listener diff --git a/docs/man/nng_dialer.5.adoc b/docs/man/nng_dialer.5.adoc index eb4d7c10d..d6b42a301 100644 --- a/docs/man/nng_dialer.5.adoc +++ b/docs/man/nng_dialer.5.adoc @@ -70,9 +70,9 @@ before it is opened, to prevent confusion with valid open dialers. xref:nng_dial.3.adoc[nng_dial(3)], xref:nng_dialer_close.3.adoc[nng_dialer_close(3)], xref:nng_dialer_create.3.adoc[nng_dialer_create(3)], -xref:nng_dialer_getopt.3.adoc[nng_dialer_getopt(3)], +xref:nng_dialer_get.3.adoc[nng_dialer_get(3)], xref:nng_dialer_id.3.adoc[nng_dialer_id(3)], -xref:nng_dialer_setopt.3.adoc[nng_dialer_setopt(3)], +xref:nng_dialer_set.3.adoc[nng_dialer_set(3)], xref:nng_dialer_start.3.adoc[nng_dialer_start(3)], xref:nng_listener.5.adoc[nng_listener(5)], xref:nng_pipe.5.adoc[nng_pipe(5)], diff --git a/docs/man/nng_dialer_create.3.adoc b/docs/man/nng_dialer_create.3.adoc index d4df92f45..aef9ff9cb 100644 --- a/docs/man/nng_dialer_create.3.adoc +++ b/docs/man/nng_dialer_create.3.adoc @@ -47,7 +47,7 @@ socket might have associated dialers, but might also have associated listeners. It may even have some of each at the same time! The dialer is not started, but may be further configured with -the xref:nng_dialer_setopt.3.adoc[`nng_dialer_setopt()`] family of functions. +the xref:nng_dialer_set.3.adoc[`nng_dialer_set()`] family of functions. Once it is fully configured, the dialer may be started using the xref:nng_dialer_start.3.adoc[`nng_dialer_start()`] function. @@ -71,8 +71,8 @@ This function returns 0 on success, and non-zero otherwise. [.text-left] xref:nng_dial.3.adoc[nng_dial(3)], xref:nng_dialer_close.3.adoc[nng_dialer_close(3)], -xref:nng_dialer_getopt.3.adoc[nng_dialer_getopt(3)], -xref:nng_dialer_setopt.3.adoc[nng_dialer_setopt(3)], +xref:nng_dialer_get.3.adoc[nng_dialer_get(3)], +xref:nng_dialer_set.3.adoc[nng_dialer_set(3)], xref:nng_dialer_start.3.adoc[nng_dialer_start(3)], xref:nng_listener_create.3.adoc[nng_listener_create(3)] xref:nng_strerror.3.adoc[nng_strerror(3)], diff --git a/docs/man/nng_dialer_getopt.3.adoc b/docs/man/nng_dialer_getopt.3.adoc deleted file mode 100644 index a40838193..000000000 --- a/docs/man/nng_dialer_getopt.3.adoc +++ /dev/null @@ -1,149 +0,0 @@ -= nng_dialer_getopt(3) -// -// Copyright 2020 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_dialer_getopt - get dialer option - -== SYNOPSIS - -[source, c] ----- -#include - -int nng_dialer_getopt(nng_dialer d, const char *opt, void *val, size_t *valszp); - -int nng_dialer_getopt_bool(nng_dialer d, const char *opt, bool *bvalp); - -int nng_dialer_getopt_int(nng_dialer d, const char *opt, int *ivalp); - -int nng_dialer_getopt_ms(nng_dialer d, const char *opt, nng_duration *durp); - -int nng_dialer_getopt_ptr(nng_dialer d, const char *opt, void **ptr); - -int nng_dialer_getopt_size(nng_dialer d, const char *opt, size_t *zp); - -int nng_dialer_getopt_sockaddr(nng_dialer d, const char *opt, nng_sockaddr *sap); - -int nng_dialer_getopt_string(nng_dialer d, const char *opt, char **strp); - -int nng_dialer_getopt_uint64(nng_dialer d, const char *opt, uint64_t *u64p); - ----- - -== DESCRIPTION - -IMPORTANT: These functions are deprecated. Please see xref:nng_dialer_get.3.adoc[nng_dialer_get]. -They may not be present if the library was built with `NNG_ELIDE_DEPRECATED`. - -(((options, dialer))) -The `nng_dialer_getopt()` functions are used to retrieve option values for -the xref:nng_dialer.5.adoc[dialer] _d_. -The actual options that may be retrieved in this way -vary, and many are documented in xref:nng_options.5.adoc[nng_options(5)]. - -Additionally some transport-specific options are documented with the transports themselves. - -=== Forms - -In all of these forms, the option _opt_ is retrieved from the dialer _d_. -The forms vary based on the type of the option they take. - -The details of the type, size, and semantics of the option will depend -on the actual option, and will be documented with the option itself. - -`nng_dialer_getopt()`:: -This function is untyped and can be used to retrieve the value of any option. -The caller must store a pointer to a buffer to receive the value in _val_, -and the size of the buffer shall be stored at the location referenced -by _valszp_. + - + -When the function returns, the actual size of the data copied (or that -would have been copied if sufficient space were present) is stored at -the location referenced by _valszp_. -If the caller's buffer is not large -enough to hold the entire object, then the copy is truncated. -Therefore the caller should validate that the returned size in _valszp_ does not -exceed the original buffer size to check for truncation. + - + -It is acceptable to pass `NULL` for _val_ if the value in _valszp_ is zero. -This can be used to determine the size of the buffer needed to receive -the object. - -TIP: It may be easier to use one of the typed forms of this function. - -`nng_dialer_getopt_bool()`:: -This function is for options which take a Boolean (`bool`). -The value will be stored at _bvalp_. - -`nng_dialer_getopt_int()`:: -This function is for options which take an integer (`int`). -The value will be stored at _ivalp_. - -`nng_dialer_getopt_ms()`:: -This function is used to retrieve time xref:nng_duration.5.adoc[durations] -(such as timeouts), stored in _durp_ as a number of milliseconds. -(The special value ((`NNG_DURATION_INFINITE`)) means an infinite amount of time, and -the special value ((`NNG_DURATION_DEFAULT`)) means a context-specific default.) - -`nng_dialer_getopt_ptr()`:: -This function is used to retrieve a pointer, _ptr_, to structured data. -The data referenced by _ptr_ is generally managed using other functions. -Note that this form is somewhat special in that the object is generally -not copied, but instead the *pointer* to the object is copied. - -`nng_dialer_getopt_size()`:: -This function is used to retrieve a size into the pointer _zp_, -typically for buffer sizes, message maximum sizes, and similar options. - -`nng_dialer_getopt_sockaddr()`:: -This function is used to retrieve an xref:nng_sockaddr.5.adoc[`nng_sockaddr`] -into the value referenced by _sap_. - -`nng_dialer_getopt_string()`:: -This function is used to retrieve a string into _strp_. -This string is created from the source using xref:nng_strdup.3.adoc[`nng_strdup()`] -and consequently must be freed by the caller using -xref:nng_strfree.3.adoc[`nng_strfree()`] when it is no longer needed. - -`nng_dialer_getopt_uint64()`:: -This function is used to retrieve a 64-bit unsigned value into the value -referenced by _u64p_. -This is typically used for options related to identifiers, network -numbers, and similar. - -== RETURN VALUES - -These functions returns 0 on success, and non-zero otherwise. - -== ERRORS - -[horizontal] -`NNG_EBADTYPE`:: Incorrect type for option. -`NNG_ECLOSED`:: Parameter _d_ does not refer to an open dialer. -`NNG_EINVAL`:: Size of destination _val_ too small for object. -`NNG_ENOMEM`:: Insufficient memory exists. -`NNG_ENOTSUP`:: The option _opt_ is not supported. -`NNG_EWRITEONLY`:: The option _opt_ is write-only. - -== SEE ALSO - -[.text-left] -xref:nng_dialer_create.3.adoc[nng_dialer_create(3)] -xref:nng_dialer_setopt.3.adoc[nng_dialer_setopt(3)] -xref:nng_strdup.3.adoc[nng_strdup(3)], -xref:nng_strerror.3.adoc[nng_strerror(3)], -xref:nng_strfree.3.adoc[nng_strfree(3)], -xref:nng_dialer.5.adoc[nng_dialer(5)], -xref:nng_duration.5.adoc[nng_duration(5)], -xref:nng_options.5.adoc[nng_options(5)], -xref:nng_sockaddr.5.adoc[nng_sockaddr(5)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_dialer_setopt.3.adoc b/docs/man/nng_dialer_setopt.3.adoc deleted file mode 100644 index 3aaff1eb1..000000000 --- a/docs/man/nng_dialer_setopt.3.adoc +++ /dev/null @@ -1,134 +0,0 @@ -= nng_dialer_setopt(3) -// -// Copyright 2020 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_dialer_setopt - set dialer option - -== SYNOPSIS - -[source, c] ----- -#include - -int nng_dialer_setopt(nng_dialer d, const char *opt, const void *val, - size_t valsz); - -int nng_dialer_setopt_bool(nng_dialer d, const char *opt, bool bval); - -int nng_dialer_setopt_int(nng_dialer d, const char *opt, int ival); - -int nng_dialer_setopt_ms(nng_dialer d, const char *opt, nng_duration dur); - -int nng_dialer_setopt_ptr(nng_dialer d, const char *opt, void *ptr); - -int nng_dialer_setopt_size(nng_dialer d, const char *opt, size_t z); - -int nng_dialer_setopt_string(nng_dialer d, const char *opt, const char *str); - -int nng_dialer_setopt_uint64(nng_dialer d, const char *opt, uint64_t u64); - ----- - -== DESCRIPTION - -IMPORTANT: These functions are deprecated. Please see xref:nng_dialer_set.3.adoc[nng_dialer_set]. -They may not be present if the library was built with `NNG_ELIDE_DEPRECATED`. - -(((options, dialer))) -The `nng_dialer_setopt()` functions are used to configure options for -the xref:nng_dialer.5.adoc[dialer] _d_. -The actual options that may be configured in this way -vary, and many are documented in xref:nng_options.5.adoc[nng_options(5)]. - -Additionally some transport-specific options are documented with the -transports themselves. - -NOTE: Once a dialer has started, it is generally not possible to change -its configuration. - -=== Forms - -In all of these forms, the option _opt_ is configured on the dialer _d_. - -The details of the type, size, and semantics of the option will depend -on the actual option, and will be documented with the option itself. - -`nng_dialer_setopt()`:: -This function is untyped, and can be used to configure any arbitrary data. -The _val_ pointer addresses the data to copy, and _valsz_ is the -size of the objected located at _val_. - -TIP: It may be easier to use one of the typed forms of this function. - -`nng_dialer_setopt_bool()`:: -This function is for options which take a Boolean (`bool`). -The _bval_ is passed to the option. - -`nng_dialer_setopt_int()`:: -This function is for options which take an integer (`int`). -The _ival_ is passed to the option. - -`nng_dialer_setopt_ms()`:: -This function is used to configure time durations (such as timeouts) using -type xref:nng_duration.5.adoc[`nng_duration`]. -The duration _dur_ is an integer number of milliseconds. - -`nng_dialer_setopt_ptr()`:: -This function is used to pass a pointer, _ptr_, to structured data. -The data referenced by _ptr_ is generally managed by other functions. -For example, TLS configuration objects created with -(xref:nng_tls_config_alloc.3tls.adoc[`nng_tls_config_alloc()`]) -can be passed this way. - -NOTE: This form is somewhat special in that the object is generally -not copied, but instead the *pointer* to the object is copied. - -`nng_dialer_setopt_size()`:: -This function is used to configure a size, _z_, typically for buffer sizes, -message maximum sizes, and similar options. - -`nng_dialer_setopt_string()`:: -This function is used to pass configure a string, _str_. -Strings passed this way must be legal UTF-8 or ASCII strings, terminated -with a `NUL` (`\0`) byte. -(Other constraints may apply as well, see the documentation for each option -for details.) - -`nng_dialer_setopt_uint64()`:: -This function is used to configure a 64-bit unsigned value, _u64_. -This is typically used for options related to identifiers, network numbers, -and such. - -== RETURN VALUES - -These functions return 0 on success, and non-zero otherwise. - -== ERRORS - -[horizontal] -`NNG_EBADTYPE`:: Incorrect type for option. -`NNG_ECLOSED`:: Parameter _d_ does not refer to an open dialer. -`NNG_EINVAL`:: The value being passed is invalid. -`NNG_ENOTSUP`:: The option _opt_ is not supported. -`NNG_EREADONLY`:: The option _opt_ is read-only. -`NNG_ESTATE`:: The dialer _d_ is already started. - -== SEE ALSO - -[.text-left] -xref:nng_dialer_create.3.adoc[nng_dialer_create(3)] -xref:nng_dialer_getopt.3.adoc[nng_dialer_getopt(3)] -xref:nng_strerror.3.adoc[nng_strerror(3)], -xref:nng_dialer.5.adoc[nng_dialer(5)], -xref:nng_duration.5.adoc[nng_duration(5)], -xref:nng_options.5.adoc[nng_options(5)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_getopt.3.adoc b/docs/man/nng_getopt.3.adoc index b4f117cfc..4a648ae2b 100644 --- a/docs/man/nng_getopt.3.adoc +++ b/docs/man/nng_getopt.3.adoc @@ -132,7 +132,6 @@ These functions return 0 on success, and non-zero otherwise. == SEE ALSO [.text-left] -xref:nng_dialer_getopt.3.adoc[nng_dialer_getopt(3)], xref:nng_listener_getopt.3.adoc[nng_listener_getopt(3)], xref:nng_setopt.3.adoc[nng_setopt(3)], xref:nng_strdup.3.adoc[nng_strdup(3)], diff --git a/docs/man/nng_pipe_get.3.adoc b/docs/man/nng_pipe_get.3.adoc deleted file mode 100644 index 51a8debfd..000000000 --- a/docs/man/nng_pipe_get.3.adoc +++ /dev/null @@ -1,153 +0,0 @@ -= nng_pipe_get(3) -// -// Copyright 2019 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_pipe_get - get pipe option - -== SYNOPSIS - -[source, c] ----- -#include - -int nng_pipe_get(nng_pipe p, const char *opt, void *val, size_t *valszp); - -int nng_pipe_get_bool(nng_pipe p, const char *opt, bool *bvalp); - -int nng_pipe_get_int(nng_pipe p, const char *opt, int *ivalp); - -int nng_pipe_get_ms(nng_pipe p, const char *opt, nng_duration *durp); - -int nng_pipe_get_ptr(nng_pipe p, const char *opt, void **ptr); - -int nng_pipe_get_addr(nng_pipe p, const char *opt, nng_sockaddr *sap); - -int nng_pipe_get_string(nng_pipe p, const char *opt, char **strp); - -int nng_pipe_get_size(nng_pipe p, const char *opt, size_t *zp); - -int nng_pipe_get_uint64(nng_pipe p, const char *opt, uint64_t *u64p); - ----- - -== DESCRIPTION - -(((options, pipe))) -The `nng_pipe_get()` functions are used to retrieve option values for -the xref:nng_pipe.5.adoc[pipe] _p_. -The actual options that may be retrieved in this way -vary, and many are documented in xref:nng_options.5.adoc[nng_options(5)]. -Additionally some transport-specific options and protocol-specific options are -documented with the transports and protocols themselves. - -NOTE: All options on a pipe are read-only values. -Modification of options may be done before the pipe is created using -xref:nng_listener_set.3.adoc[`nng_listener_set()`] or -xref:nng_dialer_get.3.adoc[`nng_dialer_set()`]. - -Any option that is set on a dialer or listener will normally be retrievable -from pipes created by that dialer or listener. - -=== Forms - -In all of these forms, the option _opt_ is retrieved from the pipe _p_. - -The details of the type, size, and semantics of the option will depend -on the actual option, and will be documented with the option itself. - -`nng_pipe_get()`:: -This is untyped, and can be used to retrieve the value of any option. -A pointer to a buffer to receive the value in _val_, and the size of the -buffer shall be stored at the location referenced by _valszp_. + - + -When the function returns, the actual size of the data copied (or that -would have been copied if sufficient space were present) is stored at -the location referenced by _valszp_. -If the caller's buffer is not large enough to hold the entire object, -then the copy is truncated. -Therefore the caller should check for truncation by verifying that the -size returned in _valszp_ does not exceed the original buffer size. + - + -It is acceptable to pass `NULL` for _val_ if the value in _valszp_ is zero. -This can be used to determine the size of the buffer needed to receive -the object. - -TIP: It may be easier to use one of the typed forms of this function. - -`nng_pipe_get_bool()`:: -This function is for options which take a Boolean (`bool`). -The value will be stored at _bvalp_. - -`nng_pipe_get_int()`:: -This function is for options which take an integer (`int`). -The value will be stored at _ivalp_. - -`nng_pipe_get_ms()`:: -This function is used to retrieve time durations -(xref:nng_duration.5.adoc[`nng_duration`]) in milliseconds, which are stored in -_durp_. - -`nng_pipe_get_ptr()`:: -This function is used to retrieve a pointer, _ptr_, to structured data. -The data referenced by _ptr_ is generally managed using other functions. -Note that this form is somewhat special in that the object is generally -not copied, but instead the *pointer* to the object is copied. - -`nng_pipe_get_size()`:: -This function is used to retrieve a size into the pointer _zp_, -typically for buffer sizes, message maximum sizes, and similar options. - -`nng_pipe_get_addr()`:: -This function is used to retrieve an xref:nng_sockaddr.5.adoc[`nng_sockaddr`] -into _sap_. - -`nng_pipe_get_string()`:: -This function is used to retrieve a string into _strp_. -This string is created from the source using xref:nng_strdup.3.adoc[`nng_strdup()`] -and consequently must be freed by the caller using -xref:nng_strfree.3.adoc[`nng_strfree()`] when it is no longer needed. - -`nng_pipe_get_uint64()`:: -This function is used to retrieve a 64-bit unsigned value into the value -referenced by _u64p_. -This is typically used for options -related to identifiers, network numbers, and similar. - -== RETURN VALUES - -These functions return 0 on success, and non-zero otherwise. - -== ERRORS - -[horizontal] -`NNG_EBADTYPE`:: Incorrect type for option. -`NNG_ECLOSED`:: Parameter _p_ does not refer to an open pipe. -`NNG_ENOTSUP`:: The option _opt_ is not supported. -`NNG_ENOMEM`:: Insufficient memory exists. -`NNG_EINVAL`:: Size of destination _val_ too small for object. -`NNG_EWRITEONLY`:: The option _opt_ is write-only. - -== SEE ALSO - -[.text-left] -xref:nng_dialer_set.3.adoc[nng_dialer_set(3)] -xref:nng_socket_get.3.adoc[nng_socket_get(3)], -xref:nng_listener_set.3.adoc[nng_listener_set(3)] -xref:nng_msg_get_pipe.3.adoc[nng_msg_get_pipe(3)] -xref:nng_strdup.3.adoc[nng_strdup(3)], -xref:nng_strerror.3.adoc[nng_strerror(3)], -xref:nng_strfree.3.adoc[nng_strfree(3)], -xref:nng_duration.5.adoc[nng_duration(5)], -xref:nng_options.5.adoc[nng_options(5)], -xref:nng_pipe.5.adoc[nng_pipe(5)], -xref:nng_sockaddr.5.adoc[nng_sockaddr(5)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_setopt.3.adoc b/docs/man/nng_setopt.3.adoc index 6c21cf956..61926d69d 100644 --- a/docs/man/nng_setopt.3.adoc +++ b/docs/man/nng_setopt.3.adoc @@ -119,7 +119,6 @@ These functions return 0 on success, and non-zero otherwise. [.text-left] xref:nng_getopt.3.adoc[nng_getopt(3)], -xref:nng_dialer_setopt.3.adoc[nng_dialer_setopt(3)], xref:nng_listener_setopt.3.adoc[nng_listener_setopt(3)], xref:nng_strerror.3.adoc[nng_strerror(3)], xref:nng_options.5.adoc[nng_options(5)], diff --git a/include/nng/nng.h b/include/nng/nng.h index d9dbabdbc..810041020 100644 --- a/include/nng/nng.h +++ b/include/nng/nng.h @@ -1450,42 +1450,6 @@ NNG_DECL int nng_ctx_setopt_ms( nng_ctx, const char *, nng_duration) NNG_DEPRECATED; NNG_DECL int nng_ctx_setopt_size(nng_ctx, const char *, size_t) NNG_DEPRECATED; -// Dialer options. Use nng_dialer_get and nng_dialer_set instead. -NNG_DECL int nng_dialer_getopt( - nng_dialer, const char *, void *, size_t *) NNG_DEPRECATED; -NNG_DECL int nng_dialer_getopt_bool( - nng_dialer, const char *, bool *) NNG_DEPRECATED; -NNG_DECL int nng_dialer_getopt_int( - nng_dialer, const char *, int *) NNG_DEPRECATED; -NNG_DECL int nng_dialer_getopt_ms( - nng_dialer, const char *, nng_duration *) NNG_DEPRECATED; -NNG_DECL int nng_dialer_getopt_size( - nng_dialer, const char *, size_t *) NNG_DEPRECATED; -NNG_DECL int nng_dialer_getopt_sockaddr( - nng_dialer, const char *, nng_sockaddr *) NNG_DEPRECATED; -NNG_DECL int nng_dialer_getopt_uint64( - nng_dialer, const char *, uint64_t *) NNG_DEPRECATED; -NNG_DECL int nng_dialer_getopt_ptr( - nng_dialer, const char *, void **) NNG_DEPRECATED; -NNG_DECL int nng_dialer_getopt_string( - nng_dialer, const char *, char **) NNG_DEPRECATED; -NNG_DECL int nng_dialer_setopt( - nng_dialer, const char *, const void *, size_t) NNG_DEPRECATED; -NNG_DECL int nng_dialer_setopt_bool( - nng_dialer, const char *, bool) NNG_DEPRECATED; -NNG_DECL int nng_dialer_setopt_int( - nng_dialer, const char *, int) NNG_DEPRECATED; -NNG_DECL int nng_dialer_setopt_ms( - nng_dialer, const char *, nng_duration) NNG_DEPRECATED; -NNG_DECL int nng_dialer_setopt_size( - nng_dialer, const char *, size_t) NNG_DEPRECATED; -NNG_DECL int nng_dialer_setopt_uint64( - nng_dialer, const char *, uint64_t) NNG_DEPRECATED; -NNG_DECL int nng_dialer_setopt_ptr( - nng_dialer, const char *, void *) NNG_DEPRECATED; -NNG_DECL int nng_dialer_setopt_string( - nng_dialer, const char *, const char *) NNG_DEPRECATED; - // Listener options. Use nng_listener_get and nng_listener_set instead. NNG_DECL int nng_listener_getopt( nng_listener, const char *, void *, size_t *) NNG_DEPRECATED; diff --git a/src/nng_legacy.c b/src/nng_legacy.c index bbaba36f0..bb6cf2e5a 100644 --- a/src/nng_legacy.c +++ b/src/nng_legacy.c @@ -172,110 +172,6 @@ nng_ctx_setopt_size(nng_ctx id, const char *n, size_t v) return (nng_ctx_set_size(id, n, v)); } -// Dialers. - -int -nng_dialer_getopt(nng_dialer id, const char *n, void *v, size_t *sz) -{ - return (nng_dialer_get(id, n, v, sz)); -} - -int -nng_dialer_getopt_int(nng_dialer id, const char *n, int *v) -{ - return (nng_dialer_get_int(id, n, v)); -} - -int -nng_dialer_getopt_bool(nng_dialer id, const char *n, bool *v) -{ - return (nng_dialer_get_bool(id, n, v)); -} - -int -nng_dialer_getopt_size(nng_dialer id, const char *n, size_t *v) -{ - return (nng_dialer_get_size(id, n, v)); -} - -int -nng_dialer_getopt_uint64(nng_dialer id, const char *n, uint64_t *v) -{ - return (nng_dialer_get_uint64(id, n, v)); -} - -int -nng_dialer_getopt_string(nng_dialer id, const char *n, char **v) -{ - return (nng_dialer_get_string(id, n, v)); -} - -int -nng_dialer_getopt_ptr(nng_dialer id, const char *n, void **v) -{ - return (nng_dialer_get_ptr(id, n, v)); -} - -int -nng_dialer_getopt_ms(nng_dialer id, const char *n, nng_duration *v) -{ - return (nng_dialer_get_ms(id, n, v)); -} - -int -nng_dialer_getopt_sockaddr(nng_dialer id, const char *n, nng_sockaddr *v) -{ - return (nng_dialer_get_addr(id, n, v)); -} - -int -nng_dialer_setopt(nng_dialer id, const char *name, const void *v, size_t sz) -{ - return (nng_dialer_set(id, name, v, sz)); -} - -int -nng_dialer_setopt_bool(nng_dialer id, const char *n, bool v) -{ - return (nng_dialer_set_bool(id, n, v)); -} - -int -nng_dialer_setopt_int(nng_dialer id, const char *n, int v) -{ - return (nng_dialer_set_int(id, n, v)); -} - -int -nng_dialer_setopt_ms(nng_dialer id, const char *n, nng_duration v) -{ - return (nng_dialer_set_ms(id, n, v)); -} - -int -nng_dialer_setopt_size(nng_dialer id, const char *n, size_t v) -{ - return (nng_dialer_set_size(id, n, v)); -} - -int -nng_dialer_setopt_uint64(nng_dialer id, const char *n, uint64_t v) -{ - return (nng_dialer_set_uint64(id, n, v)); -} - -int -nng_dialer_setopt_ptr(nng_dialer id, const char *n, void *v) -{ - return (nng_dialer_set_ptr(id, n, v)); -} - -int -nng_dialer_setopt_string(nng_dialer id, const char *n, const char *v) -{ - return (nng_dialer_set_string(id, n, v)); -} - // Listeners. int From dcb7fd99da0ae32cfe96fb281e7534f89a5e2d74 Mon Sep 17 00:00:00 2001 From: Garrett D'Amore Date: Sat, 7 Sep 2024 14:34:55 -0700 Subject: [PATCH 024/222] Drop the legacy listener option functions --- docs/man/CMakeLists.txt | 2 - docs/man/libnng.3.adoc | 2 - docs/man/nng_getopt.3.adoc | 1 - docs/man/nng_listener.5.adoc | 4 +- docs/man/nng_listener_create.3.adoc | 6 +- docs/man/nng_listener_getopt.3.adoc | 150 ---------------------------- docs/man/nng_listener_setopt.3.adoc | 136 ------------------------- docs/man/nng_setopt.3.adoc | 1 - docs/man/nng_zerotier.7.adoc | 2 +- include/nng/nng.h | 36 ------- src/nng_legacy.c | 105 ------------------- tests/zt.c | 21 ++-- 12 files changed, 16 insertions(+), 450 deletions(-) delete mode 100644 docs/man/nng_listener_getopt.3.adoc delete mode 100644 docs/man/nng_listener_setopt.3.adoc diff --git a/docs/man/CMakeLists.txt b/docs/man/CMakeLists.txt index f596e530c..f1f9c42eb 100644 --- a/docs/man/CMakeLists.txt +++ b/docs/man/CMakeLists.txt @@ -106,10 +106,8 @@ if (NNG_ENABLE_DOC) nng_listener_close nng_listener_create nng_listener_get - nng_listener_getopt nng_listener_id nng_listener_set - nng_listener_setopt nng_listener_start nng_msg_alloc nng_msg_append diff --git a/docs/man/libnng.3.adoc b/docs/man/libnng.3.adoc index 0280d033e..b7190292c 100644 --- a/docs/man/libnng.3.adoc +++ b/docs/man/libnng.3.adoc @@ -77,10 +77,8 @@ Listeners accept incoming connection requests, and dialers make them. |xref:nng_listener_close.3.adoc[nng_listener_close()]|close listener |xref:nng_listener_create.3.adoc[nng_listener_create()]|create listener |xref:nng_listener_get.3.adoc[nng_listener_get()]|get listener option -|xref:nng_listener_getopt.3.adoc[nng_listener_getopt()]|get listener option |xref:nng_listener_id.3.adoc[nng_listener_id()]|get numeric listener identifier |xref:nng_listener_set.3.adoc[nng_listener_set()]|set listener option -|xref:nng_listener_setopt.3.adoc[nng_listener_setopt()]|set listener option |xref:nng_listener_start.3.adoc[nng_listener_start()]|start listener |xref:nng_pipe_close.3.adoc[nng_pipe_close()]|close pipe |xref:nng_pipe_dialer.3.adoc[nng_pipe_dialer()]|return dialer that created pipe diff --git a/docs/man/nng_getopt.3.adoc b/docs/man/nng_getopt.3.adoc index 4a648ae2b..9b61fc5f6 100644 --- a/docs/man/nng_getopt.3.adoc +++ b/docs/man/nng_getopt.3.adoc @@ -132,7 +132,6 @@ These functions return 0 on success, and non-zero otherwise. == SEE ALSO [.text-left] -xref:nng_listener_getopt.3.adoc[nng_listener_getopt(3)], xref:nng_setopt.3.adoc[nng_setopt(3)], xref:nng_strdup.3.adoc[nng_strdup(3)], xref:nng_strerror.3.adoc[nng_strerror(3)], diff --git a/docs/man/nng_listener.5.adoc b/docs/man/nng_listener.5.adoc index 66eb736db..1af9c0ad3 100644 --- a/docs/man/nng_listener.5.adoc +++ b/docs/man/nng_listener.5.adoc @@ -67,9 +67,9 @@ before it is opened, to prevent confusion with valid open listener. xref:nng_listen.3.adoc[nng_listen(3)], xref:nng_listener_close.3.adoc[nng_listener_close(3)], xref:nng_listener_create.3.adoc[nng_listener_create(3)], -xref:nng_listener_getopt.3.adoc[nng_listener_getopt(3)], +xref:nng_listener_get.3.adoc[nng_listener_get(3)], xref:nng_listener_id.3.adoc[nng_listener_id(3)], -xref:nng_listener_setopt.3.adoc[nng_listener_setopt(3)], +xref:nng_listener_set.3.adoc[nng_listener_set(3)], xref:nng_listener_start.3.adoc[nng_listener_start(3)], xref:nng_dialer.5.adoc[nng_dialer(5)], xref:nng_pipe.5.adoc[nng_pipe(5)], diff --git a/docs/man/nng_listener_create.3.adoc b/docs/man/nng_listener_create.3.adoc index edf19af7b..2e97e1c18 100644 --- a/docs/man/nng_listener_create.3.adoc +++ b/docs/man/nng_listener_create.3.adoc @@ -43,7 +43,7 @@ but might also have associated listeners. It may even have some of each at the same time! The listener is not started, but may be further configured with -the xref:nng_listener_setopt.3.adoc[`nng_listener_setopt()`] family of +the xref:nng_listener_set.3.adoc[`nng_listener_set()`] family of functions. Once it is fully configured, the listener may be started using the @@ -69,8 +69,8 @@ This function returns 0 on success, and non-zero otherwise. xref:nng_dialer_create.3.adoc[nng_dialer_create(3)] xref:nng_listen.3.adoc[nng_listen(3)], xref:nng_listener_close.3.adoc[nng_listener_close(3)], -xref:nng_listener_getopt.3.adoc[nng_listener_getopt(3)], -xref:nng_listener_setopt.3.adoc[nng_listener_setopt(3)], +xref:nng_listener_get.3.adoc[nng_listener_get(3)], +xref:nng_listener_set.3.adoc[nng_listener_set(3)], xref:nng_listener_start.3.adoc[nng_listener_start(3)], xref:nng_strerror.3.adoc[nng_strerror(3)], xref:nng_listener.5.adoc[nng_listener(5)], diff --git a/docs/man/nng_listener_getopt.3.adoc b/docs/man/nng_listener_getopt.3.adoc deleted file mode 100644 index 828f440d9..000000000 --- a/docs/man/nng_listener_getopt.3.adoc +++ /dev/null @@ -1,150 +0,0 @@ -= nng_listener_getopt(3) -// -// Copyright 2020 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_listener_getopt - get listener option - -== SYNOPSIS - -[source, c] ----- -#include - -int nng_listener_getopt(nng_listener l, const char *opt, void *val, size_t *valszp); - -int nng_listener_getopt_bool(nng_listener l, const char *opt, bool *bvalp); - -int nng_listener_getopt_int(nng_listener l, const char *opt, int *ivalp); - -int nng_listener_getopt_ms(nng_listener l, const char *opt, nng_duration *durp); - -int nng_listener_getopt_ptr(nng_listener l, const char *opt, void **ptr); - -int nng_listener_getopt_size(nng_listener l, const char *opt, size_t *zp); - -int nng_listener_getopt_sockaddr(nng_listener l, const char *opt, nng_sockaddr *sap); - -int nng_listener_getopt_string(nng_listener l, const char *opt, char **strp); - -int nng_listener_getopt_uint64(nng_listener l, const char *opt, uint64_t *u64p); - ----- - -== DESCRIPTION - -IMPORTANT: These functions are deprecated. Please see xref:nng_listener_get.3.adoc[nng_listener_get]. -They may not be present if the library was built with `NNG_ELIDE_DEPRECATED`. - -(((options, listener))) -The `nng_listener_getopt()` functions are used to retrieve option values for -the xref:nng_listener.5.adoc[listener] _l_. -The actual options that may be retrieved in this way -vary, and many are documented in xref:nng_options.5.adoc[nng_options(5)]. - -Additionally some transport-specific options -are documented with the transports themselves. - -=== Forms - -In all of these forms, the option _opt_ is retrieved from the listener _l_. -The forms vary based on the type of the option they take. - -The details of the type, size, and semantics of the option will depend -on the actual option, and will be documented with the option itself. - -`nng_listener_getopt()`:: -This function is untyped and can be used to retrieve the value of any option. -The caller must store a pointer to a buffer to receive the value in _val_, -and the size of the buffer shall be stored at the location referenced -by _valszp_. + - + -When the function returns, the actual size of the data copied (or that -would have been copied if sufficient space were present) is stored at -the location referenced by _valszp_. -If the caller's buffer is not large -enough to hold the entire object, then the copy is truncated. Therefore -the caller should validate that the returned size in _valszp_ does not -exceed the original buffer size to check for truncation. + - + -It is acceptable to pass `NULL` for _val_ if the value in _valszp_ is zero. -This can be used to determine the size of the buffer needed to receive -the object. - -TIP: It may be easier to use one of the typed forms of this function. - -`nng_listener_getopt_bool()`:: -This function is for options which take a Boolean (`bool`). -The value will be stored at _bvalp_. - -`nng_listener_getopt_int()`:: -This function is for options which take an integer (`int`). -The value will be stored at _ivalp_. - -`nng_listener_getopt_ms()`:: -This function is used to retrieve time xref:nng_duration.5.adoc[durations] -(such as timeouts), stored in _durp_ as a number of milliseconds. - -`nng_listener_getopt_ptr()`:: -This function is used to retrieve a pointer, _ptr_, to structured data. -The data referenced by _ptr_ is generally managed using other functions. -Note that this form is somewhat special in that the object is generally -not copied, but instead the *pointer* to the object is copied. - -`nng_listener_getopt_size()`:: -This function is used to retrieve a size into the pointer _zp_, -typically for buffer sizes, message maximum sizes, and similar options. - -`nng_listener_getopt_sockaddr()`:: -This function is used to retrieve an xref:nng_sockaddr.5.adoc[`nng_sockaddr`] -into the value referenced by _sap_. - -`nng_listener_getopt_string()`:: -This function is used to retrieve a string into _strp_. -This string is created from the source using xref:nng_strdup.3.adoc[`nng_strdup()`] -and consequently must be freed by the caller using -xref:nng_strfree.3.adoc[`nng_strfree()`] when it is no longer needed. - -`nng_listener_getopt_uint64()`:: -This function is used to retrieve a 64-bit unsigned value into the value -referenced by _u64p_. -This is typically used for options related to identifiers, network -numbers, and similar. - -== RETURN VALUES - -These functions return 0 on success, and non-zero otherwise. - -== ERRORS - -[horizontal] -`NNG_EBADTYPE`:: Incorrect type for option. -`NNG_ECLOSED`:: Parameter _l_ does not refer to an open listener. -`NNG_EINVAL`:: Size of destination _val_ too small for object. -`NNG_ENOMEM`:: Insufficient memory exists. -`NNG_ENOTSUP`:: The option _opt_ is not supported. -`NNG_EWRITEONLY`:: The option _opt_ is write-only. - -== SEE ALSO - -[.text-left] -xref:nng_listen.3.adoc[nng_listen(3)], -xref:nng_listener_create.3.adoc[nng_listener_create(3)] -xref:nng_listener_setopt.3.adoc[nng_listener_setopt(3)] -xref:nng_getopt.3.adoc[nng_getopt(3)], -xref:nng_strdup.3.adoc[nng_strdup(3)], -xref:nng_strerror.3.adoc[nng_strerror(3)], -xref:nng_strfree.3.adoc[nng_strfree(3)], -xref:nng_duration.5.adoc[nng_duration(5)], -xref:nng_listener.5.adoc[nng_listener(5)], -xref:nng_options.5.adoc[nng_options(5)], -xref:nng_sockaddr.5.adoc[nng_sockaddr(5)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_listener_setopt.3.adoc b/docs/man/nng_listener_setopt.3.adoc deleted file mode 100644 index 25411adcd..000000000 --- a/docs/man/nng_listener_setopt.3.adoc +++ /dev/null @@ -1,136 +0,0 @@ -= nng_listener_setopt(3) -// -// Copyright 2020 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_listener_setopt - set listener option - -== SYNOPSIS - -[source, c] ----- -#include - -int nng_listener_setopt(nng_listener l, const char *opt, const void *val, - size_t valsz); - -int nng_listener_setopt_bool(nng_listener l, const char *opt, bool bval); - -int nng_listener_setopt_int(nng_listener l, const char *opt, int ival); - -int nng_listener_setopt_ms(nng_listener l, const char *opt, nng_duration dur); - -int nng_listener_setopt_ptr(nng_listener l, const char *opt, void *ptr); - -int nng_listener_setopt_size(nng_listener l, const char *opt, size_t z); - -int nng_listener_setopt_string(nng_listener l, const char *opt, const char *str); - -int nng_listener_setopt_uint64(nng_listener l, const char *opt, uint64_t u64); - ----- - -== DESCRIPTION - -IMPORTANT: These functions are deprecated. Please see xref:nng_listener_set.3.adoc[nng_listener_set]. -They may not be present if the library was built with `NNG_ELIDE_DEPRECATED`. - -(((options, listener))) -The `nng_listener_setopt()` functions are used to configure options for -the xref:nng_listener.5.adoc[listener] _l_. -The actual options that may be configured in this way -vary, and many are documented in xref:nng_options.5.adoc[nng_options(5)]. - -Additionally some transport-specific options -are documented with the transports themselves. - -NOTE: Once a listener has started, it is generally not possible to change -its configuration. - -=== Forms - -In all of these forms, the option _opt_ is configured on the listener _l_. - -The details of the type, size, and semantics of the option will depend -on the actual option, and will be documented with the option itself. - -TIP: It may be easier to use one of the typed forms of this function. - -`nng_listener_setopt()`:: -This function is untyped, and can be used to configure any arbitrary data. -The _val_ pointer addresses the data to copy, and _valsz_ is the -size of the objected located at _val_. - -`nng_listener_setopt_bool()`:: -This function is for options which take a Boolean (`bool`). -The _bval_ is passed to the option. - -`nng_listener_setopt_int()`:: -This function is for options which take an integer (`int`). -The _ival_ is passed to the option. - -`nng_listener_setopt_ms()`:: -This function is used to configure time durations (such as timeouts) using -type xref:nng_duration.5.adoc[`nng_duration`]. -The duration _dur_ is an integer number of milliseconds. - -`nng_listener_setopt_ptr()`:: -This function is used to pass a pointer, _ptr_, to structured data. -The data referenced by _ptr_ is generally managed by other functions. -For example, TLS configuration objects created with -(xref:nng_tls_config_alloc.3tls.adoc[`nng_tls_config_alloc()`]) -can be passed this way. - -NOTE: This form is somewhat special in that the object is generally -not copied, but instead the *pointer* to the object is copied. - -`nng_listener_setopt_size()`:: -This function is used to configure a size, _z_, typically for buffer sizes, -message maximum sizes, and similar options. - -`nng_listener_setopt_string()`:: -This function is used to pass configure a string, _str_. -Strings passed this way must be legal UTF-8 or ASCII strings, terminated -with a `NUL` (`\0`) byte. -(Other constraints may apply as well, see the documentation for each option -for details.) - -`nng_listener_setopt_uint64()`:: -This function is used to configure a 64-bit unsigned value, _u64_. -This is typically used for options related to identifiers, network numbers, -and similar. - -== RETURN VALUES - -These functions return 0 on success, and non-zero otherwise. - -== ERRORS - -[horizontal] -`NNG_EBADTYPE`:: Incorrect type for option. -`NNG_ECLOSED`:: Parameter _l_ does not refer to an open listener. -`NNG_EINVAL`:: The value being passed is invalid. -`NNG_ENOTSUP`:: The option _opt_ is not supported. -`NNG_EREADONLY`:: The option _opt_ is read-only. -`NNG_ESTATE`:: The listener _l_ is already started. - -== SEE ALSO - -[.text-left] -xref:nng_listen.3.adoc[nng_listen(3)], -xref:nng_listener_create.3.adoc[nng_listener_create(3)] -xref:nng_listener_getopt.3.adoc[nng_listener_getopt(3)] -xref:nng_setopt.3.adoc[nng_setopt(3)], -xref:nng_strerror.3.adoc[nng_strerror(3)], -xref:nng_duration.5.adoc[nng_duration(5)], -xref:nng_listener.5.adoc[nng_listener(5)], -xref:nng_options.5.adoc[nng_options(5)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_setopt.3.adoc b/docs/man/nng_setopt.3.adoc index 61926d69d..aa65a6381 100644 --- a/docs/man/nng_setopt.3.adoc +++ b/docs/man/nng_setopt.3.adoc @@ -119,7 +119,6 @@ These functions return 0 on success, and non-zero otherwise. [.text-left] xref:nng_getopt.3.adoc[nng_getopt(3)], -xref:nng_listener_setopt.3.adoc[nng_listener_setopt(3)], xref:nng_strerror.3.adoc[nng_strerror(3)], xref:nng_options.5.adoc[nng_options(5)], xref:nng_socket.5.adoc[nng_socket(5)], diff --git a/docs/man/nng_zerotier.7.adoc b/docs/man/nng_zerotier.7.adoc index 36cf7f0ec..40c048d6a 100644 --- a/docs/man/nng_zerotier.7.adoc +++ b/docs/man/nng_zerotier.7.adoc @@ -64,7 +64,7 @@ the node's own node number. Listeners may use port 0 to indicate that a suitable port number be selected automatically. Applications using this must determine the selected port number using the -xref:nng_listener_getopt.3.adoc[`nng_listener_getopt()`] function. +xref:nng_listener_get.3.adoc[`nng_listener_get()`] function. === Socket Address diff --git a/include/nng/nng.h b/include/nng/nng.h index 810041020..e109536f8 100644 --- a/include/nng/nng.h +++ b/include/nng/nng.h @@ -1450,42 +1450,6 @@ NNG_DECL int nng_ctx_setopt_ms( nng_ctx, const char *, nng_duration) NNG_DEPRECATED; NNG_DECL int nng_ctx_setopt_size(nng_ctx, const char *, size_t) NNG_DEPRECATED; -// Listener options. Use nng_listener_get and nng_listener_set instead. -NNG_DECL int nng_listener_getopt( - nng_listener, const char *, void *, size_t *) NNG_DEPRECATED; -NNG_DECL int nng_listener_getopt_bool( - nng_listener, const char *, bool *) NNG_DEPRECATED; -NNG_DECL int nng_listener_getopt_int( - nng_listener, const char *, int *) NNG_DEPRECATED; -NNG_DECL int nng_listener_getopt_ms( - nng_listener, const char *, nng_duration *) NNG_DEPRECATED; -NNG_DECL int nng_listener_getopt_size( - nng_listener, const char *, size_t *) NNG_DEPRECATED; -NNG_DECL int nng_listener_getopt_sockaddr( - nng_listener, const char *, nng_sockaddr *) NNG_DEPRECATED; -NNG_DECL int nng_listener_getopt_uint64( - nng_listener, const char *, uint64_t *) NNG_DEPRECATED; -NNG_DECL int nng_listener_getopt_ptr( - nng_listener, const char *, void **) NNG_DEPRECATED; -NNG_DECL int nng_listener_getopt_string( - nng_listener, const char *, char **) NNG_DEPRECATED; -NNG_DECL int nng_listener_setopt( - nng_listener, const char *, const void *, size_t) NNG_DEPRECATED; -NNG_DECL int nng_listener_setopt_bool( - nng_listener, const char *, bool) NNG_DEPRECATED; -NNG_DECL int nng_listener_setopt_int( - nng_listener, const char *, int) NNG_DEPRECATED; -NNG_DECL int nng_listener_setopt_ms( - nng_listener, const char *, nng_duration) NNG_DEPRECATED; -NNG_DECL int nng_listener_setopt_size( - nng_listener, const char *, size_t) NNG_DEPRECATED; -NNG_DECL int nng_listener_setopt_uint64( - nng_listener, const char *, uint64_t) NNG_DEPRECATED; -NNG_DECL int nng_listener_setopt_ptr( - nng_listener, const char *, void *) NNG_DEPRECATED; -NNG_DECL int nng_listener_setopt_string( - nng_listener, const char *, const char *) NNG_DEPRECATED; - #endif // NNG_ELIDE_DEPRECATED // nng_init_parameter is used by applications to change a tunable setting. diff --git a/src/nng_legacy.c b/src/nng_legacy.c index bb6cf2e5a..e2ddeebf1 100644 --- a/src/nng_legacy.c +++ b/src/nng_legacy.c @@ -172,109 +172,4 @@ nng_ctx_setopt_size(nng_ctx id, const char *n, size_t v) return (nng_ctx_set_size(id, n, v)); } -// Listeners. - -int -nng_listener_getopt(nng_listener id, const char *n, void *v, size_t *sz) -{ - return (nng_listener_get(id, n, v, sz)); -} - -int -nng_listener_getopt_int(nng_listener id, const char *n, int *v) -{ - return (nng_listener_get_int(id, n, v)); -} - -int -nng_listener_getopt_bool(nng_listener id, const char *n, bool *v) -{ - return (nng_listener_get_bool(id, n, v)); -} - -int -nng_listener_getopt_size(nng_listener id, const char *n, size_t *v) -{ - return (nng_listener_get_size(id, n, v)); -} - -int -nng_listener_getopt_uint64(nng_listener id, const char *n, uint64_t *v) -{ - return (nng_listener_get_uint64(id, n, v)); -} - -int -nng_listener_getopt_string(nng_listener id, const char *n, char **v) -{ - return (nng_listener_get_string(id, n, v)); -} - -int -nng_listener_getopt_ptr(nng_listener id, const char *n, void **v) -{ - return (nng_listener_get_ptr(id, n, v)); -} - -int -nng_listener_getopt_ms(nng_listener id, const char *n, nng_duration *v) -{ - return (nng_listener_get_ms(id, n, v)); -} - -int -nng_listener_getopt_sockaddr(nng_listener id, const char *n, nng_sockaddr *v) -{ - return (nng_listener_get_addr(id, n, v)); -} - -int -nng_listener_setopt( - nng_listener id, const char *name, const void *v, size_t sz) -{ - return (nng_listener_set(id, name, v, sz)); -} - -int -nng_listener_setopt_bool(nng_listener id, const char *n, bool v) -{ - return (nng_listener_set_bool(id, n, v)); -} - -int -nng_listener_setopt_int(nng_listener id, const char *n, int v) -{ - return (nng_listener_set_int(id, n, v)); -} - -int -nng_listener_setopt_ms(nng_listener id, const char *n, nng_duration v) -{ - return (nng_listener_set_ms(id, n, v)); -} - -int -nng_listener_setopt_size(nng_listener id, const char *n, size_t v) -{ - return (nng_listener_set_size(id, n, v)); -} - -int -nng_listener_setopt_uint64(nng_listener id, const char *n, uint64_t v) -{ - return (nng_listener_set_uint64(id, n, v)); -} - -int -nng_listener_setopt_ptr(nng_listener id, const char *n, void *v) -{ - return (nng_listener_set_ptr(id, n, v)); -} - -int -nng_listener_setopt_string(nng_listener id, const char *n, const char *v) -{ - return (nng_listener_set_string(id, n, v)); -} - #endif // NNG_ELIDE_DEPRECATED diff --git a/tests/zt.c b/tests/zt.c index b2aca7e72..c4e350b4e 100644 --- a/tests/zt.c +++ b/tests/zt.c @@ -13,8 +13,8 @@ #include #include "convey.h" -#include "trantest.h" #include "stubs.h" +#include "trantest.h" // zerotier tests. @@ -151,7 +151,7 @@ TestMain("ZeroTier Transport", { Convey("And it can be started...", { mkdir(path1, 0700); - So(nng_listener_setopt(l, NNG_OPT_ZT_HOME, path1, + So(nng_listener_set(l, NNG_OPT_ZT_HOME, path1, strlen(path1) + 1) == 0); So(nng_listener_start(l, 0) == 0); @@ -171,14 +171,14 @@ TestMain("ZeroTier Transport", { ids[0] = 0x622514484aull; ids[1] = 0x622514484aull; - So(nng_listener_setopt(l, NNG_OPT_ZT_ORBIT, - ids, sizeof(ids)) == 0); + So(nng_listener_set(l, NNG_OPT_ZT_ORBIT, ids, + sizeof(ids)) == 0); }); Convey("And we can deorbit anything", { uint64_t id; id = 0x12345678; - So(nng_listener_setopt(l, NNG_OPT_ZT_DEORBIT, - &id, sizeof(id)) == 0); + So(nng_listener_set(l, NNG_OPT_ZT_DEORBIT, &id, + sizeof(id)) == 0); }); }); }); @@ -218,16 +218,15 @@ TestMain("ZeroTier Transport", { So(nng_listener_create(&l, s, addr) == 0); - So(nng_listener_get_uint64(l, NNG_OPT_ZT_NODE, &node1) == - 0); + So(nng_listener_get_uint64(l, NNG_OPT_ZT_NODE, &node1) == 0); So(node1 != 0); Convey("Connection refused works", { snprintf(addr, sizeof(addr), "zt://%llx." NWID ":%u", (unsigned long long) node1, 42u); So(nng_dialer_create(&d, s, addr) == 0); - So(nng_dialer_get_uint64( - d, NNG_OPT_ZT_NODE, &node2) == 0); + So(nng_dialer_get_uint64(d, NNG_OPT_ZT_NODE, &node2) == + 0); So(node2 == node1); So(nng_dialer_start(d, 0) == NNG_ECONNREFUSED); }); @@ -257,7 +256,7 @@ TestMain("ZeroTier Transport", { }); So(nng_listener_create(&l, s1, addr1) == 0); - So(nng_listener_setopt( + So(nng_listener_set( l, NNG_OPT_ZT_HOME, path1, strlen(path1) + 1) == 0); So(nng_listener_start(l, 0) == 0); From 82f29399478d9942925fea77e852d56f76adee47 Mon Sep 17 00:00:00 2001 From: Garrett D'Amore Date: Sat, 7 Sep 2024 14:43:23 -0700 Subject: [PATCH 025/222] Remove deprecated context option functions. Signed-off-by: jaylin --- docs/man/CMakeLists.txt | 2 - docs/man/libnng.3.adoc | 20 +++-- docs/man/nng_ctx_getopt.3.adoc | 134 --------------------------------- docs/man/nng_ctx_open.3.adoc | 4 +- docs/man/nng_ctx_setopt.3.adoc | 114 ---------------------------- include/nng/nng.h | 17 ----- src/nng_legacy.c | 62 --------------- 7 files changed, 11 insertions(+), 342 deletions(-) delete mode 100644 docs/man/nng_ctx_getopt.3.adoc delete mode 100644 docs/man/nng_ctx_setopt.3.adoc diff --git a/docs/man/CMakeLists.txt b/docs/man/CMakeLists.txt index f1f9c42eb..02787a4f4 100644 --- a/docs/man/CMakeLists.txt +++ b/docs/man/CMakeLists.txt @@ -85,13 +85,11 @@ if (NNG_ENABLE_DOC) nng_close nng_ctx_close nng_ctx_get - nng_ctx_getopt nng_ctx_id nng_ctx_open nng_ctx_recv nng_ctx_send nng_ctx_set - nng_ctx_setopt nng_device nng_dial nng_dialer_close diff --git a/docs/man/libnng.3.adoc b/docs/man/libnng.3.adoc index b7190292c..848e049b3 100644 --- a/docs/man/libnng.3.adoc +++ b/docs/man/libnng.3.adoc @@ -211,17 +211,15 @@ This can allow multiple contexts to be created on a single socket for concurrent applications. |=== -|xref:nng_ctx_close.3.adoc[nng_ctx_close]|close context -|xref:nng_ctx_get.3.adoc[nng_ctx_get]|get context option -|xref:nng_ctx_getopt.3.adoc[nng_ctx_getopt]|get context option (DEPRECATED) -|xref:nng_ctx_id.3.adoc[nng_ctx_id]|get numeric context identifier -|xref:nng_ctx_open.3.adoc[nng_ctx_open]|create context -|xref:nng_ctx_recv.3.adoc[nng_ctx_recv]|receive message using context asynchronously -|xref:nng_ctx_recvmsg.3.adoc[nng_ctx_recvmsg]|receive a message using context -|xref:nng_ctx_send.3.adoc[nng_ctx_send]|send message using context asynchronously -|xref:nng_ctx_sendmsg.3.adoc[nng_ctx_sendmsg]|send a message using context -|xref:nng_ctx_set.3.adoc[nng_ctx_set]|set context option -|xref:nng_ctx_setopt.3.adoc[nng_ctx_setopt]|set context option (DEPRECATED) +|xref:nng_ctx_close.3.adoc[nng_ctx_close()]|close context +|xref:nng_ctx_get.3.adoc[nng_ctx_get()]|get context option +|xref:nng_ctx_id.3.adoc[nng_ctx_id()]|get numeric context identifier +|xref:nng_ctx_open.3.adoc[nng_ctx_open()]|create context +|xref:nng_ctx_recv.3.adoc[nng_ctx_recv()]|receive message using context asynchronously +|xref:nng_ctx_recvmsg.3.adoc[nng_ctx_recvmsg()]|receive a message using context +|xref:nng_ctx_send.3.adoc[nng_ctx_send()]|send message using context asynchronously +|xref:nng_ctx_sendmsg.3.adoc[nng_ctx_sendmsg()]|send a message using context +|xref:nng_ctx_set.3.adoc[nng_ctx_set()]|set context option |=== === Devices, Relays diff --git a/docs/man/nng_ctx_getopt.3.adoc b/docs/man/nng_ctx_getopt.3.adoc deleted file mode 100644 index 2214a3eb4..000000000 --- a/docs/man/nng_ctx_getopt.3.adoc +++ /dev/null @@ -1,134 +0,0 @@ -= nng_ctx_getopt(3) -// -// Copyright 2020 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_ctx_getopt - get context option - -== SYNOPSIS - -[source, c] ----- -#include - -int nng_ctx_getopt(nng_ctx ctx, const char *opt, void *val, size_t *valszp); - -int nng_ctx_getopt_bool(nng_ctx ctx, const char *opt, bool *bvalp); - -int nng_ctx_getopt_int(nng_ctx ctx, const char *opt, int *ivalp); - -int nng_ctx_getopt_ms(nng_ctx ctx, const char *opt, nng_duration *durp); - -int nng_ctx_getopt_size(nng_ctx ctx, const char *opt, size_t *zp); - -int nng_ctx_getopt_string(nng_ctx ctx, const char *opt, char **strp); - -int nng_ctx_getopt_uint64(nng_ctx ctx, const char *opt, uint64_t *u64p); - ----- - -== DESCRIPTION - -IMPORTANT: These functions are deprecated. Please see xref:nng_ctx_get.3.adoc[nng_ctx_get]. -They may not be present if the library was built with `NNG_ELIDE_DEPRECATED`. - -(((options, context))) -The `nng_ctx_getopt()` functions are used to retrieve option values for -the xref:nng_ctx.5.adoc[context] _ctx_. -The actual options that may be retrieved in this way vary. -A number of them are documented in xref:nng_options.5.adoc[nng_options(5)]. - -NOTE: Context options are protocol specific. -The details will be documented with the protocol. - -=== Forms - -In all of these forms, the option _opt_ is retrieved from the context _ctx_. -The forms vary based on the type of the option they take. - -The details of the type, size, and semantics of the option will depend -on the actual option, and will be documented with the option itself. - -`nng_ctx_getopt()`:: -This function is untyped and can be used to retrieve the value of any option. -The caller must store a pointer to a buffer to receive the value in _val_, -and the size of the buffer shall be stored at the location referenced by -_valszp_. + - + -When the function returns, the actual size of the data copied (or that -would have been copied if sufficient space were present) is stored at -the location referenced by _valszp_. -If the caller's buffer is not large enough to hold the entire object, -then the copy is truncated. -Therefore the caller should check for truncation by verifying that the -returned size in _valszp_ does not exceed the original buffer size. + - + -It is acceptable to pass `NULL` for _val_ if the value in _valszp_ is zero. -This can be used to determine the size of the buffer needed to receive -the object. - -TIP: It may be easier to use one of the typed forms of this function. - -`nng_ctx_getopt_bool()`:: -This function is for options which take a Boolean (`bool`). -The value will be stored at _ivalp_. - -`nng_ctx_getopt_int()`:: -This function is for options which take an integer (`int`). -The value will be stored at _ivalp_. - -`nng_ctx_getopt_ms()`:: -This function is used to retrieve time xref:nng_duration.5.adoc[durations] -(such as timeouts), stored in _durp_ as a number of milliseconds. -(The special value ((`NNG_DURATION_INFINITE`)) means an infinite amount of time, and -the special value ((`NNG_DURATION_DEFAULT`)) means a context-specific default.) - -`nng_ctx_getopt_size()`:: -This function is used to retrieve a size into the pointer _zp_, -typically for buffer sizes, message maximum sizes, and similar options. - -`nng_ctx_getopt_string()`:: -This function is used to retrieve a string into _strp_. -This string is created from the source using xref:nng_strdup.3.adoc[`nng_strdup()`] -and consequently must be freed by the caller using -xref:nng_strfree.3.adoc[`nng_strfree()`] when it is no longer needed. - -`nng_ctx_getopt_uint64()`:: -This function is used to retrieve a 64-bit unsigned value into the value -referenced by _u64p_. -This is typically used for options related to identifiers, network -numbers, and similar. - -== RETURN VALUES - -These functions return 0 on success, and non-zero otherwise. - -== ERRORS - -[horizontal] -`NNG_EBADTYPE`:: Incorrect type for option. -`NNG_ECLOSED`:: Parameter _s_ does not refer to an open socket. -`NNG_EINVAL`:: Size of destination _val_ too small for object. -`NNG_ENOMEM`:: Insufficient memory exists. -`NNG_ENOTSUP`:: The option _opt_ is not supported. -`NNG_EWRITEONLY`:: The option _opt_ is write-only. - -== SEE ALSO - -[.text-left] -xref:nng_ctx_setopt.3.adoc[nng_ctx_setopt(3)], -xref:nng_strdup.3.adoc[nng_strdup(3)], -xref:nng_strerror.3.adoc[nng_strerror(3)], -xref:nng_strfree.3.adoc[nng_strfree(3)], -xref:nng_duration.5.adoc[nng_duration(5)], -xref:nng_ctx.5.adoc[nng_ctx(5)], -xref:nng_options.5.adoc[nng_options(5)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_ctx_open.3.adoc b/docs/man/nng_ctx_open.3.adoc index 76842b7e0..8157c6eee 100644 --- a/docs/man/nng_ctx_open.3.adoc +++ b/docs/man/nng_ctx_open.3.adoc @@ -59,10 +59,10 @@ This function returns 0 on success, and non-zero otherwise. [.text-left] xref:nng_ctx_close.3.adoc[nng_ctx_close(3)], -xref:nng_ctx_getopt.3.adoc[nng_ctx_getopt(3)], +xref:nng_ctx_get.3.adoc[nng_ctx_get(3)], xref:nng_ctx_recv.3.adoc[nng_ctx_recv(3)], xref:nng_ctx_send.3.adoc[nng_ctx_send(3)], -xref:nng_ctx_setopt.3.adoc[nng_ctx_setopt(3)], +xref:nng_ctx_set.3.adoc[nng_ctx_set(3)], xref:nng_strerror.3.adoc[nng_strerror(3)], xref:nng_ctx.5.adoc[nng_ctx(5)], xref:nng_socket.5.adoc[nng_socket(5)], diff --git a/docs/man/nng_ctx_setopt.3.adoc b/docs/man/nng_ctx_setopt.3.adoc deleted file mode 100644 index f6f7f9efa..000000000 --- a/docs/man/nng_ctx_setopt.3.adoc +++ /dev/null @@ -1,114 +0,0 @@ -= nng_ctx_setopt(3) -// -// Copyright 2020 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_ctx_setopt - set context option - -== SYNOPSIS - -[source, c] ----- -#include - -int nng_ctx_setopt(nng_ctx ctx, const char *opt, const void *val, size_t valsz); - -int nng_ctx_setopt_bool(nng_ctx ctx, const char *opt, int bval); - -int nng_ctx_setopt_int(nng_ctx ctx, const char *opt, int ival); - -int nng_ctx_setopt_ms(nng_ctx ctx, const char *opt, nng_duration dur); - -int nng_ctx_setopt_size(nng_ctx ctx, const char *opt, size_t z); - -int nng_ctx_setopt_string(nng_ctx ctx, const char *opt, const char *str); - -int nng_ctx_setopt_uint64(nng_ctx ctx, const char *opt, uint64_t u64); ----- - -== DESCRIPTION - -IMPORTANT: These functions are deprecated. Please see xref:nng_ctx_set.3.adoc[nng_ctx_set]. -They may not be present if the library was built with `NNG_ELIDE_DEPRECATED`. - -(((options, context))) -The `nng_ctx_setopt()` functions are used to configure options for -the context _ctx_. -The actual options that may be configured in this way vary, and are -specified by _opt_. - -NOTE: Context options are protocol specific. -The details will be documented with the protocol. - -=== Forms - -The details of the type, size, and semantics of the option will depend -on the actual option, and will be documented with the option itself. - -`nng_ctx_setopt()`:: -This function is untyped, and can be used to configure any arbitrary data. -The _val_ pointer addresses the data to copy, and _valsz_ is the -size of the objected located at _val_. - -TIP: It may be easier to use one of the typed forms of this function. - -`nng_ctx_setopt_bool()`:: -This function is for options which take a Boolean (`bool`). -The _bval_ is passed to the option. - -`nng_ctx_setopt_int()`:: -This function is for options which take an integer (`int`). -The _ival_ is passed to the option. - -`nng_ctx_setopt_ms()`:: -This function is used to configure time durations (such as timeouts) using -type xref:nng_duration.5.adoc[`nng_duration`]. -The duration _dur_ is an integer number of milliseconds. - -`nng_ctx_setopt_size()`:: -This function is used to configure a size, _z_, typically for buffer sizes, -message maximum sizes, and similar options. - -`nng_ctx_setopt_string()`:: -This function is used to pass configure a string, _str_. -Strings passed this way must be legal UTF-8 or ASCII strings, terminated -with a `NUL` (`\0`) byte. -(Other constraints may apply as well, see the documentation for each option -for details.) - -`nng_ctx_setopt_uint64()`:: -This function is used to configure a 64-bit unsigned value, _u64_. -This is typically used for options related to identifiers, network numbers, -and similar. - -== RETURN VALUES - -These functions return 0 on success, and non-zero otherwise. - -== ERRORS - -[horizontal] -`NNG_ECLOSED`:: Parameter _s_ does not refer to an open socket. -`NNG_EINVAL`:: The value being passed is invalid. -`NNG_ENOTSUP`:: The option _opt_ is not supported. -`NNG_EREADONLY`:: The option _opt_ is read-only. -`NNG_ESTATE`:: The socket is in an inappropriate state for setting this option. - -== SEE ALSO - -[.text-left] -xref:nng_ctx_getopt.3.adoc[nng_ctx_getopt(3)], -xref:nng_setopt.3.adoc[nng_setopt(3)], -xref:nng_strerror.3.adoc[nng_strerror(3)], -xref:nng_ctx.5.adoc[nng_ctx(5)], -xref:nng_options.5.adoc[nng_options(5)], -xref:nng_socket.5.adoc[nng_socket(5)], -xref:nng.7.adoc[nng(7)] diff --git a/include/nng/nng.h b/include/nng/nng.h index e109536f8..ca8a6b145 100644 --- a/include/nng/nng.h +++ b/include/nng/nng.h @@ -1433,23 +1433,6 @@ NNG_DECL int nng_setopt_string( nng_socket, const char *, const char *) NNG_DEPRECATED; NNG_DECL int nng_setopt_ptr(nng_socket, const char *, void *) NNG_DEPRECATED; -// Context options. Use nng_ctx_get and nng_ctx_set instead. -NNG_DECL int nng_ctx_getopt( - nng_ctx, const char *, void *, size_t *) NNG_DEPRECATED; -NNG_DECL int nng_ctx_getopt_bool(nng_ctx, const char *, bool *) NNG_DEPRECATED; -NNG_DECL int nng_ctx_getopt_int(nng_ctx, const char *, int *) NNG_DEPRECATED; -NNG_DECL int nng_ctx_getopt_ms( - nng_ctx, const char *, nng_duration *) NNG_DEPRECATED; -NNG_DECL int nng_ctx_getopt_size( - nng_ctx, const char *, size_t *) NNG_DEPRECATED; -NNG_DECL int nng_ctx_setopt( - nng_ctx, const char *, const void *, size_t) NNG_DEPRECATED; -NNG_DECL int nng_ctx_setopt_bool(nng_ctx, const char *, bool) NNG_DEPRECATED; -NNG_DECL int nng_ctx_setopt_int(nng_ctx, const char *, int) NNG_DEPRECATED; -NNG_DECL int nng_ctx_setopt_ms( - nng_ctx, const char *, nng_duration) NNG_DEPRECATED; -NNG_DECL int nng_ctx_setopt_size(nng_ctx, const char *, size_t) NNG_DEPRECATED; - #endif // NNG_ELIDE_DEPRECATED // nng_init_parameter is used by applications to change a tunable setting. diff --git a/src/nng_legacy.c b/src/nng_legacy.c index e2ddeebf1..833c35d59 100644 --- a/src/nng_legacy.c +++ b/src/nng_legacy.c @@ -110,66 +110,4 @@ nng_setopt_ptr(nng_socket id, const char *n, void *v) return (nng_socket_set_ptr(id, n, v)); } -// Contexts. - -int -nng_ctx_getopt(nng_ctx id, const char *n, void *v, size_t *sz) -{ - return (nng_ctx_get(id, n, v, sz)); -} - -int -nng_ctx_getopt_int(nng_ctx id, const char *n, int *v) -{ - return (nng_ctx_get_int(id, n, v)); -} - -int -nng_ctx_getopt_bool(nng_ctx id, const char *n, bool *v) -{ - return (nng_ctx_get_bool(id, n, v)); -} - -int -nng_ctx_getopt_size(nng_ctx id, const char *n, size_t *v) -{ - return (nng_ctx_get_size(id, n, v)); -} - -int -nng_ctx_getopt_ms(nng_ctx id, const char *n, nng_duration *v) -{ - return (nng_ctx_get_ms(id, n, v)); -} - -int -nng_ctx_setopt(nng_ctx id, const char *name, const void *v, size_t sz) -{ - return (nng_ctx_set(id, name, v, sz)); -} - -int -nng_ctx_setopt_bool(nng_ctx id, const char *n, bool v) -{ - return (nng_ctx_set_bool(id, n, v)); -} - -int -nng_ctx_setopt_int(nng_ctx id, const char *n, int v) -{ - return (nng_ctx_set_int(id, n, v)); -} - -int -nng_ctx_setopt_ms(nng_ctx id, const char *n, nng_duration v) -{ - return (nng_ctx_set_ms(id, n, v)); -} - -int -nng_ctx_setopt_size(nng_ctx id, const char *n, size_t v) -{ - return (nng_ctx_set_size(id, n, v)); -} - #endif // NNG_ELIDE_DEPRECATED From d2d15adc9018a50b61cd2a60d7197dc817055c4a Mon Sep 17 00:00:00 2001 From: Garrett D'Amore Date: Sat, 7 Sep 2024 14:56:23 -0700 Subject: [PATCH 026/222] Remove the last of the legacy option handling functions. Signed-off-by: jaylin --- docs/man/CMakeLists.txt | 3 +- docs/man/libnng.3.adoc | 23 ++---- docs/man/nng_getopt.3.adoc | 142 -------------------------------- docs/man/nng_pipe_notify.3.adoc | 2 +- docs/man/nng_setopt.3.adoc | 125 ---------------------------- docs/man/nng_socket.5.adoc | 4 +- docs/man/nng_sub.7.adoc | 4 +- docs/man/nng_tcp_options.5.adoc | 6 -- include/nng/nng.h | 33 -------- src/nng_legacy.c | 100 ---------------------- 10 files changed, 15 insertions(+), 427 deletions(-) delete mode 100644 docs/man/nng_getopt.3.adoc delete mode 100644 docs/man/nng_setopt.3.adoc diff --git a/docs/man/CMakeLists.txt b/docs/man/CMakeLists.txt index 02787a4f4..225a65bab 100644 --- a/docs/man/CMakeLists.txt +++ b/docs/man/CMakeLists.txt @@ -99,7 +99,6 @@ if (NNG_ENABLE_DOC) nng_dialer_set nng_dialer_start nng_free - nng_getopt nng_listen nng_listener_close nng_listener_create @@ -147,7 +146,7 @@ if (NNG_ENABLE_DOC) nng_send nng_send_aio nng_sendmsg - nng_setopt + nng_set nng_sleep_aio nng_socket_id nng_socket_get diff --git a/docs/man/libnng.3.adoc b/docs/man/libnng.3.adoc index 848e049b3..9b078329b 100644 --- a/docs/man/libnng.3.adoc +++ b/docs/man/libnng.3.adoc @@ -44,20 +44,15 @@ The following common functions exist in _libnng_. The following functions operate on sockets. |=== -|xref:nng_close.3.adoc[nng_close]|close socket -|xref:nng_dial.3.adoc[nng_dial]|create and start dialer -|xref:nng_getopt.3.adoc[nng_getopt]|get socket option -|xref:nng_listen.3.adoc[nng_listen]|create and start listener -|xref:nng_recv.3.adoc[nng_recv]|receive data -|xref:nng_send.3.adoc[nng_send]|send data -|xref:nng_setopt.3.adoc[nng_setopt]|set socket option (DEPRECATED) -|xref:nng_socket_get.3.adoc[nng_socket_get]|get socket option -|xref:nng_socket_id.3.adoc[nng_socket_id]|get numeric socket identifier -|xref:nng_socket_raw.3.adoc[nng_socket_raw]|is the socket raw -|xref:nng_socket_proto_id.3.adoc[nng_socket_proto_id]|get the socket protocol identifier -|xref:nng_socket_proto_name.3.adoc[nng_socket_proto_name]|get the socket protocol name -|xref:nng_socket_set.3.adoc[nng_socket_set]|set socket option -|xref:nng_sub_susbcribe.3.adoc[nng_sub_subscribe]|manage subscriptions +|xref:nng_close.3.adoc[nng_close()]|close socket +|xref:nng_dial.3.adoc[nng_dial()]|create and start dialer +|xref:nng_get.3.adoc[nng_get()]|get socket option +|xref:nng_listen.3.adoc[nng_listen()]|create and start listener +|xref:nng_recv.3.adoc[nng_recv()]|receive data +|xref:nng_send.3.adoc[nng_send()]|send data +|xref:nng_socket_get.3.adoc[nng_socket_get()]|get socket option +|xref:nng_socket_id.3.adoc[nng_socket_id()]|get numeric socket identifier +|xref:nng_socket_set.3.adoc[nng_socket_set()]|set socket option |=== === Connection Management diff --git a/docs/man/nng_getopt.3.adoc b/docs/man/nng_getopt.3.adoc deleted file mode 100644 index 9b61fc5f6..000000000 --- a/docs/man/nng_getopt.3.adoc +++ /dev/null @@ -1,142 +0,0 @@ -= nng_getopt(3) -// -// Copyright 2020 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_getopt - get socket option - -== SYNOPSIS - -[source, c] ----- -#include - -int nng_getopt(nng_socket s, const char *opt, void *val, size_t *valszp); - -int nng_getopt_bool(nng_socket s, const char *opt, bool *bvalp); - -int nng_getopt_int(nng_socket s, const char *opt, int *ivalp); - -int nng_getopt_ms(nng_socket s, const char *opt, nng_duration *durp); - -int nng_getopt_ptr(nng_socket s, const char *opt, void **ptr); - -int nng_getopt_size(nng_socket s, const char *opt, size_t *zp); - -int nng_getopt_string(nng_socket s, const char *opt, char **strp); - -int nng_getopt_uint64(nng_socket s, const char *opt, uint64_t *u64p); - ----- - -== DESCRIPTION - -IMPORTANT: These functions are deprecated. Please see xref:nng_socket_get.3.adoc[nng_socket_get]. -They may not be present if the library was built with `NNG_ELIDE_DEPRECATED`. - -(((options, socket))) -The `nng_getopt()` functions are used to retrieve option values for -the xref:nng_socket.5.adoc[socket] _s_. -The actual options that may be retrieved in this way vary. -A number of them are documented in xref:nng_options.5.adoc[nng_options(5)]. - -Additionally transport-specific options and protocol-specific options are -documented with the transports and protocols themselves. - -=== Forms - -In all of these forms, the option _opt_ is retrieved from the socket _s_. -The forms vary based on the type of the option they take. - -The details of the type, size, and semantics of the option will depend -on the actual option, and will be documented with the option itself. - -`nng_getopt()`:: -This function is untyped and can be used to retrieve the value of any option. -The caller must store a pointer to a buffer to receive the value in _val_, -and the size of the buffer shall be stored at the location referenced by -_valszp_. -+ -When the function returns, the actual size of the data copied (or that -would have been copied if sufficient space were present) is stored at -the location referenced by _valszp_. -If the caller's buffer is not large enough to hold the entire object, -then the copy is truncated. -Therefore the caller should check for truncation by verifying that the -returned size in _valszp_ does not exceed the original buffer size. -+ -It is acceptable to pass `NULL` for _val_ if the value in _valszp_ is zero. -This can be used to determine the size of the buffer needed to receive -the object. -+ -TIP: It may be easier to use one of the typed forms of this function. - -`nng_getopt_bool()`:: -This function is for options which take a Boolean (`bool`). -The value will be stored at _bvalp_. - -`nng_getopt_int()`:: -This function is for options which take an integer (`int`). -The value will be stored at _ivalp_. - -`nng_getopt_ms()`:: -This function is used to retrieve time xref:nng_duration.5.adoc[durations] -(such as timeouts), stored in _durp_ as a number of milliseconds. -(The special value ((`NNG_DURATION_INFINITE`)) means an infinite amount of time, and -the special value ((`NNG_DURATION_DEFAULT`)) means a context-specific default.) - -`nng_getopt_ptr()`:: -This function is used to retrieve a pointer, _ptr_, to structured data. -The data referenced by _ptr_ is generally managed using other functions. -Note that this form is somewhat special in that the object is generally -not copied, but instead the *pointer* to the object is copied. - -`nng_getopt_size()`:: -This function is used to retrieve a size into the pointer _zp_, -typically for buffer sizes, message maximum sizes, and similar options. - -`nng_getopt_string()`:: -This function is used to retrieve a string into _strp_. -This string is created from the source using xref:nng_strdup.3.adoc[`nng_strdup()`] -and consequently must be freed by the caller using -xref:nng_strfree.3.adoc[`nng_strfree()`] when it is no longer needed. - -`nng_getopt_uint64()`:: -This function is used to retrieve a 64-bit unsigned value into the value -referenced by _u64p_. -This is typically used for options related to identifiers, network -numbers, and similar. - -== RETURN VALUES - -These functions return 0 on success, and non-zero otherwise. - -== ERRORS - -[horizontal] -`NNG_EBADTYPE`:: Incorrect type for option. -`NNG_ECLOSED`:: Parameter _s_ does not refer to an open socket. -`NNG_EINVAL`:: Size of destination _val_ too small for object. -`NNG_ENOMEM`:: Insufficient memory exists. -`NNG_ENOTSUP`:: The option _opt_ is not supported. -`NNG_EWRITEONLY`:: The option _opt_ is write-only. - -== SEE ALSO - -[.text-left] -xref:nng_setopt.3.adoc[nng_setopt(3)], -xref:nng_strdup.3.adoc[nng_strdup(3)], -xref:nng_strerror.3.adoc[nng_strerror(3)], -xref:nng_strfree.3.adoc[nng_strfree(3)], -xref:nng_duration.5.adoc[nng_duration(5)], -xref:nng_options.5.adoc[nng_options(5)], -xref:nng_socket.5.adoc[nng_socket(5)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_pipe_notify.3.adoc b/docs/man/nng_pipe_notify.3.adoc index e351129ea..cd7250f7f 100644 --- a/docs/man/nng_pipe_notify.3.adoc +++ b/docs/man/nng_pipe_notify.3.adoc @@ -87,7 +87,7 @@ This function returns 0 on success, and non-zero otherwise. [.text-left] xref:nng_pipe_close.3.adoc[nng_pipe_close(3)], -xref:nng_pipe_getopt.3.adoc[nng_pipe_getopt(3)], +xref:nng_pipe_get.3.adoc[nng_pipe_get(3)], xref:nng_pipe.5.adoc[nng_pipe(5)], xref:nng_socket.5.adoc[nng_socket(5)], xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_setopt.3.adoc b/docs/man/nng_setopt.3.adoc deleted file mode 100644 index aa65a6381..000000000 --- a/docs/man/nng_setopt.3.adoc +++ /dev/null @@ -1,125 +0,0 @@ -= nng_setopt(3) - -// Copyright 2020 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. - -== NAME - -nng_setopt - set socket option - -== SYNOPSIS - -[source, c] ----- -#include - -int nng_setopt(nng_socket s, const char *opt, const void *val, size_t valsz); - -int nng_setopt_bool(nng_socket s, const char *opt, bool bval); - -int nng_setopt_int(nng_socket s, const char *opt, int ival); - -int nng_setopt_ms(nng_socket s, const char *opt, nng_duration dur); - -int nng_setopt_ptr(nng_socket s, const char *opt, void *ptr); - -int nng_setopt_size(nng_socket s, const char *opt, size_t z); - -int nng_setopt_string(nng_socket s, const char *opt, const char *str); - -int nng_setopt_uint64(nng_socket s, const char *opt, uint64_t u64); - ----- - -== DESCRIPTION - -IMPORTANT: These functions are deprecated. Please see xref:nng_socket_set.3.adoc[nng_socket_set]. -They may not be present if the library was built with `NNG_ELIDE_DEPRECATED`. - -(((options, socket))) -The `nng_setopt()` functions are used to configure options for -the socket _s_. -The actual options that may be configured in this way vary, and are -specified by _opt_. -A number of them are documented in xref:nng_options.5.adoc[nng_options(5)]. - -Additionally some transport-specific and protocol-specific options are -documented with the transports and protocols themselves. - -=== Forms - -The details of the type, size, and semantics of the option will depend -on the actual option, and will be documented with the option itself. - -`nng_setopt()`:: -This function is untyped, and can be used to configure any arbitrary data. -The _val_ pointer addresses the data to copy, and _valsz_ is the -size of the objected located at _val_. - -TIP: It may be easier to use one of the typed forms of this function. - -`nng_setopt_bool()`:: -This function is for options which take a Boolean (`bool`). -The _bval_ is passed to the option. - -`nng_setopt_int()`:: -This function is for options which take an integer (`int`). -The _ival_ is passed to the option. - -`nng_setopt_ms()`:: -This function is used to configure time durations (such as timeouts) using -type xref:nng_duration.5.adoc[`nng_duration`]. -The duration _dur_ is an integer number of milliseconds. - -`nng_setopt_ptr()`:: -This function is used to pass a pointer, _ptr_, to structured data. -The data referenced by _ptr_ is generally managed by other functions. -For example, TLS configuration objects created with -(xref:nng_tls_config_alloc.3tls.adoc[`nng_tls_config_alloc()`]) -can be passed this way. - -NOTE: This form is somewhat special in that the object is generally -not copied, but instead the *pointer* to the object is copied. - -`nng_setopt_size()`:: -This function is used to configure a size, _z_, typically for buffer sizes, -message maximum sizes, and similar options. - -`nng_setopt_string()`:: -This function is used to pass configure a string, _str_. -Strings passed this way must be legal UTF-8 or ASCII strings, terminated -with a `NUL` (`\0`) byte. -(Other constraints may apply as well, see the documentation for each option -for details.) - -`nng_setopt_uint64()`:: -This function is used to configure a 64-bit unsigned value, _u64_. -This is typically used for options related to identifiers, network numbers, -and similar. - -== RETURN VALUES - -These functions return 0 on success, and non-zero otherwise. - -== ERRORS - -[horizontal] -`NNG_ECLOSED`:: Parameter _s_ does not refer to an open socket. -`NNG_EINVAL`:: The value being passed is invalid. -`NNG_ENOTSUP`:: The option _opt_ is not supported. -`NNG_EREADONLY`:: The option _opt_ is read-only. -`NNG_ESTATE`:: The socket is in an inappropriate state for setting this option. - -== SEE ALSO - -[.text-left] -xref:nng_getopt.3.adoc[nng_getopt(3)], -xref:nng_strerror.3.adoc[nng_strerror(3)], -xref:nng_options.5.adoc[nng_options(5)], -xref:nng_socket.5.adoc[nng_socket(5)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_socket.5.adoc b/docs/man/nng_socket.5.adoc index 5c5657203..c80a4dcd2 100644 --- a/docs/man/nng_socket.5.adoc +++ b/docs/man/nng_socket.5.adoc @@ -62,9 +62,9 @@ nng_socket s = NNG_SOCKET_INITIALIZER; [.text-left] xref:libnng.3.adoc[libnng(3)], xref:nng_close.3.adoc[nng_close(3)], -xref:nng_getopt.3.adoc[nng_getopt(3)], -xref:nng_setopt.3.adoc[nng_setopt(3)], +xref:nng_socket_get.3.adoc[nng_socket_get(3)], xref:nng_socket_id.3.adoc[nng_socket_id(3)], +xref:nng_socket_set.3.adoc[nng_socket_set(3)], xref:nng_dialer.5.adoc[nng_dialer(5)], xref:nng_listener.5.adoc[nng_listener(5)], xref:nng_options.5.adoc[nng_options(5)], diff --git a/docs/man/nng_sub.7.adoc b/docs/man/nng_sub.7.adoc index 95d7066e9..8b3a216ad 100644 --- a/docs/man/nng_sub.7.adoc +++ b/docs/man/nng_sub.7.adoc @@ -70,10 +70,10 @@ xref:nng_sub_subscribe.3.adoc[`nng_sub0_socket_subscribe`] or `nng_sub0_ctx_subs functions. + NOTE: This option is a byte array. Thus if you use -xref:nng_setopt.3.adoc[`nng_setopt_string()`] the `NUL` terminator byte will +xref:nng_socket_set.3.adoc[`nng_socket_set_string()`] the `NUL` terminator byte will be included in the topic. If that isn't desired, consider using -xref:nng_setopt.3.adoc[`nng_setopt()`] and using `strlen()` of the topic +xref:nng_socket_set.3.adoc[`nng_socket_set()`] and using `strlen()` of the topic as the topic size. + TIP: To receive all messages, an empty topic (zero length) can be used. diff --git a/docs/man/nng_tcp_options.5.adoc b/docs/man/nng_tcp_options.5.adoc index b8629fe57..ad5fabfdd 100644 --- a/docs/man/nng_tcp_options.5.adoc +++ b/docs/man/nng_tcp_options.5.adoc @@ -112,11 +112,5 @@ when appropriate for the context: == SEE ALSO [.text-left] -xref:nng_tcp_dialer_getopt.3tcp.adoc[nng_tcp_dialer_getopt(3tcp)], -xref:nng_tcp_dialer_setopt.3tcp.adoc[nng_tcp_dialer_setopt(3tcp)], -xref:nng_tcp_getopt.3tcp.adoc[nng_tcp_getopt(3tcp)], -xref:nng_tcp_listener_getopt.3tcp.adoc[nng_tcp_listener_getopt(3tcp)], -xref:nng_tcp_listener_setopt.3tcp.adoc[nng_tcp_listener_setopt(3tcp)], -xref:nng_tcp_setopt.3tcp.adoc[nng_tcp_setopt(3tcp)], xref:nng_options.5.adoc[nng_options(5)] xref:nng.7.adoc[nng(7)] diff --git a/include/nng/nng.h b/include/nng/nng.h index ca8a6b145..1537ed4e3 100644 --- a/include/nng/nng.h +++ b/include/nng/nng.h @@ -1402,39 +1402,6 @@ NNG_DECL void nng_udp_recv(nng_udp *udp, nng_aio *aio); NNG_DECL int nng_udp_multicast_membership( nng_udp *udp, nng_sockaddr *sa, bool join); -#ifndef NNG_ELIDE_DEPRECATED -// These are legacy APIs that have been deprecated. -// Their use is strongly discouraged. - -// Socket options. Use nng_socket_get and nng_socket_set instead. -NNG_DECL int nng_getopt( - nng_socket, const char *, void *, size_t *) NNG_DEPRECATED; -NNG_DECL int nng_getopt_bool(nng_socket, const char *, bool *) NNG_DEPRECATED; -NNG_DECL int nng_getopt_int(nng_socket, const char *, int *) NNG_DEPRECATED; -NNG_DECL int nng_getopt_ms( - nng_socket, const char *, nng_duration *) NNG_DEPRECATED; -NNG_DECL int nng_getopt_size( - nng_socket, const char *, size_t *) NNG_DEPRECATED; -NNG_DECL int nng_getopt_uint64( - nng_socket, const char *, uint64_t *) NNG_DEPRECATED; -NNG_DECL int nng_getopt_ptr(nng_socket, const char *, void **) NNG_DEPRECATED; -NNG_DECL int nng_getopt_string( - nng_socket, const char *, char **) NNG_DEPRECATED; -NNG_DECL int nng_setopt( - nng_socket, const char *, const void *, size_t) NNG_DEPRECATED; -NNG_DECL int nng_setopt_bool(nng_socket, const char *, bool) NNG_DEPRECATED; -NNG_DECL int nng_setopt_int(nng_socket, const char *, int) NNG_DEPRECATED; -NNG_DECL int nng_setopt_ms( - nng_socket, const char *, nng_duration) NNG_DEPRECATED; -NNG_DECL int nng_setopt_size(nng_socket, const char *, size_t) NNG_DEPRECATED; -NNG_DECL int nng_setopt_uint64( - nng_socket, const char *, uint64_t) NNG_DEPRECATED; -NNG_DECL int nng_setopt_string( - nng_socket, const char *, const char *) NNG_DEPRECATED; -NNG_DECL int nng_setopt_ptr(nng_socket, const char *, void *) NNG_DEPRECATED; - -#endif // NNG_ELIDE_DEPRECATED - // nng_init_parameter is used by applications to change a tunable setting. // This function must be called before any other NNG function for the setting // to have any effect. This function is also not thread-safe! diff --git a/src/nng_legacy.c b/src/nng_legacy.c index 833c35d59..83a5f668e 100644 --- a/src/nng_legacy.c +++ b/src/nng_legacy.c @@ -10,104 +10,4 @@ #ifndef NNG_ELIDE_DEPRECATED #include "core/nng_impl.h" -// These are legacy APIs that we would prefer nobody used. -// Eventually they will likely be removed. For now we have -// to continue to provide them for compatibility. - -int -nng_getopt(nng_socket id, const char *n, void *v, size_t *sz) -{ - return (nng_socket_get(id, n, v, sz)); -} - -int -nng_getopt_int(nng_socket id, const char *n, int *v) -{ - return (nng_socket_get_int(id, n, v)); -} - -int -nng_getopt_uint64(nng_socket id, const char *n, uint64_t *v) -{ - return (nng_socket_get_uint64(id, n, v)); -} - -int -nng_getopt_bool(nng_socket id, const char *n, bool *v) -{ - return (nng_socket_get_bool(id, n, v)); -} - -int -nng_getopt_size(nng_socket id, const char *n, size_t *v) -{ - return (nng_socket_get_size(id, n, v)); -} - -int -nng_getopt_ms(nng_socket id, const char *n, nng_duration *v) -{ - return (nng_socket_get_ms(id, n, v)); -} - -int -nng_getopt_ptr(nng_socket id, const char *n, void **v) -{ - return (nng_socket_get_ptr(id, n, v)); -} - -int -nng_getopt_string(nng_socket id, const char *n, char **v) -{ - return (nng_socket_get_string(id, n, v)); -} - -int -nng_setopt(nng_socket id, const char *name, const void *v, size_t sz) -{ - return (nng_socket_set(id, name, v, sz)); -} - -int -nng_setopt_bool(nng_socket id, const char *n, bool v) -{ - return (nng_socket_set_bool(id, n, v)); -} - -int -nng_setopt_int(nng_socket id, const char *n, int v) -{ - return (nng_socket_set_int(id, n, v)); -} - -int -nng_setopt_ms(nng_socket id, const char *n, nng_duration v) -{ - return (nng_socket_set_ms(id, n, v)); -} - -int -nng_setopt_size(nng_socket id, const char *n, size_t v) -{ - return (nng_socket_set_size(id, n, v)); -} - -int -nng_setopt_uint64(nng_socket id, const char *n, uint64_t v) -{ - return (nng_socket_set_uint64(id, n, v)); -} - -int -nng_setopt_string(nng_socket id, const char *n, const char *v) -{ - return (nng_socket_set_string(id, n, v)); -} - -int -nng_setopt_ptr(nng_socket id, const char *n, void *v) -{ - return (nng_socket_set_ptr(id, n, v)); -} - #endif // NNG_ELIDE_DEPRECATED From 339e1b04db438cd0a9f42fa5aca09d663e290111 Mon Sep 17 00:00:00 2001 From: Garrett D'Amore Date: Sun, 6 Oct 2024 14:36:10 -0700 Subject: [PATCH 027/222] fixup README stuff --- README.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 9cd637677..dfd6c2677 100644 --- a/README.md +++ b/README.md @@ -3,13 +3,13 @@ This is NNG repo of NanoMQ project. I have updated it to support MQTT protocol. # nng - nanomsg-next-gen [![Stand With Ukraine](https://raw.githubusercontent.com/vshymanskyy/StandWithUkraine/main/badges/StandWithUkraine.svg)](https://stand-with-ukraine.pp.ua) -[![Linux Status](https://img.shields.io/github/actions/workflow/status/nanomsg/nng/linux.yml?branch=dev2.0&logoColor=grey&logo=ubuntu&label=)](https://github.com/nanomsg/nng/actions) -[![Windows Status](https://img.shields.io/github/actions/workflow/status/nanomsg/nng/windows.yml?branch=dev2.0&logoColor=grey&logo=data:image/svg%2bxml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCA0ODc1IDQ4NzUiPjxwYXRoIGZpbGw9ImdyZXkiIGQ9Ik0wIDBoMjMxMXYyMzEwSDB6bTI1NjQgMGgyMzExdjIzMTBIMjU2NHpNMCAyNTY0aDIzMTF2MjMxMUgwem0yNTY0IDBoMjMxMXYyMzExSDI1NjQiLz48L3N2Zz4=&label=)](https://github.com/nanomsg/nng/actions) -[![macOS Status](https://img.shields.io/github/actions/workflow/status/nanomsg/nng/darwin.yml?branch=dev2.0&logoColor=grey&logo=apple&label=)](https://github.com/nanomsg/nng/actions) +[![Linux Status](https://img.shields.io/github/actions/workflow/status/nanomsg/nng/linux.yml?branch=main&logoColor=grey&logo=ubuntu&label=)](https://github.com/nanomsg/nng/actions) +[![Windows Status](https://img.shields.io/github/actions/workflow/status/nanomsg/nng/windows.yml?branch=main&logoColor=grey&logo=data:image/svg%2bxml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCA0ODc1IDQ4NzUiPjxwYXRoIGZpbGw9ImdyZXkiIGQ9Ik0wIDBoMjMxMXYyMzEwSDB6bTI1NjQgMGgyMzExdjIzMTBIMjU2NHpNMCAyNTY0aDIzMTF2MjMxMUgwem0yNTY0IDBoMjMxMXYyMzExSDI1NjQiLz48L3N2Zz4=&label=)](https://github.com/nanomsg/nng/actions) +[![macOS Status](https://img.shields.io/github/actions/workflow/status/nanomsg/nng/darwin.yml?branch=main&logoColor=grey&logo=apple&label=)](https://github.com/nanomsg/nng/actions) [![Coverage](https://img.shields.io/codecov/c/github/nanomsg/nng?logo=codecov&logoColor=grey&label=)](https://codecov.io/gh/nanomsg/nng) [![Discord](https://img.shields.io/discord/639573728212156478?label=&logo=discord)](https://discord.gg/Xnac6b9) [![Manual](https://img.shields.io/static/v1?label=&message=docs&logo=asciidoctor&logoColor=silver&color=blue)](https://nng.nanomsg.org/man) -[![MIT License](https://img.shields.io/github/license/nanomsg/nng.svg?logoColor=silver&logo=open-source-initiative&label=&color=blue)](https://github.com/nanomsg/nng/blob/dev2.0/LICENSE.txt) +[![MIT License](https://img.shields.io/github/license/nanomsg/nng.svg?logoColor=silver&logo=open-source-initiative&label=&color=blue)](https://github.com/nanomsg/nng/blob/main/LICENSE.txt) [![Latest Version](https://img.shields.io/github/v/tag/nanomsg/nng.svg?logo=github&label=)](https://github.com/nanomsg/nng/releases) Please see [here](UKRAINE.md) for an important message for the people of Russia. @@ -105,7 +105,7 @@ Here are areas where this project improves on "nanomsg": This project offers both wire compatibility and API compatibility, so most nanomsg users can begin using NNG right away. -Existing nanomsg and https://github.com/nanomsg/mangos[mangos] applications +Existing nanomsg and [mangos](https://github.com/nanomsg/mangos) applications can inter-operate with NNG applications automatically. That said, there are some areas where legacy nanomsg still offers From 3051c24e361541b1097652d7b873ea270f99fb4a Mon Sep 17 00:00:00 2001 From: Garrett D'Amore Date: Sun, 6 Oct 2024 16:20:21 -0700 Subject: [PATCH 028/222] idmap public docs converted to mdbook --- docs/README.txt | 11 ++-- docs/book.toml | 17 ++++++ docs/ref/SUMMARY.md | 7 +++ docs/ref/api.md | 1 + docs/ref/api/util.md | 3 + docs/ref/api/util/nng_id_map.md | 101 ++++++++++++++++++++++++++++++++ docs/ref/indexing.md | 1 + 7 files changed, 135 insertions(+), 6 deletions(-) create mode 100644 docs/book.toml create mode 100644 docs/ref/SUMMARY.md create mode 100644 docs/ref/api.md create mode 100644 docs/ref/api/util.md create mode 100644 docs/ref/api/util/nng_id_map.md create mode 100644 docs/ref/indexing.md diff --git a/docs/README.txt b/docs/README.txt index 5331f67ba..8dae4711a 100644 --- a/docs/README.txt +++ b/docs/README.txt @@ -1,11 +1,10 @@ This contains the nng documentation for API users. -The documentation is written in asciidoc in the form of man pages. It is -automatically formatted for display on the website. - -It is possible to emit TROFF sources for use by the UNIX man page, and HTML -for online viewing. asciidoctor supports PDF and EPUB formats via plugins, -so there are still more options available. +Historically, the documentation was written in asciidoc in the form of man pages. +It is automatically formatted for display on the website. The man pages are in the "man" directory. The reason those are separate is that they get special treatment. Other documentation is located here. + +HOWEVER, we are converting the documentation to mdbook -- see ref/ as the top-level +of the new tree for that. diff --git a/docs/book.toml b/docs/book.toml new file mode 100644 index 000000000..d7fb14f7f --- /dev/null +++ b/docs/book.toml @@ -0,0 +1,17 @@ +[book] +authors = ["Garrett D'Amore"] +language = "en" +multilingual = false +src = "ref" +title = "NNG Reference Manual (DRAFT)" + +[output.html] +smart-punctuation = true +fold.enable = true +fold.level = 1 + +[preprocessor.alerts] + +[preprocessor.indexing] + +[preprocessor.footnote] diff --git a/docs/ref/SUMMARY.md b/docs/ref/SUMMARY.md new file mode 100644 index 000000000..09d1939c4 --- /dev/null +++ b/docs/ref/SUMMARY.md @@ -0,0 +1,7 @@ +# Summary + +- [API](./api.md) + - [Utility Functions](./api/util.md) + - [nng_id_map](./api/util/nng_id_map.md) + +[Index](./indexing.md) diff --git a/docs/ref/api.md b/docs/ref/api.md new file mode 100644 index 000000000..593279293 --- /dev/null +++ b/docs/ref/api.md @@ -0,0 +1 @@ +# API diff --git a/docs/ref/api/util.md b/docs/ref/api/util.md new file mode 100644 index 000000000..0ea03878b --- /dev/null +++ b/docs/ref/api/util.md @@ -0,0 +1,3 @@ +# Utility Functions + +- [nng_id_map](./util/nng_id_map.md) diff --git a/docs/ref/api/util/nng_id_map.md b/docs/ref/api/util/nng_id_map.md new file mode 100644 index 000000000..1dd077f5d --- /dev/null +++ b/docs/ref/api/util/nng_id_map.md @@ -0,0 +1,101 @@ +# nng_id_map + +## NAME + +nng_id_map - identifier based mapping table + +## SYNOPSIS + +```c +#include +#include + +typedef struct nng_id_map_s nng_id_map; + +#define NNG_MAP_RANDOM 1 + +int nng_id_map_alloc(nng_id_map **map_p, uint64_t lo, uint64_t hi, int flags); +void nng_id_map_free(nng_id_map *map); +void *nng_id_get(nng_id_map *map, uint64_t id); +int nng_id_set(nng_id_map *map, uint64_t, void *value); +int nng_id_alloc(nng_id_map *map, uint64_t *id_p, void *value); +int nng_id_remove(nng_id_map *map, uint64_t id); +bool nng_id_visit(nng_id_map *map, uint64_t *id_p, void **value_p, uint32_t *cursor); +``` + +## DESCRIPTION + +These functions provide support for managing tables of data based on +{{i:identifiers}}, ensuring that identifiers are allocated uniquely and within +specified range limits. + +The table stores data pointers (which must not be `NULL`) at a logical numeric index. +It does so efficiently, even if large gaps exist, and it provides a means to efficiently +allocate a numeric identifier from a pool of unused identifiers. + +Identifiers are allocated in increasing order, without reusing old identifiers until the +largest possible identifier is allocated. After wrapping, only identifiers that are no longer +in use will be considered. +No effort is made to order the availability of identifiers based on +when they were freed.{{footnote: The concern about possibly reusing a +recently released identifier comes into consideration after the range has wrapped. +Given a sufficiently large range, this is unlikely to be a concern.}} + +> [!IMPORTANT] +> These functions are _not_ thread-safe. +> Callers should use a [mutex][mutex] or similar approach when thread-safety is needed. + +### Initialization + +An initial table is allocated with `nng_id_map_alloc()`, which takes the lowest legal identifier in _lo_, +and the largest legal identifier in _hi_. +The new table is returned in _map_p_, and should be used as the _map_ argument to the rest of these functions. + +If these are specified as zero, then a full range of 32-bit identifiers is assumed. +If identifiers beyond 32-bits are required, +then both _lo_ and _hi_ must be specified with the exact values desired. +{{footnote: These functions are limited to storing at most 232 identifiers, even though the identifers may +themselves be larger than this.}} + +The _flags_ argument is a bit mask of flags for the table. +If `NNG_MAP_RANDOM` is specified, then the starting point for allocations is randomized, but subsequent allocations will then be monotonically increasing. +This is useful to reduce the odds of different instances of an application using the same identifiers at the same time. + +### Accessors + +The `nng_id_get()` function returns the value previously stored with the given identifier. +If no value is currently associated with the identifer, it returns `NULL`. + +The `nng_id_set()` function sets the value with the associated identifier. +This can be used to replace a previously allocated identifier. +If the identifier was not previously allocated, then it is allocated as part of the call. +This function does not necessarily honor the identifier range limits set for the map when it was allocated. + +The `nng_id_alloc()` function allocates a new identifier from the range for the map, and associates it with +the supplied _value_. + +The `nng_id_remove()` function removes the identifier and its associated value from the table. + +### Iteration + +The `nng_id_visit()` function is used to iterate over all items in the table. +The caller starts the iteration by setting the _cursor_ to 0 before calling it. +For each call, the associated key and value of the next item will be returned in _id_p_, +and _value_p_ and the _cursor_ will be updated. +When all items have been iterated, the function returns `false`. +The order of items returned is not guaranteed to be sequential. +The caller must not attempt to derive any value of the _cursor_ as it refers to internal table indices. + +## RETURN VALUES + +The `nng_id_map_alloc()`, `nng_id_set()`, `nng_id_alloc()`, and `nng_id_remove()` functions +return 0 on success, or -1 on failure. + +The `nng_id_map_get()` function returns the requested data pointer, or `NULL` if the identifier was not found. + +## ERRORS + +- `NNG_ENOENT`: The _id_ does not exist in the table. +- `NNG_ENOMEM`: Insufficient memory is available, or the table is full. + +[mutex]: ../thr/mutex.md diff --git a/docs/ref/indexing.md b/docs/ref/indexing.md new file mode 100644 index 000000000..8b013d6a6 --- /dev/null +++ b/docs/ref/indexing.md @@ -0,0 +1 @@ +# Index From 2717424e57b4dda9ee4cfa9ce931f42e97ac9882 Mon Sep 17 00:00:00 2001 From: Garrett D'Amore Date: Sun, 6 Oct 2024 16:53:20 -0700 Subject: [PATCH 029/222] Docs for mutexes converted. --- docs/ref/SUMMARY.md | 4 ++- docs/ref/api.md | 3 ++ docs/ref/api/thr/index.md | 3 ++ docs/ref/api/thr/nng_mtx.md | 63 +++++++++++++++++++++++++++++++++ docs/ref/api/util/index.md | 3 ++ docs/ref/api/util/nng_id_map.md | 18 +++++----- 6 files changed, 84 insertions(+), 10 deletions(-) create mode 100644 docs/ref/api/thr/index.md create mode 100644 docs/ref/api/thr/nng_mtx.md create mode 100644 docs/ref/api/util/index.md diff --git a/docs/ref/SUMMARY.md b/docs/ref/SUMMARY.md index 09d1939c4..253f23949 100644 --- a/docs/ref/SUMMARY.md +++ b/docs/ref/SUMMARY.md @@ -1,7 +1,9 @@ # Summary - [API](./api.md) - - [Utility Functions](./api/util.md) + - [Threading Functions](./api/thr/index.md) + - [nng_mtx](./api/thr/nng_mtx.md) + - [Utility Functions](./api/util/index.md) - [nng_id_map](./api/util/nng_id_map.md) [Index](./indexing.md) diff --git a/docs/ref/api.md b/docs/ref/api.md index 593279293..84d0501f5 100644 --- a/docs/ref/api.md +++ b/docs/ref/api.md @@ -1 +1,4 @@ # API + +- [Threading Support](api/thr/) +- [Utility Functions](api/util/) diff --git a/docs/ref/api/thr/index.md b/docs/ref/api/thr/index.md new file mode 100644 index 000000000..d9d168ac8 --- /dev/null +++ b/docs/ref/api/thr/index.md @@ -0,0 +1,3 @@ +# Threading Functions + +- [nng_mtx](nng_mtx.md) diff --git a/docs/ref/api/thr/nng_mtx.md b/docs/ref/api/thr/nng_mtx.md new file mode 100644 index 000000000..ecd00e225 --- /dev/null +++ b/docs/ref/api/thr/nng_mtx.md @@ -0,0 +1,63 @@ +# nng_id_map + +## NAME + +nng_mutex - mutual exclusion lock + +## SYNOPSIS + +```c +#include + +typedef struct nng_mtx nng_mtx; + +int nng_mtx_alloc(nng_mtx **mtxp); +void nng_mtx_free(nng_mtx *mtx); +void nng_mtx_lock(nng_mtx *mtx); +void nng_mtx_unlock(nng_mtx *mtx); +``` + +## DESCRIPTION + +The {{i:`nng_mutex`}}{{hi:mutex}} structure provides a {{i:mutual-exclusion}} {{i:lock}}, such +that only one thread at a time can have the lock (taken using `nng_mtx_lock`). +This is critical for solving certain problems that arise in concurrent programming. + +### Initialization and Teardown + +The `nng_mtx` structure is created dynamically, by the application using `nng_mtx_alloc`. +This function will store a pointer to the allocate mutex at the location signified by _mtxp_. + +When the application has no further need of the mutex, it can deallocate the resources +associated using the `nng_mtx_free` function. + +### Locking and Unlocking + +The `nng_mtx` lock can be acquired by a calling thread using the `nng_mtx_lock` function. + +The caller will block until the lock is acquired. +If multiple threads are contending for ownership of the lock, the order of +acquisition is not specified, and applications must not depend on it. + +> [!NOTE] +> Mutex locks are _not_ recursive; attempts to reacquire the +> same mutex may result in deadlock or aborting the current program. +> It is a programming error for the owner of a mutex to attempt to +> reacquire it. + +The lock can be released by the thread that has ownership using the `nng_mtx_unlock` function. + +> [!NOTE] +> A mutex can _only_ be unlocked by the thread that locked it. +> Attempting to unlock a mutex that is not owned by the caller will result +> in undefined behavior. + +## RETURN VALUES + +The `nng_mtx_lock` function returns 0 on success, or non-zero on failure. + +The other mutex functions always succeed, and have no return values. + +## ERRORS + +- `NNG_ENOMEM`: Insufficient memory is available, or the table is full. diff --git a/docs/ref/api/util/index.md b/docs/ref/api/util/index.md new file mode 100644 index 000000000..62c5fc67b --- /dev/null +++ b/docs/ref/api/util/index.md @@ -0,0 +1,3 @@ +# Utility Functions + +- [nng_id_map](nng_id_map.md) diff --git a/docs/ref/api/util/nng_id_map.md b/docs/ref/api/util/nng_id_map.md index 1dd077f5d..016c60e4d 100644 --- a/docs/ref/api/util/nng_id_map.md +++ b/docs/ref/api/util/nng_id_map.md @@ -47,7 +47,7 @@ Given a sufficiently large range, this is unlikely to be a concern.}} ### Initialization -An initial table is allocated with `nng_id_map_alloc()`, which takes the lowest legal identifier in _lo_, +An initial table is allocated with `nng_id_map_alloc`, which takes the lowest legal identifier in _lo_, and the largest legal identifier in _hi_. The new table is returned in _map_p_, and should be used as the _map_ argument to the rest of these functions. @@ -63,22 +63,22 @@ This is useful to reduce the odds of different instances of an application using ### Accessors -The `nng_id_get()` function returns the value previously stored with the given identifier. +The `nng_id_get` function returns the value previously stored with the given identifier. If no value is currently associated with the identifer, it returns `NULL`. -The `nng_id_set()` function sets the value with the associated identifier. +The `nng_id_set` function sets the value with the associated identifier. This can be used to replace a previously allocated identifier. If the identifier was not previously allocated, then it is allocated as part of the call. This function does not necessarily honor the identifier range limits set for the map when it was allocated. -The `nng_id_alloc()` function allocates a new identifier from the range for the map, and associates it with +The `nng_id_alloc` function allocates a new identifier from the range for the map, and associates it with the supplied _value_. -The `nng_id_remove()` function removes the identifier and its associated value from the table. +The `nng_id_remove` function removes the identifier and its associated value from the table. ### Iteration -The `nng_id_visit()` function is used to iterate over all items in the table. +The `nng_id_visit` function is used to iterate over all items in the table. The caller starts the iteration by setting the _cursor_ to 0 before calling it. For each call, the associated key and value of the next item will be returned in _id_p_, and _value_p_ and the _cursor_ will be updated. @@ -88,14 +88,14 @@ The caller must not attempt to derive any value of the _cursor_ as it refers to ## RETURN VALUES -The `nng_id_map_alloc()`, `nng_id_set()`, `nng_id_alloc()`, and `nng_id_remove()` functions +The `nng_id_map_alloc`, `nng_id_set`, `nng_id_alloc`, and `nng_id_remove` functions return 0 on success, or -1 on failure. -The `nng_id_map_get()` function returns the requested data pointer, or `NULL` if the identifier was not found. +The `nng_id_map_get` function returns the requested data pointer, or `NULL` if the identifier was not found. ## ERRORS - `NNG_ENOENT`: The _id_ does not exist in the table. - `NNG_ENOMEM`: Insufficient memory is available, or the table is full. -[mutex]: ../thr/mutex.md +[mutex]: ../thr/nng_mtx.md From 1d2ebb7f2199330c503eb9c04d42af3d08b3cc54 Mon Sep 17 00:00:00 2001 From: Garrett D'Amore Date: Sun, 6 Oct 2024 16:59:47 -0700 Subject: [PATCH 030/222] Remove old idmap and mutex docs Signed-off-by: jaylin --- docs/man/libnng.3.adoc | 38 +++++----- docs/man/nng_id_map.3supp.adoc | 108 ----------------------------- docs/man/nng_mtx_alloc.3supp.adoc | 58 ---------------- docs/man/nng_mtx_free.3supp.adoc | 43 ------------ docs/man/nng_mtx_lock.3supp.adoc | 65 ----------------- docs/man/nng_mtx_unlock.3supp.adoc | 48 ------------- 6 files changed, 19 insertions(+), 341 deletions(-) delete mode 100644 docs/man/nng_id_map.3supp.adoc delete mode 100644 docs/man/nng_mtx_alloc.3supp.adoc delete mode 100644 docs/man/nng_mtx_free.3supp.adoc delete mode 100644 docs/man/nng_mtx_lock.3supp.adoc delete mode 100644 docs/man/nng_mtx_unlock.3supp.adoc diff --git a/docs/man/libnng.3.adoc b/docs/man/libnng.3.adoc index 9b078329b..2ae608f2f 100644 --- a/docs/man/libnng.3.adoc +++ b/docs/man/libnng.3.adoc @@ -277,25 +277,25 @@ network applications with _NNG_, but they are made available as a convenience to aid in creating portable applications. |=== -|xref:nng_clock.3supp.adoc[nng_clock]|get time -|xref:nng_cv_alloc.3supp.adoc[nng_cv_alloc]|allocate condition variable -|xref:nng_cv_free.3supp.adoc[nng_cv_free]|free condition variable -|xref:nng_cv_until.3supp.adoc[nng_cv_until]|wait for condition or timeout -|xref:nng_cv_wait.3supp.adoc[nng_cv_wait]|wait for condition -|xref:nng_cv_wake.3supp.adoc[nng_cv_wake]|wake all waiters -|xref:nng_cv_wake1.3supp.adoc[nng_cv_wake1]|wake one waiter -|xref:nng_id_map.3supp.adoc[nng_id_map]|identifier based mapping table -|xref:nng_msleep.3supp.adoc[nng_msleep]|sleep for milliseconds -|xref:nng_mtx_alloc.3supp.adoc[nng_mtx_alloc]|allocate mutex -|xref:nng_mtx_free.3supp.adoc[nng_mtx_free]|free mutex -|xref:nng_mtx_lock.3supp.adoc[nng_mtx_lock]|lock mutex -|xref:nng_mtx_unlock.3supp.adoc[nng_mtx_unlock]|unlock mutex -|xref:nng_opts_parse.3supp.adoc[nng_opts_parse]|parse command line options -|xref:nng_random.3supp.adoc[nng_random]|get random number -|xref:nng_socket_pair.3supp.adoc[nng_socket_pair]|create connected pair of BSD sockets -|xref:nng_thread_create.3supp.adoc[nng_thread_create]|create thread -|xref:nng_thread_destroy.3supp.adoc[nng_thread_destroy]|reap thread -|xref:nng_thread_set_name.3supp.adoc[nng_thread_set_name]|set thread name +|xref:nng_clock.3supp.adoc[nng_clock()]|get time +|xref:nng_cv_alloc.3supp.adoc[nng_cv_alloc()]|allocate condition variable +|xref:nng_cv_free.3supp.adoc[nng_cv_free()]|free condition variable +|xref:nng_cv_until.3supp.adoc[nng_cv_until()]|wait for condition or timeout +|xref:nng_cv_wait.3supp.adoc[nng_cv_wait()]|wait for condition +|xref:nng_cv_wake.3supp.adoc[nng_cv_wake()]|wake all waiters +|xref:nng_cv_wake1.3supp.adoc[nng_cv_wake1()]|wake one waiter +// |xref:nng_id_map.3supp.adoc[nng_id_map]|identifier based mapping table +|xref:nng_msleep.3supp.adoc[nng_msleep()]|sleep for milliseconds +// |xref:nng_mtx_alloc.3supp.adoc[nng_mtx_alloc()]|allocate mutex +// |xref:nng_mtx_free.3supp.adoc[nng_mtx_free()]|free mutex +// |xref:nng_mtx_lock.3supp.adoc[nng_mtx_lock()]|lock mutex +// |xref:nng_mtx_unlock.3supp.adoc[nng_mtx_unlock()]|unlock mutex +|xref:nng_opts_parse.3supp.adoc[nng_opts_parse()]|parse command line options +|xref:nng_random.3supp.adoc[nng_random()]|get random number +|xref:nng_socket_pair.3supp.adoc[nng_socket_pair()]|create connected pair of BSD sockets +|xref:nng_thread_create.3supp.adoc[nng_thread_create()]|create thread +|xref:nng_thread_destroy.3supp.adoc[nng_thread_destroy()]|reap thread +|xref:nng_thread_set_name.3supp.adoc[nng_thread_set_name()]|set thread name |=== === Byte Streams diff --git a/docs/man/nng_id_map.3supp.adoc b/docs/man/nng_id_map.3supp.adoc deleted file mode 100644 index 5bebf1c41..000000000 --- a/docs/man/nng_id_map.3supp.adoc +++ /dev/null @@ -1,108 +0,0 @@ -= nng_id_map(3supp) -// -// 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 -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_id_map - identifier based mapping table - -== SYNOPSIS - -[source, c] ----- -#include -#include - -typedef struct nng_id_map_s nng_id_map; - -#define NNG_MAP_RANDOM 1 - -int nng_id_map_alloc(nng_id_map **map_p, uint64_t lo, uint64_t hi, int flags); -void nng_id_map_free(nng_id_map *map); -void *nng_id_get(nng_id_map *map, uint64_t id); -int nng_id_set(nng_id_map *map, uint64_t, void *value); -int nng_id_alloc(nng_id_map *map, uint64_t *id_p, void *value); -int nng_id_remove(nng_id_map *map, uint64_t id); -bool nng_id_visit(nng_id_map *map, uint64_t *id_p, void **value_p, uint32_t *cursor); - ----- - -== DESCRIPTION - -These functions provide support for managing tables of data based on -identifiers, ensuring that identifiers are allocated uniquely and within -specified range limits. - -The table stores data pointers (which must not be `NULL`) at a logical numeric index. -It does so efficiently, even if large gaps exist, and it provides a means to efficiently -allocate a numeric identifier from a pool of unused identifiers. - -Identifiers are allocated in increasing order, without reusing old identifiers until the -largest possible identifier is allocated. After wrapping, only identifiers that are no longer -in use will be considered. -No effort to order the availability of identifiers based on when they were freed is made. - -An initial table is allocated with `nng_id_map_alloc()`, which takes the lowest legal identifier in _lo_, -and the largest legal identifier in _hi_. -The new table is returned in _map_p_, and should be used as the _map_ argument to the rest of these functions. - -**** -As a special convenience, if these are specified as zero, then a full range of 32-bit identifiers is assumed. -If identifiers larger than or equal to 2^32^ are required, then both _lo_ and _hi_ must be specified with the -exact values desired. -**** - -The _flags_ argument is a bit mask of flags for the table. -If `NNG_MAP_RANDOM` is specified, then the starting point for allocations is randomized, but subsequent allocations will then be monotonically increasing. -This is useful to reduce the odds of different instances of an application using the same identifiers at the same time. - -The `nng_id_get()` function returns the value previously stored with the given identifier. -If no value is currently associated with the identifer, it returns `NULL`. - -The `nng_id_set()` function sets the value with the associated identifier. -This can be used to replace a previously allocated identifier. -If the identifier was not previously allocated, then it is allocated as part of the call. -This function does not necessarily honor the identifier range limits set for the map when it was allocated. - -The `nng_id_alloc()` function allocates a new identifier from the range for the map, and associates it with -the supplied _value_. - -The `nng_id_remove()` function removes the identifier and its associated value from the table. - -The `nng_id_visit()` function is used to iterate over all items in the table. -The caller starts the iteration by setting the _cursor_ to 0 before calling it. -For each call, the associated key and value of the next item will be returned in __id_p__, and __value_p__ and the _cursor_ will be updated. -When all items have been iterated, the function returns `false`. -The order of items returned is not guaranteed to be sequential. -The caller must not attempt to derive any value of the _cursor_ as it refers to internal table indices. - -NOTE: These functions are limited to storing at most 2^32^ identifiers, even though the identifers may -themselves be larger than 2^32^. - -IMPORTANT: These functions are *not* thread-safe. -Callers should use a xref:nng_mtx_lock.3supp[mutex] or similar approach when thread-safety is needed. - -== RETURN VALUES - -The `nng_id_map_alloc()`, `nng_id_set()`, `nng_id_alloc()`, and `nng_id_remove()` functions -return 0 on success, or -1 on failure. - -The `nng_id_map_get()` function returns the requested data pointer, or `NULL` if the identifier was not found. - -== ERRORS - -[horizontal] -`NNG_ENOENT`:: The _id_ does not exist in the table. -`NNG_ENOMEM`:: Insufficient memory is available, or the table is full. - -== SEE ALSO - -[.text-left] -xref:nng_mtx_lock.3supp.adoc[nng(7)] -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_mtx_alloc.3supp.adoc b/docs/man/nng_mtx_alloc.3supp.adoc deleted file mode 100644 index 45bbfac23..000000000 --- a/docs/man/nng_mtx_alloc.3supp.adoc +++ /dev/null @@ -1,58 +0,0 @@ -= nng_mtx_alloc(3supp) -// -// Copyright 2018 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_mtx_alloc - allocate mutex - -== SYNOPSIS - -[source, c] ----- -#include -#include - -typedef struct nng_mtx nng_mtx; - -int nng_mtx_alloc(nng_mtx **mtxp); ----- - -== DESCRIPTION - -The `nng_mtx_alloc()` function allocates mutex and returns it in _mtxp_. - -The mutex objects created by this function are suitable only for -simple lock and unlock operations, and are not recursive. -Every effort has been made to use light-weight underlying primitives when available. - -Mutex (mutual exclusion) objects can be thought of as binary semaphores, -where only a single thread of execution is permitted to acquire the semaphore. - -Furthermore, a mutex can only be unlocked by the thread that locked it. - -== RETURN VALUES - -This function returns 0 on success, and non-zero otherwise. - -== ERRORS - -[horizontal] -`NNG_ENOMEM`:: Insufficient free memory exists. - -== SEE ALSO - -[.text-left] -xref:nng_cv_alloc.3supp.adoc[nng_cv_alloc(3supp)], -xref:nng_mtx_free.3supp.adoc[nng_mtx_free(3supp)], -xref:nng_mtx_lock.3supp.adoc[nng_mtx_lock(3supp)], -xref:nng_mtx_unlock.3supp.adoc[nng_mtx_unlock(3supp)], -xref:nng_strerror.3.adoc[nng_strerror(3)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_mtx_free.3supp.adoc b/docs/man/nng_mtx_free.3supp.adoc deleted file mode 100644 index 2867afe16..000000000 --- a/docs/man/nng_mtx_free.3supp.adoc +++ /dev/null @@ -1,43 +0,0 @@ -= nng_mtx_free(3supp) -// -// Copyright 2018 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_mtx_free - free mutex - -== SYNOPSIS - -[source, c] ----- -#include -#include - -void nng_mtx_free(nng_mtx *mtx); ----- - -== DESCRIPTION - -The `nng_mtx_free()` function frees the mutex _mtx_. -The mutex must not be locked when this function is called. - -== RETURN VALUES - -None. - -== ERRORS - -None. - -== SEE ALSO - -[.text-left] -xref:nng_mtx_alloc.3supp.adoc[nng_mtx_alloc(3supp)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_mtx_lock.3supp.adoc b/docs/man/nng_mtx_lock.3supp.adoc deleted file mode 100644 index 91fd2ab5f..000000000 --- a/docs/man/nng_mtx_lock.3supp.adoc +++ /dev/null @@ -1,65 +0,0 @@ -= nng_mtx_lock(3supp) -// -// Copyright 2018 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_mtx_lock - lock mutex - -== SYNOPSIS - -[source, c] ----- -#include -#include - -void nng_mtx_lock(nng_mtx *mtx); ----- - -== DESCRIPTION - -The `nng_mtx_lock()` acquires exclusive ownership of the mutex _mtx_. -If the lock is already owned, this function will wait until the current -owner releases it with xref:nng_mtx_unlock.3supp.adoc[`nng_mtx_unlock()`]. - -If multiple threads are waiting for the lock, the order of acquisition -is not specified. - -NOTE: A mutex can _only_ be unlocked by the thread that locked it. - -IMPORTANT: Mutex locks are _not_ recursive; attempts to reacquire the -same mutex may result in deadlock or aborting the current program. -It is a programming error for the owner of a mutex to attempt to -reacquire it. - -**** -_NNG_ offers neither a non-blocking variant that can fail, -nor recursive mutexes. -This is by design, as _NNG_ itself does not use such things, -and most often the need for them is the result of poor design. -If such capabilities are needed, they may be synthesized fairly -easily from mutexes and condition variables. -**** - -== RETURN VALUES - -None. - -== ERRORS - -None. - -== SEE ALSO - -[.text-left] -xref:nng_cv_alloc.3supp.adoc[nng_cv_alloc(3supp)], -xref:nng_mtx_alloc.3supp.adoc[nng_mtx_alloc(3supp)], -xref:nng_mtx_unlock.3supp.adoc[nng_mtx_unlock(3supp)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_mtx_unlock.3supp.adoc b/docs/man/nng_mtx_unlock.3supp.adoc deleted file mode 100644 index d1b048e6d..000000000 --- a/docs/man/nng_mtx_unlock.3supp.adoc +++ /dev/null @@ -1,48 +0,0 @@ -= nng_mtx_unlock(3supp) -// -// Copyright 2018 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_mtx_unlock - unlock mutex - -== SYNOPSIS - -[source, c] ----- -#include -#include - -void nng_mtx_unlock(nng_mtx *mtx); ----- - -== DESCRIPTION - -The `nng_mtx_unlock()` relinquishes ownership of the mutex _mtx_ that -was previously acquired via xref:nng_mtx_lock.3supp.adoc[`nng_mtx_lock()`]. - -IMPORTANT: A mutex can _only_ be unlocked by the thread that locked it. -Attempting to unlock a mutex that is not owned by the caller will result -in undefined behavior. - -== RETURN VALUES - -None. - -== ERRORS - -None. - -== SEE ALSO - -[.text-left] -xref:nng_mtx_alloc.3supp.adoc[nng_mtx_alloc(3supp)], -xref:nng_mtx_lock.3supp.adoc[nng_mtx_lock(3supp)], -xref:nng.7.adoc[nng(7)] From 8d35b000f705eac3b0c79adb9b75a29779678e89 Mon Sep 17 00:00:00 2001 From: Garrett D'Amore Date: Sun, 6 Oct 2024 17:10:44 -0700 Subject: [PATCH 031/222] Convert nng_clock and nng_msleep docs to mdbook --- docs/ref/SUMMARY.md | 2 ++ docs/ref/api/util/index.md | 2 ++ docs/ref/api/util/nng_clock.md | 47 +++++++++++++++++++++++++++++++++ docs/ref/api/util/nng_msleep.md | 32 ++++++++++++++++++++++ 4 files changed, 83 insertions(+) create mode 100644 docs/ref/api/util/nng_clock.md create mode 100644 docs/ref/api/util/nng_msleep.md diff --git a/docs/ref/SUMMARY.md b/docs/ref/SUMMARY.md index 253f23949..78853440c 100644 --- a/docs/ref/SUMMARY.md +++ b/docs/ref/SUMMARY.md @@ -4,6 +4,8 @@ - [Threading Functions](./api/thr/index.md) - [nng_mtx](./api/thr/nng_mtx.md) - [Utility Functions](./api/util/index.md) + - [nng_clock](./api/util/nng_clock.md) - [nng_id_map](./api/util/nng_id_map.md) + - [nng_msleep](./api/util/nng_msleep.md) [Index](./indexing.md) diff --git a/docs/ref/api/util/index.md b/docs/ref/api/util/index.md index 62c5fc67b..9f155b659 100644 --- a/docs/ref/api/util/index.md +++ b/docs/ref/api/util/index.md @@ -1,3 +1,5 @@ # Utility Functions +- [nng_clock](nng_clock.md) - [nng_id_map](nng_id_map.md) +- [nng_msleep](nng_msleep.md) diff --git a/docs/ref/api/util/nng_clock.md b/docs/ref/api/util/nng_clock.md new file mode 100644 index 000000000..f4e9f9d54 --- /dev/null +++ b/docs/ref/api/util/nng_clock.md @@ -0,0 +1,47 @@ +# nng_clock + +## NAME + +nng_clock - get time + +## SYNOPSIS + +```c +#include + +typedef uint64_t nng_time; + +nng_time nng_clock(void); +``` + +## DESCRIPTION + +The `nng_clock` function returns the number of elapsed milliseconds since some +arbitrary time in the past. +The resolution of the clock depends on the underlying timing facilities +of the system. +This function may be used for timing, but applications should not expect +very fine-grained values. + +> [!NOTE] +> The reference time will be the same for a given program, +> but different programs may have different references. + +This function is intended to help with setting appropriate +timeouts using [`nng_cv_until`][nng_cv_until] +or [`nng_aio_set_expire`][nng_aio_set_timeout]. + +## RETURN VALUES + +Milliseconds since reference time. + +## SEE ALSO + +[nng_cv_until][nng_cv_until], +[nng_msleep][nng_msleep], +[nng_sleep_aio][nng_sleep_aio] + +[nng_cv_until]: ../thr/nng_cv.md +[nng_msleep]: ../util/nng_msleep.md +[nng_sleep_aio]: ../aio/nng_sleep_aio.md +[nng_aio_set_timeout]: ../aio/nng_aio_set_timeout.md diff --git a/docs/ref/api/util/nng_msleep.md b/docs/ref/api/util/nng_msleep.md new file mode 100644 index 000000000..ed3b8b27f --- /dev/null +++ b/docs/ref/api/util/nng_msleep.md @@ -0,0 +1,32 @@ +# nng_msleep + +## NAME + +nng_msleep --- sleep milliseconds + +## SYNOPSIS + +```c +#include + +typedef int64_t nng_duration; + +void nng_msleep(nng_duration msec); +``` + +## DESCRIPTION + +The `nng_msleep()` blocks the caller for at least _msec_ milliseconds. + +> [!NOTE] +> This function may block for longer than requested. +> The actual wait time is determined by the capabilities of the +> underlying system. + +## SEE ALSO + +[nng_sleep_aio][nng_sleep_aio], +[nng_clock][nng_clock] + +[nng_clock]: ../util/nng_clock.md +[nng_sleep_aio]: ../aio/nng_sleep_aio.md From 23ed3507647aed91e0246f82949177a6a6d9d568 Mon Sep 17 00:00:00 2001 From: Garrett D'Amore Date: Sun, 6 Oct 2024 17:14:05 -0700 Subject: [PATCH 032/222] Remove asciidoc nng_clock and nng_msleep --- docs/man/nng_clock.3supp.adoc | 57 ---------------------------------- docs/man/nng_msleep.3supp.adoc | 48 ---------------------------- 2 files changed, 105 deletions(-) delete mode 100644 docs/man/nng_clock.3supp.adoc delete mode 100644 docs/man/nng_msleep.3supp.adoc diff --git a/docs/man/nng_clock.3supp.adoc b/docs/man/nng_clock.3supp.adoc deleted file mode 100644 index 4c91c645c..000000000 --- a/docs/man/nng_clock.3supp.adoc +++ /dev/null @@ -1,57 +0,0 @@ -= nng_clock(3supp) -// -// Copyright 2024 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_clock - get time - -== SYNOPSIS - -[source, c] ----- -#include - -typedef uint64_t nng_time; - -nng_time nng_clock(void); ----- - -== DESCRIPTION - -The `nng_clock()` returns the number of elapsed milliseconds since some -arbitrary time in the past. -The resolution of the clock depends on the underlying timing facilities -of the system. -This function may be used for timing, but applications should not expect -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 should help with setting appropriate timeouts. - -== RETURN VALUES - -Milliseconds since reference time. - -== ERRORS - -None. - -== SEE ALSO - -[.text-left] -xref:nng_sleep_aio.3.adoc[nng_sleep_aio(3)], -xref:nng_strerror.3.adoc[nng_strerror(3)], -xref:nng_cv_until.3supp.adoc[nng_cv_until(3supp)], -xref:nng_msleep.3supp.adoc[nng_msleep(3supp)], -xref:nng_duration.5.adoc[nng_duration(5)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_msleep.3supp.adoc b/docs/man/nng_msleep.3supp.adoc deleted file mode 100644 index bef745879..000000000 --- a/docs/man/nng_msleep.3supp.adoc +++ /dev/null @@ -1,48 +0,0 @@ -= nng_msleep(3supp) -// -// Copyright 2024 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_msleep - sleep milliseconds - -== SYNOPSIS - -[source, c] ----- -#include - -void nng_msleep(nng_duration msec); ----- - -== DESCRIPTION - -The `nng_msleep()` blocks the caller for at least _msec_ milliseconds. - -NOTE: This function may block for longer than requested. -The actual wait time is determined by the capabilities of the -underlying system. - -== RETURN VALUES - -None. - -== ERRORS - -None. - -== SEE ALSO - -[.text-left] -xref:nng_sleep_aio.3.adoc[nng_sleep_aio(3)], -xref:nng_strerror.3.adoc[nng_strerror(3)], -xref:nng_clock.3supp.adoc[nng_clock(3supp)], -xref:nng_duration.5.adoc[nng_duration(5)], -xref:nng.7.adoc[nng(7)] From 9c7a463a29eb322d6494655e3ce1da87c60809db Mon Sep 17 00:00:00 2001 From: Garrett D'Amore Date: Sun, 6 Oct 2024 17:15:02 -0700 Subject: [PATCH 033/222] Style fix for nng_msleep --- docs/man/libnng.3.adoc | 4 ++-- docs/ref/api/util/nng_msleep.md | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/man/libnng.3.adoc b/docs/man/libnng.3.adoc index 2ae608f2f..7a0768458 100644 --- a/docs/man/libnng.3.adoc +++ b/docs/man/libnng.3.adoc @@ -277,7 +277,7 @@ network applications with _NNG_, but they are made available as a convenience to aid in creating portable applications. |=== -|xref:nng_clock.3supp.adoc[nng_clock()]|get time +// |xref:nng_clock.3supp.adoc[nng_clock()]|get time |xref:nng_cv_alloc.3supp.adoc[nng_cv_alloc()]|allocate condition variable |xref:nng_cv_free.3supp.adoc[nng_cv_free()]|free condition variable |xref:nng_cv_until.3supp.adoc[nng_cv_until()]|wait for condition or timeout @@ -285,7 +285,7 @@ as a convenience to aid in creating portable applications. |xref:nng_cv_wake.3supp.adoc[nng_cv_wake()]|wake all waiters |xref:nng_cv_wake1.3supp.adoc[nng_cv_wake1()]|wake one waiter // |xref:nng_id_map.3supp.adoc[nng_id_map]|identifier based mapping table -|xref:nng_msleep.3supp.adoc[nng_msleep()]|sleep for milliseconds +// |xref:nng_msleep.3supp.adoc[nng_msleep()]|sleep for milliseconds // |xref:nng_mtx_alloc.3supp.adoc[nng_mtx_alloc()]|allocate mutex // |xref:nng_mtx_free.3supp.adoc[nng_mtx_free()]|free mutex // |xref:nng_mtx_lock.3supp.adoc[nng_mtx_lock()]|lock mutex diff --git a/docs/ref/api/util/nng_msleep.md b/docs/ref/api/util/nng_msleep.md index ed3b8b27f..d9e49e499 100644 --- a/docs/ref/api/util/nng_msleep.md +++ b/docs/ref/api/util/nng_msleep.md @@ -16,7 +16,7 @@ void nng_msleep(nng_duration msec); ## DESCRIPTION -The `nng_msleep()` blocks the caller for at least _msec_ milliseconds. +The `nng_msleep` blocks the caller for at least _msec_ milliseconds. > [!NOTE] > This function may block for longer than requested. From f685fa1e02b9ec3acb553ee5824aa237fdece7b2 Mon Sep 17 00:00:00 2001 From: Garrett D'Amore Date: Sun, 6 Oct 2024 17:45:39 -0700 Subject: [PATCH 034/222] Initial swag at UDP transport docs, also converted socket transport to mdbook This has a lot of TODO links, because there are missing pieces still of course. --- docs/ref/SUMMARY.md | 6 +++ docs/ref/tran/index.md | 4 ++ docs/ref/tran/socket.md | 71 ++++++++++++++++++++++++++++++++ docs/ref/tran/udp.md | 90 +++++++++++++++++++++++++++++++++++++++++ 4 files changed, 171 insertions(+) create mode 100644 docs/ref/tran/index.md create mode 100644 docs/ref/tran/socket.md create mode 100644 docs/ref/tran/udp.md diff --git a/docs/ref/SUMMARY.md b/docs/ref/SUMMARY.md index 78853440c..72b7dd94b 100644 --- a/docs/ref/SUMMARY.md +++ b/docs/ref/SUMMARY.md @@ -1,6 +1,7 @@ # Summary - [API](./api.md) + - [Threading Functions](./api/thr/index.md) - [nng_mtx](./api/thr/nng_mtx.md) - [Utility Functions](./api/util/index.md) @@ -8,4 +9,9 @@ - [nng_id_map](./api/util/nng_id_map.md) - [nng_msleep](./api/util/nng_msleep.md) +- [Transports](./tran/index.md) + + - [BSD Socket](./tran/socket.md) + - [UDP](./tran/udp.md) + [Index](./indexing.md) diff --git a/docs/ref/tran/index.md b/docs/ref/tran/index.md new file mode 100644 index 000000000..25f32a7f7 --- /dev/null +++ b/docs/ref/tran/index.md @@ -0,0 +1,4 @@ +# Transports + +- [BSD Socket](socket.md) +- [UDP](udp.md) diff --git a/docs/ref/tran/socket.md b/docs/ref/tran/socket.md new file mode 100644 index 000000000..cfb31ca3e --- /dev/null +++ b/docs/ref/tran/socket.md @@ -0,0 +1,71 @@ +# BSD Socket Transport (Experimental) + +The {{i:_socket_ transport}} supports communication between +peers across arbitrary BSD sockets, such as those that are +created with [`nng_socket_pair()`][nng_socket_pair]. + +This transport only supports [listeners][listener], +using [`nng_listener_create()`][nng_listener_create]. + +> [!NOTE] +> Attempts to create [dialers][dialer] using this transport will result in `NNG_ENOTSUP`. + +The socket file descriptor is passed to the listener using +the {{i:`NNG_OPT_SOCKET_FD`}} option (as an integer). +Setting this option will cause the listener to create a [pipe][pipe] +backed by the file descriptor. + +The protocol between peers using this transport is compatible with the protocol used +for the [_tcp_][tcp] transport, but this is an implementation detail and subject to change without notice. +{{footnote: Specifically it is not compatible with the [_ipc_][ipc] transport.}} + +> [!NOTE] +> This transport is _experimental_, and at present is only supported on POSIX platforms. +> {{footnote: Windows lacks a suitable `socketpair()` equivalent function we could use.}} + +## Registration + +No special action is necessary to register this transport. + +## URI Format + +This transport uses the URL {{i:`socket://`}}, without further qualification. + +## Socket Address + +The socket address will be of family {{i:`NNG_AF_UNSPEC`}}. +There are no further socket details available. + +## Transport Options + +The following transport option is available: + +- {{i:`NNG_OPT_SOCKET_FD`}}: \ + (int) \ + \ + This is a write-only option, that may be set multiple times on a listener. + Each time this is set, the listener will create a [pipe][pipe] backed by the given file + descriptor passed as an argument. + +Additionally, the following options may be supported on pipes when the platform supports them: + +- [`NNG_OPT_PEER_GID`][NNG_OPT_PEER_GID] +- [`NNG_OPT_PEER_PID`][NNG_OPT_PEER_PID] +- [`NNG_OPT_PEER_UID`][NNG_OPT_PEER_UID] +- [`NNG_OPT_PEER_ZONEID`][NNG_OPT_PEER_ZONEID] + +[ipc]: [ipc.md] +[tcp]: [tcp.md] +[pipe]: [TODO.md] +[listener]: [TODO.md] +[dialer]: [TODO.md] +[nng_sockaddr]: [TODO.md] +[nng_listener_create]: [TODO.md] +[nng_socket_pair]: [TODO.md] +[NNG_OPT_LOCADDR]: [TODO.md] +[NNG_OPT_REMADDR]: [TODO.md] +[NNG_OPT_URL]: [TODO.md] +[NNG_OPT_PEER_GID]: [TODO.md] +[NNG_OPT_PEER_PID]: [TODO.md] +[NNG_OPT_PEER_UID]: [TODO.md] +[NNG_OPT_PEER_ZONEID]: [TODO.md] diff --git a/docs/ref/tran/udp.md b/docs/ref/tran/udp.md new file mode 100644 index 000000000..4579c88aa --- /dev/null +++ b/docs/ref/tran/udp.md @@ -0,0 +1,90 @@ +# UDP Transport (Experimental) + +The {{i:_udp_ transport}} supports communication between peers using {{i:UDP}}. + +UDP is a very light-weight connection-less, unreliable, unordered delivery mechanism. + +Both IPv4 and {{i:IPv6}} are supported when the underlying platform also supports it. + +## Maximum Message Size + +This transport maps each SP message to a single UDP packet. +In order to allow room for network headers, we thus limit the maximum +message size to 65000 bytes, minus the overhead for any SP protocol headers. + +However, applications are _strongly_ encouraged to only use this transport for +very much smaller messages, ideally those that will fit within a single network +packet without requiring fragmentation and reassembly. + +For Ethernet without jumbo frames, this typically means an {{i:MTU}} of a little +less than 1500 bytes. (Specifically, 1452, which allows 28 bytes for IP and UDP, +and 20 bytes for the this transport). +Other link layers may have different MTUs. + +> [!NOTE] +> This transport is _experimental_. + +## URI Format + +This transport uses URIs using the scheme {{i:`udp://`}}, followed by +an IP address or hostname, followed by a colon and finally a +TCP {{i:port number}}. +For example, to contact port 80 on the localhost either of the following URIs +could be used: `udp://127.0.0.1:80` or `udp://localhost:80`. + +A URI may be restricted to IPv6 using the scheme `udp6://`, and may +be restricted to IPv4 using the scheme `udp4://`. + +> [!NOTE] +> Specifying `udp6://` may not prevent IPv4 hosts from being used with +> IPv4-in-IPv6 addresses, particularly when using a wildcard hostname with +> listeners. +> The details of this varies across operating systems. + +> [!TIP] +> We recommend using either numeric IP addresses, or names that are +> specific to either IPv4 or IPv6 to prevent confusion and surprises. + +When specifying IPv6 addresses, the address must be enclosed in +square brackets (`[]`) to avoid confusion with the final colon +separating the port. + +For example, the same port 80 on the IPv6 loopback address (`::1`) would +be specified as `udp://[::1]:80`. + +The special value of 0 ({{i:`INADDR_ANY`}}) +can be used for a listener to indicate that it should listen on all +interfaces on the host. +A short-hand for this form is to either omit the address, or specify +the asterisk (`*`) character. +For example, the following three URIs are all equivalent, +and could be used to listen to port 9999 on the host: + +1. `udp://0.0.0.0:9999` +2. `udp://*:9999` +3. `udp://:9999` + +## Socket Address + +When using an [`nng_sockaddr`][nng_sockaddr] structure, +the actual structure is either of type +[`nng_sockaddr_in`][nng_sockaddr_in] (for IPv4) or +[`nng_sockaddr_in6`][nng_sockaddr_in6] (for IPv6). + +## Transport Options + +The following transport options are supported by this transport, +where supported by the underlying platform. + +- [`NNG_OPT_LOCADDR`][NNG_OPT_LOCADDR] +- [`NNG_OPT_REMADDR`][NNG_OPT_REMADDR] +- [`NNG_OPT_URL`][NNG_OPT_URL] + +TOOD: Document other options. + +[nng_sockaddr]: [TODO.md] +[nng_sockaddr_in]: [TODO.md] +[nng_sockaddr_in6]: [TODO.md] +[NNG_OPT_LOCADDR]: [TODO.md] +[NNG_OPT_REMADDR]: [TODO.md] +[NNG_OPT_URL]: [TODO.md] From 007dd246f213fd310c9e06c1cb399b16c9fbd56f Mon Sep 17 00:00:00 2001 From: Garrett D'Amore Date: Sun, 6 Oct 2024 17:58:48 -0700 Subject: [PATCH 035/222] Fix UDP port numbers in docs --- docs/ref/tran/udp.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/ref/tran/udp.md b/docs/ref/tran/udp.md index 4579c88aa..5a10e2d77 100644 --- a/docs/ref/tran/udp.md +++ b/docs/ref/tran/udp.md @@ -28,9 +28,9 @@ Other link layers may have different MTUs. This transport uses URIs using the scheme {{i:`udp://`}}, followed by an IP address or hostname, followed by a colon and finally a -TCP {{i:port number}}. -For example, to contact port 80 on the localhost either of the following URIs -could be used: `udp://127.0.0.1:80` or `udp://localhost:80`. +UDP {{i:port number}}. +For example, to contact port 8001 on the localhost either of the following URIs +could be used: `udp://127.0.0.1:8001` or `udp://localhost:8001`. A URI may be restricted to IPv6 using the scheme `udp6://`, and may be restricted to IPv4 using the scheme `udp4://`. @@ -49,8 +49,8 @@ When specifying IPv6 addresses, the address must be enclosed in square brackets (`[]`) to avoid confusion with the final colon separating the port. -For example, the same port 80 on the IPv6 loopback address (`::1`) would -be specified as `udp://[::1]:80`. +For example, the same port 8001 on the IPv6 loopback address (`::1`) would +be specified as `udp://[::1]:8001`. The special value of 0 ({{i:`INADDR_ANY`}}) can be used for a listener to indicate that it should listen on all From d395dfe3648c983655da291db53a6d6d76fc8ab0 Mon Sep 17 00:00:00 2001 From: Garrett D'Amore Date: Sun, 6 Oct 2024 19:47:27 -0700 Subject: [PATCH 036/222] Forgot to add the UDP man page! --- docs/ref/tran/udp.md | 53 +++++++++++++++++++++++++++++++------------- 1 file changed, 38 insertions(+), 15 deletions(-) diff --git a/docs/ref/tran/udp.md b/docs/ref/tran/udp.md index 5a10e2d77..ebf21248c 100644 --- a/docs/ref/tran/udp.md +++ b/docs/ref/tran/udp.md @@ -1,25 +1,17 @@ # UDP Transport (Experimental) +## Description + The {{i:_udp_ transport}} supports communication between peers using {{i:UDP}}. UDP is a very light-weight connection-less, unreliable, unordered delivery mechanism. Both IPv4 and {{i:IPv6}} are supported when the underlying platform also supports it. -## Maximum Message Size - -This transport maps each SP message to a single UDP packet. -In order to allow room for network headers, we thus limit the maximum -message size to 65000 bytes, minus the overhead for any SP protocol headers. - -However, applications are _strongly_ encouraged to only use this transport for -very much smaller messages, ideally those that will fit within a single network -packet without requiring fragmentation and reassembly. - -For Ethernet without jumbo frames, this typically means an {{i:MTU}} of a little -less than 1500 bytes. (Specifically, 1452, which allows 28 bytes for IP and UDP, -and 20 bytes for the this transport). -Other link layers may have different MTUs. +This transport adds an ordering guarantee, so that messages will always be received in +the correct order. Messages that arrive out of order, or are duplicated, will be +dropped. There may be gaps in the messages received, so applications should not assume +that all messages sent will arrive. > [!NOTE] > This transport is _experimental_. @@ -80,7 +72,37 @@ where supported by the underlying platform. - [`NNG_OPT_REMADDR`][NNG_OPT_REMADDR] - [`NNG_OPT_URL`][NNG_OPT_URL] -TOOD: Document other options. +TODO: Document other options. + +## Maximum Message Size + +This transport maps each SP message to a single UDP packet. +In order to allow room for network headers, we thus limit the maximum +message size to 65000 bytes, minus the overhead for any SP protocol headers. + +However, applications are _strongly_ encouraged to only use this transport for +very much smaller messages, ideally those that will fit within a single network +packet without requiring fragmentation and reassembly. + +For Ethernet without jumbo frames, this typically means an {{i:MTU}} of a little +less than 1500 bytes. (Specifically, 1452, which allows 28 bytes for IP and UDP, +and 20 bytes for the this transport). +Other link layers may have different MTUs. + +The maximum message size is negotiated as part of establishing a peering relationship, +and oversize messages will be dropped by the sender before going to the network. + +The maximum message size to receive can be configured with the +[`NNG_OPT_RECVMAXSZ`][NNG_OPT_RECVMAXSZ] option. + +## Keep Alive + +This transports maintains a logical "connection" with each peer, to provide a rough +facsimile of a connection based semantic. This requires some resource on each peer. +In order to ensure that resources are reclaimed when a peer vanishes unexpectedly, a +keep-alive mechanism is implemented. + +TODO: Document the tunables for this. [nng_sockaddr]: [TODO.md] [nng_sockaddr_in]: [TODO.md] @@ -88,3 +110,4 @@ TOOD: Document other options. [NNG_OPT_LOCADDR]: [TODO.md] [NNG_OPT_REMADDR]: [TODO.md] [NNG_OPT_URL]: [TODO.md] +[NNG_OPT_RECVMAXSZ]: [TODO.md] From f83197510702e3104c7cb260c2681ead00ee1908 Mon Sep 17 00:00:00 2001 From: Garrett D'Amore Date: Sun, 6 Oct 2024 19:49:02 -0700 Subject: [PATCH 037/222] Add missing description header to socket manual --- docs/ref/tran/socket.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/ref/tran/socket.md b/docs/ref/tran/socket.md index cfb31ca3e..0b7d5a457 100644 --- a/docs/ref/tran/socket.md +++ b/docs/ref/tran/socket.md @@ -1,5 +1,7 @@ # BSD Socket Transport (Experimental) +## Description + The {{i:_socket_ transport}} supports communication between peers across arbitrary BSD sockets, such as those that are created with [`nng_socket_pair()`][nng_socket_pair]. From 78a0c02dbdc298be527df126300aba9ffd0e6618 Mon Sep 17 00:00:00 2001 From: Garrett D'Amore Date: Sun, 6 Oct 2024 19:49:26 -0700 Subject: [PATCH 038/222] Convert nng_random to new format. --- docs/ref/SUMMARY.md | 4 ++++ docs/ref/api/util.md | 3 --- docs/ref/api/util/index.md | 6 ++++++ docs/ref/api/util/nng_random.md | 25 +++++++++++++++++++++++++ 4 files changed, 35 insertions(+), 3 deletions(-) delete mode 100644 docs/ref/api/util.md create mode 100644 docs/ref/api/util/nng_random.md diff --git a/docs/ref/SUMMARY.md b/docs/ref/SUMMARY.md index 72b7dd94b..9a4593833 100644 --- a/docs/ref/SUMMARY.md +++ b/docs/ref/SUMMARY.md @@ -3,11 +3,15 @@ - [API](./api.md) - [Threading Functions](./api/thr/index.md) + - [nng_mtx](./api/thr/nng_mtx.md) + - [Utility Functions](./api/util/index.md) + - [nng_clock](./api/util/nng_clock.md) - [nng_id_map](./api/util/nng_id_map.md) - [nng_msleep](./api/util/nng_msleep.md) + - [nng_random](./api/util/nng_random.md) - [Transports](./tran/index.md) diff --git a/docs/ref/api/util.md b/docs/ref/api/util.md deleted file mode 100644 index 0ea03878b..000000000 --- a/docs/ref/api/util.md +++ /dev/null @@ -1,3 +0,0 @@ -# Utility Functions - -- [nng_id_map](./util/nng_id_map.md) diff --git a/docs/ref/api/util/index.md b/docs/ref/api/util/index.md index 9f155b659..e11692c63 100644 --- a/docs/ref/api/util/index.md +++ b/docs/ref/api/util/index.md @@ -1,5 +1,11 @@ # Utility Functions +This section documents various utility functions that may help +with application portability. These are not fundamental to NNG +or Scalability Protocols, but we find them useful for a variety +of other uses. + - [nng_clock](nng_clock.md) - [nng_id_map](nng_id_map.md) - [nng_msleep](nng_msleep.md) +- [nng_random](nng_random.md) diff --git a/docs/ref/api/util/nng_random.md b/docs/ref/api/util/nng_random.md new file mode 100644 index 000000000..160752ab9 --- /dev/null +++ b/docs/ref/api/util/nng_random.md @@ -0,0 +1,25 @@ +# nng_random + +## NAME + +nng_random --- get random number + +## SYNOPSIS + +```c +#include + +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. + +## RETURN VALUES + +Returns a random 32-bit value. From cd54db08a49065739278eb6850bce5ac5d8f98ec Mon Sep 17 00:00:00 2001 From: Garrett D'Amore Date: Sun, 6 Oct 2024 21:03:48 -0700 Subject: [PATCH 039/222] nng_version converted to mdbook Signed-off-by: jaylin --- docs/man/libnng.3.adoc | 14 ++++---- docs/man/nng_random.3supp.adoc | 42 ----------------------- docs/man/nng_version.3.adoc | 58 -------------------------------- docs/ref/SUMMARY.md | 1 + docs/ref/api/util/index.md | 1 + docs/ref/api/util/nng_version.md | 36 ++++++++++++++++++++ 6 files changed, 45 insertions(+), 107 deletions(-) delete mode 100644 docs/man/nng_random.3supp.adoc delete mode 100644 docs/man/nng_version.3.adoc create mode 100644 docs/ref/api/util/nng_version.md diff --git a/docs/man/libnng.3.adoc b/docs/man/libnng.3.adoc index 7a0768458..419eaa4d1 100644 --- a/docs/man/libnng.3.adoc +++ b/docs/man/libnng.3.adoc @@ -31,12 +31,12 @@ It provides a C language API. The following common functions exist in _libnng_. |=== -|xref:nng_alloc.3.adoc[nng_alloc]|allocate memory -|xref:nng_free.3.adoc[nng_free]|free memory -|xref:nng_strdup.3.adoc[nng_strdup]|duplicate string -|xref:nng_strerror.3.adoc[nng_strerror]|return an error description -|xref:nng_strfree.3.adoc[nng_strfree]|free string -|xref:nng_version.3.adoc[nng_version]|report library version +|xref:nng_alloc.3.adoc[nng_alloc()]|allocate memory +|xref:nng_free.3.adoc[nng_free()]|free memory +|xref:nng_strdup.3.adoc[nng_strdup()]|duplicate string +|xref:nng_strerror.3.adoc[nng_strerror()]|return an error description +|xref:nng_strfree.3.adoc[nng_strfree()]|free string +// |xref:nng_version.3.adoc[nng_version()]|report library version |=== === Socket Functions @@ -291,7 +291,7 @@ as a convenience to aid in creating portable applications. // |xref:nng_mtx_lock.3supp.adoc[nng_mtx_lock()]|lock mutex // |xref:nng_mtx_unlock.3supp.adoc[nng_mtx_unlock()]|unlock mutex |xref:nng_opts_parse.3supp.adoc[nng_opts_parse()]|parse command line options -|xref:nng_random.3supp.adoc[nng_random()]|get random number +// |xref:nng_random.3supp.adoc[nng_random()]|get random number |xref:nng_socket_pair.3supp.adoc[nng_socket_pair()]|create connected pair of BSD sockets |xref:nng_thread_create.3supp.adoc[nng_thread_create()]|create thread |xref:nng_thread_destroy.3supp.adoc[nng_thread_destroy()]|reap thread diff --git a/docs/man/nng_random.3supp.adoc b/docs/man/nng_random.3supp.adoc deleted file mode 100644 index c2cd4bac5..000000000 --- a/docs/man/nng_random.3supp.adoc +++ /dev/null @@ -1,42 +0,0 @@ -= nng_random(3supp) -// -// Copyright 2024 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_random - get random number - -== SYNOPSIS - -[source, c] ----- -#include - -uint32_t nng_random(void); ----- - -== DESCRIPTION - -The `nng_random()` returns a random number. -The value is obtained using platform specific cryptographically strong random -number facilities when available. - -== RETURN VALUES - -Random number. - -== ERRORS - -None. - -== SEE ALSO - -[.text-left] -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_version.3.adoc b/docs/man/nng_version.3.adoc deleted file mode 100644 index 8859a46a1..000000000 --- a/docs/man/nng_version.3.adoc +++ /dev/null @@ -1,58 +0,0 @@ -= nng_version(3) -// -// Copyright 2020 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_version - report library version - -== SYNOPSIS - -[source, c] ----- -#include - -const char * nng_version(void); ----- - -== DESCRIPTION - -The `nng_version()` function returns a human readable ((version number)) -for _NNG_. - -Additionally, compile time version information is available -via some predefined macros: - -[horizontal] -((`NNG_MAJOR_VERSION`)):: Major version number. -((`NNG_MINOR_VERSION`)):: Minor version number. -((`NNG_PATCH_VERSION`)):: Patch version number. - -_NNG_ is developed and released using -http://www.semver.org[Semantic Versioning 2.0], and -the version numbers reported refer to both the API and the -library itself. -(The ((ABI)) -- ((application binary interface)) -- between the -library and the application is controlled in a similar, but different -manner depending upon the link options and how the library is built.) - -== RETURN VALUES - -Null-terminated string containing the library version number. - -== ERRORS - -None. - -== SEE ALSO - -[.text-left] -xref:libnng.3.adoc[libnng(3)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/ref/SUMMARY.md b/docs/ref/SUMMARY.md index 9a4593833..193b316f8 100644 --- a/docs/ref/SUMMARY.md +++ b/docs/ref/SUMMARY.md @@ -12,6 +12,7 @@ - [nng_id_map](./api/util/nng_id_map.md) - [nng_msleep](./api/util/nng_msleep.md) - [nng_random](./api/util/nng_random.md) + - [nng_version](./api/util/nng_version.md) - [Transports](./tran/index.md) diff --git a/docs/ref/api/util/index.md b/docs/ref/api/util/index.md index e11692c63..0a96da446 100644 --- a/docs/ref/api/util/index.md +++ b/docs/ref/api/util/index.md @@ -9,3 +9,4 @@ of other uses. - [nng_id_map](nng_id_map.md) - [nng_msleep](nng_msleep.md) - [nng_random](nng_random.md) +- [nng_version](nng_version.md) diff --git a/docs/ref/api/util/nng_version.md b/docs/ref/api/util/nng_version.md new file mode 100644 index 000000000..a84ed4cc3 --- /dev/null +++ b/docs/ref/api/util/nng_version.md @@ -0,0 +1,36 @@ +# nng_version + +## NAME + +nng_version --- report library version + +## SYNOPSIS + +```c +#include + +const char * nng_version(void); +``` + +## DESCRIPTION + +The `nng_version` function returns a human readable {{i:version number}} +for _NNG_. + +Additionally, compile time version information is available +via some predefined macros: + +- {{i:`NNG_MAJOR_VERSION`}}: Major version number. +- {{i:`NNG_MINOR_VERSION`}}: Minor version number. +- {{i:`NNG_PATCH_VERSION`}}: Patch version number. + +_NNG_ is developed and released using +[Semantic Versioning 2.0](http://www.semver.org), and +the version numbers reported refer to both the API and the library itself. +(The {{i:ABI}} -- {{i:application binary interface}} -- between the +library and the application is controlled in a similar, but different +manner depending upon the link options and how the library is built.) + +## RETURN VALUES + +`NUL`-terminated string containing the library version number. From fea0e852331725133bef1146497acfc6475a4781 Mon Sep 17 00:00:00 2001 From: Garrett D'Amore Date: Sun, 6 Oct 2024 21:15:31 -0700 Subject: [PATCH 040/222] Convert nng_alloc and nng_free to mdbook. --- docs/man/libnng.3.adoc | 4 +-- docs/man/nng_alloc.3.adoc | 56 ---------------------------------- docs/man/nng_free.3.adoc | 53 -------------------------------- docs/ref/SUMMARY.md | 1 + docs/ref/api/util/index.md | 1 + docs/ref/api/util/nng_alloc.md | 47 ++++++++++++++++++++++++++++ 6 files changed, 51 insertions(+), 111 deletions(-) delete mode 100644 docs/man/nng_alloc.3.adoc delete mode 100644 docs/man/nng_free.3.adoc create mode 100644 docs/ref/api/util/nng_alloc.md diff --git a/docs/man/libnng.3.adoc b/docs/man/libnng.3.adoc index 419eaa4d1..cb5da83ef 100644 --- a/docs/man/libnng.3.adoc +++ b/docs/man/libnng.3.adoc @@ -31,8 +31,8 @@ It provides a C language API. The following common functions exist in _libnng_. |=== -|xref:nng_alloc.3.adoc[nng_alloc()]|allocate memory -|xref:nng_free.3.adoc[nng_free()]|free memory +//|xref:nng_alloc.3.adoc[nng_alloc()]|allocate memory +//|xref:nng_free.3.adoc[nng_free()]|free memory |xref:nng_strdup.3.adoc[nng_strdup()]|duplicate string |xref:nng_strerror.3.adoc[nng_strerror()]|return an error description |xref:nng_strfree.3.adoc[nng_strfree()]|free string diff --git a/docs/man/nng_alloc.3.adoc b/docs/man/nng_alloc.3.adoc deleted file mode 100644 index 93c03111f..000000000 --- a/docs/man/nng_alloc.3.adoc +++ /dev/null @@ -1,56 +0,0 @@ -= nng_alloc(3) -// -// Copyright 2018 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_alloc - allocate memory - -== SYNOPSIS - -[source, c] ----- -#include - -void *nng_alloc(size_t size); ----- - -== DESCRIPTION - -The `nng_alloc()` function allocates a contiguous memory region of -at least _size_ bytes. -The memory will be 64-bit aligned. - -The returned memory can be used to hold message buffers, in which -case it can be directly passed to xref:nng_send.3.adoc[`nng_send()`] using -the flag `NNG_FLAG_ALLOC`. Alternatively, it can be freed when no -longer needed using xref:nng_free.3.adoc[`nng_free()`]. - -IMPORTANT: Do not use the system `free()` function to release this memory. -On some platforms this may work, but it is not guaranteed and may lead -to a crash or other undesirable and unpredictable behavior. - -== RETURN VALUES - -This function returns a pointer to the allocated memory on success, -and `NULL` otherwise. - -== ERRORS - -No errors are returned, but a `NULL` return value should be -treated the same as `NNG_ENOMEM`. - -== SEE ALSO - -[.text-left] -xref:nng_free.3.adoc[nng_free(3)], -xref:nng_send.3.adoc[nng_send(3)], -xref:nng_strerror.3.adoc[nng_strerror(3)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_free.3.adoc b/docs/man/nng_free.3.adoc deleted file mode 100644 index b4fdc249a..000000000 --- a/docs/man/nng_free.3.adoc +++ /dev/null @@ -1,53 +0,0 @@ -= nng_free(3) -// -// Copyright 2018 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_free - free memory - -== SYNOPSIS - -[source, c] ----- -#include - -void nng_free(void *ptr, size_t size); ----- - -== DESCRIPTION - -The `nng_free()` function deallocates a memory region of size _size_, -that was previously allocated by xref:nng_alloc.3.adoc[`nng_alloc()`] or -xref:nng_recv.3.adoc[`nng_recv()`] with the `NNG_FLAG_ALLOC` flag. - -IMPORTANT: It is very important that _size_ match the allocation size -used to allocate the memory. - -IMPORTANT: Do not attempt to use this function to deallocate memory -obtained by a call to the system `malloc()` or `calloc()` functions, -or the {cpp} `new` operator. -Doing so may result in unpredictable -behavior, including corruption of application memory. - -== RETURN VALUES - -None. - -== ERRORS - -None. - -== SEE ALSO - -[.text-left] -xref:nng_alloc.3.adoc[nng_alloc(3)], -xref:nng_recv.3.adoc[nng_recv(3)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/ref/SUMMARY.md b/docs/ref/SUMMARY.md index 193b316f8..590107948 100644 --- a/docs/ref/SUMMARY.md +++ b/docs/ref/SUMMARY.md @@ -8,6 +8,7 @@ - [Utility Functions](./api/util/index.md) + - [nng_alloc](./api/util/nng_alloc.md) - [nng_clock](./api/util/nng_clock.md) - [nng_id_map](./api/util/nng_id_map.md) - [nng_msleep](./api/util/nng_msleep.md) diff --git a/docs/ref/api/util/index.md b/docs/ref/api/util/index.md index 0a96da446..24c88d9ce 100644 --- a/docs/ref/api/util/index.md +++ b/docs/ref/api/util/index.md @@ -5,6 +5,7 @@ with application portability. These are not fundamental to NNG or Scalability Protocols, but we find them useful for a variety of other uses. +- [nng_alloc](nng_alloc.md) - [nng_clock](nng_clock.md) - [nng_id_map](nng_id_map.md) - [nng_msleep](nng_msleep.md) diff --git a/docs/ref/api/util/nng_alloc.md b/docs/ref/api/util/nng_alloc.md new file mode 100644 index 000000000..39b7bc2c9 --- /dev/null +++ b/docs/ref/api/util/nng_alloc.md @@ -0,0 +1,47 @@ +# nng_alloc + +## NAME + +nng_alloc --- allocate memory + +## SYNOPSIS + +```c +#include + +void *nng_alloc(size_t size); +void nng_free(void *ptr, size_t size); +``` + +## DESCRIPTION + +The {{i:`nng_alloc`}} function allocates a contiguous memory region of +at least _size_ bytes. +The memory will be 64-bit aligned. + +The {{i:`nng_free`}} function deallocates {{i:memory}} previously allocated by `nng_alloc`. + +Memory returned by `nng_alloc` can be used to hold message buffers, in which +case it can be directly passed to [`nng_send`][nng_send] using the flag `NNG_FLAG_ALLOC`. +Alternatively, it can be freed when no longer needed using `nng_free`. + +> [!IMPORTANT] +> Do not use the system `free` function (or the C++ `delete` operator) to release this memory. +> On some configurations this may work, but on others it will lead to a crash or +> other unpredictable behavior. + +## RETURN VALUES + +The `nng_alloc` function returns a pointer to the allocated memory on success, +and `NULL` otherwise. + +## ERRORS + +No errors are returned, but if memory cannot be allocated then `NULL` is returned. +This can reasonably be treated as if an `NNG_ENOMEM` error occurred. + +## SEE ALSO + +[nng_send][nng_send] + +[nng_send]: [TODO.md] From e2fcce3ffe18ea374e5a9526b04666efbd49414d Mon Sep 17 00:00:00 2001 From: Garrett D'Amore Date: Sun, 6 Oct 2024 21:27:54 -0700 Subject: [PATCH 041/222] Indexing improvements to mdbook docs. --- docs/ref/api/thr/nng_mtx.md | 10 +++++----- docs/ref/api/util/nng_clock.md | 7 +++---- docs/ref/api/util/nng_id_map.md | 17 ++++++++++------- docs/ref/api/util/nng_msleep.md | 2 +- docs/ref/api/util/nng_random.md | 2 +- docs/ref/api/util/nng_version.md | 2 +- docs/ref/tran/udp.md | 2 +- 7 files changed, 22 insertions(+), 20 deletions(-) diff --git a/docs/ref/api/thr/nng_mtx.md b/docs/ref/api/thr/nng_mtx.md index ecd00e225..9673ad990 100644 --- a/docs/ref/api/thr/nng_mtx.md +++ b/docs/ref/api/thr/nng_mtx.md @@ -19,21 +19,21 @@ void nng_mtx_unlock(nng_mtx *mtx); ## DESCRIPTION -The {{i:`nng_mutex`}}{{hi:mutex}} structure provides a {{i:mutual-exclusion}} {{i:lock}}, such +The {{i:`nng_mtx`}}{{hi:mutex}} structure provides a {{i:mutual-exclusion}} {{i:lock}}, such that only one thread at a time can have the lock (taken using `nng_mtx_lock`). This is critical for solving certain problems that arise in concurrent programming. ### Initialization and Teardown -The `nng_mtx` structure is created dynamically, by the application using `nng_mtx_alloc`. +The `nng_mtx` structure is created dynamically, by the application using {{i:`nng_mtx_alloc`}}. This function will store a pointer to the allocate mutex at the location signified by _mtxp_. When the application has no further need of the mutex, it can deallocate the resources -associated using the `nng_mtx_free` function. +associated using the {{i:`nng_mtx_free`}} function. ### Locking and Unlocking -The `nng_mtx` lock can be acquired by a calling thread using the `nng_mtx_lock` function. +The `nng_mtx` lock can be acquired by a calling thread using the {{i:`nng_mtx_lock`}} function. The caller will block until the lock is acquired. If multiple threads are contending for ownership of the lock, the order of @@ -45,7 +45,7 @@ acquisition is not specified, and applications must not depend on it. > It is a programming error for the owner of a mutex to attempt to > reacquire it. -The lock can be released by the thread that has ownership using the `nng_mtx_unlock` function. +The lock can be released by the thread that has ownership using the {{i:`nng_mtx_unlock`}} function. > [!NOTE] > A mutex can _only_ be unlocked by the thread that locked it. diff --git a/docs/ref/api/util/nng_clock.md b/docs/ref/api/util/nng_clock.md index f4e9f9d54..fcd5af1b4 100644 --- a/docs/ref/api/util/nng_clock.md +++ b/docs/ref/api/util/nng_clock.md @@ -16,10 +16,9 @@ nng_time nng_clock(void); ## DESCRIPTION -The `nng_clock` function returns the number of elapsed milliseconds since some -arbitrary time in the past. -The resolution of the clock depends on the underlying timing facilities -of the system. +The {{i:`nng_clock`}}{{hi:clock}} function returns the number of elapsed +milliseconds since some arbitrary time in the past. +The resolution of the clock depends on the underlying timing facilities of the system. This function may be used for timing, but applications should not expect very fine-grained values. diff --git a/docs/ref/api/util/nng_id_map.md b/docs/ref/api/util/nng_id_map.md index 016c60e4d..1a516e444 100644 --- a/docs/ref/api/util/nng_id_map.md +++ b/docs/ref/api/util/nng_id_map.md @@ -45,9 +45,12 @@ Given a sufficiently large range, this is unlikely to be a concern.}} > These functions are _not_ thread-safe. > Callers should use a [mutex][mutex] or similar approach when thread-safety is needed. +The {{i:`nng_id_map_free`}} function deallocates one of these tables, and should be called +when it is no longer neeeded. + ### Initialization -An initial table is allocated with `nng_id_map_alloc`, which takes the lowest legal identifier in _lo_, +An initial table is allocated with {{i:`nng_id_map_alloc`}}, which takes the lowest legal identifier in _lo_, and the largest legal identifier in _hi_. The new table is returned in _map_p_, and should be used as the _map_ argument to the rest of these functions. @@ -58,27 +61,27 @@ then both _lo_ and _hi_ must be specified with the exact values desired. themselves be larger than this.}} The _flags_ argument is a bit mask of flags for the table. -If `NNG_MAP_RANDOM` is specified, then the starting point for allocations is randomized, but subsequent allocations will then be monotonically increasing. +If {{i:`NNG_MAP_RANDOM`}} is specified, then the starting point for allocations is randomized, but subsequent allocations will then be monotonically increasing. This is useful to reduce the odds of different instances of an application using the same identifiers at the same time. ### Accessors -The `nng_id_get` function returns the value previously stored with the given identifier. +The {{i:`nng_id_get`}} function returns the value previously stored with the given identifier. If no value is currently associated with the identifer, it returns `NULL`. -The `nng_id_set` function sets the value with the associated identifier. +The {{i:`nng_id_set`}} function sets the value with the associated identifier. This can be used to replace a previously allocated identifier. If the identifier was not previously allocated, then it is allocated as part of the call. This function does not necessarily honor the identifier range limits set for the map when it was allocated. -The `nng_id_alloc` function allocates a new identifier from the range for the map, and associates it with +The {{:`nng_id_alloc`}} function allocates a new identifier from the range for the map, and associates it with the supplied _value_. -The `nng_id_remove` function removes the identifier and its associated value from the table. +The {{:`nng_id_remove`}} function removes the identifier and its associated value from the table. ### Iteration -The `nng_id_visit` function is used to iterate over all items in the table. +The {{i:`nng_id_visit`}} function is used to iterate over all items in the table. The caller starts the iteration by setting the _cursor_ to 0 before calling it. For each call, the associated key and value of the next item will be returned in _id_p_, and _value_p_ and the _cursor_ will be updated. diff --git a/docs/ref/api/util/nng_msleep.md b/docs/ref/api/util/nng_msleep.md index d9e49e499..e055b2f97 100644 --- a/docs/ref/api/util/nng_msleep.md +++ b/docs/ref/api/util/nng_msleep.md @@ -16,7 +16,7 @@ void nng_msleep(nng_duration msec); ## DESCRIPTION -The `nng_msleep` blocks the caller for at least _msec_ milliseconds. +The {{i:`nng_msleep`}}{{hi:sleep}} blocks the caller for at least _msec_ milliseconds. > [!NOTE] > This function may block for longer than requested. diff --git a/docs/ref/api/util/nng_random.md b/docs/ref/api/util/nng_random.md index 160752ab9..b8a89d0e9 100644 --- a/docs/ref/api/util/nng_random.md +++ b/docs/ref/api/util/nng_random.md @@ -14,7 +14,7 @@ uint32_t nng_random(void); ## DESCRIPTION -The `nng_random` returns a random number. +The {{i:`nng_random`}} returns a {{i: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 diff --git a/docs/ref/api/util/nng_version.md b/docs/ref/api/util/nng_version.md index a84ed4cc3..04a1dd1ba 100644 --- a/docs/ref/api/util/nng_version.md +++ b/docs/ref/api/util/nng_version.md @@ -14,7 +14,7 @@ const char * nng_version(void); ## DESCRIPTION -The `nng_version` function returns a human readable {{i:version number}} +The {{i:`nng_version`}} function returns a human readable {{i:version number}} for _NNG_. Additionally, compile time version information is available diff --git a/docs/ref/tran/udp.md b/docs/ref/tran/udp.md index ebf21248c..7c389028f 100644 --- a/docs/ref/tran/udp.md +++ b/docs/ref/tran/udp.md @@ -6,7 +6,7 @@ The {{i:_udp_ transport}} supports communication between peers using {{i:UDP}}. UDP is a very light-weight connection-less, unreliable, unordered delivery mechanism. -Both IPv4 and {{i:IPv6}} are supported when the underlying platform also supports it. +Both {{i:IPv4}} and {{i:IPv6}} are supported when the underlying platform also supports it. This transport adds an ordering guarantee, so that messages will always be received in the correct order. Messages that arrive out of order, or are duplicated, will be From 8da27fba09d5bfc12ccd358d573665ce38def211 Mon Sep 17 00:00:00 2001 From: Garrett D'Amore Date: Sun, 6 Oct 2024 21:36:50 -0700 Subject: [PATCH 042/222] Minor markup fix for some mdbook pages. --- docs/ref/api/thr/nng_mtx.md | 2 +- docs/ref/api/util/nng_clock.md | 2 +- docs/ref/api/util/nng_id_map.md | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/ref/api/thr/nng_mtx.md b/docs/ref/api/thr/nng_mtx.md index 9673ad990..37249e4f8 100644 --- a/docs/ref/api/thr/nng_mtx.md +++ b/docs/ref/api/thr/nng_mtx.md @@ -2,7 +2,7 @@ ## NAME -nng_mutex - mutual exclusion lock +nng_mutex --- mutual exclusion lock ## SYNOPSIS diff --git a/docs/ref/api/util/nng_clock.md b/docs/ref/api/util/nng_clock.md index fcd5af1b4..ca6d1c6e7 100644 --- a/docs/ref/api/util/nng_clock.md +++ b/docs/ref/api/util/nng_clock.md @@ -2,7 +2,7 @@ ## NAME -nng_clock - get time +nng_clock --- get time ## SYNOPSIS diff --git a/docs/ref/api/util/nng_id_map.md b/docs/ref/api/util/nng_id_map.md index 1a516e444..a7057ba03 100644 --- a/docs/ref/api/util/nng_id_map.md +++ b/docs/ref/api/util/nng_id_map.md @@ -2,7 +2,7 @@ ## NAME -nng_id_map - identifier based mapping table +nng_id_map --- identifier based mapping table ## SYNOPSIS From babc82449694d70662755eb61ef66dc1d4a8b22b Mon Sep 17 00:00:00 2001 From: Garrett D'Amore Date: Sun, 6 Oct 2024 21:38:24 -0700 Subject: [PATCH 043/222] Convert nng_strerror to mdbook. --- docs/man/libnng.3.adoc | 2 +- docs/man/nng_strerror.3.adoc | 48 ------------------------------- docs/ref/SUMMARY.md | 1 + docs/ref/api/util/index.md | 1 + docs/ref/api/util/nng_strerror.md | 33 +++++++++++++++++++++ 5 files changed, 36 insertions(+), 49 deletions(-) delete mode 100644 docs/man/nng_strerror.3.adoc create mode 100644 docs/ref/api/util/nng_strerror.md diff --git a/docs/man/libnng.3.adoc b/docs/man/libnng.3.adoc index cb5da83ef..4d2cc5bb1 100644 --- a/docs/man/libnng.3.adoc +++ b/docs/man/libnng.3.adoc @@ -34,7 +34,7 @@ The following common functions exist in _libnng_. //|xref:nng_alloc.3.adoc[nng_alloc()]|allocate memory //|xref:nng_free.3.adoc[nng_free()]|free memory |xref:nng_strdup.3.adoc[nng_strdup()]|duplicate string -|xref:nng_strerror.3.adoc[nng_strerror()]|return an error description +//|xref:nng_strerror.3.adoc[nng_strerror()]|return an error description |xref:nng_strfree.3.adoc[nng_strfree()]|free string // |xref:nng_version.3.adoc[nng_version()]|report library version |=== diff --git a/docs/man/nng_strerror.3.adoc b/docs/man/nng_strerror.3.adoc deleted file mode 100644 index 145fd0bc3..000000000 --- a/docs/man/nng_strerror.3.adoc +++ /dev/null @@ -1,48 +0,0 @@ -= nng_strerror(3) -// -// Copyright 2018 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_strerror - return an error description - -== SYNOPSIS - -[source, c] ----- -#include - -const char * nng_strerror(int err); ----- - -== DESCRIPTION - -The `nng_strerror()` returns the human-readable description of the -given error in `err`. - -NOTE: The returned error message is provided in US English, but in the -future locale-specific strings may be presented instead. - -NOTE: The specific strings associated with specific error messages are -subject to change. -Therefore applications must not depend on the message, -but may use them verbatim when supplying information to end-users, such -as in diagnostic messages or log entries. - -== RETURN VALUES - -This function returns the human-readable error message, terminated -by a `NUL` byte. - -== SEE ALSO - -[.text-left] -xref:libnng.3.adoc[libnng(3)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/ref/SUMMARY.md b/docs/ref/SUMMARY.md index 590107948..58e596953 100644 --- a/docs/ref/SUMMARY.md +++ b/docs/ref/SUMMARY.md @@ -13,6 +13,7 @@ - [nng_id_map](./api/util/nng_id_map.md) - [nng_msleep](./api/util/nng_msleep.md) - [nng_random](./api/util/nng_random.md) + - [nng_strerror](./api/util/nng_strerror.md) - [nng_version](./api/util/nng_version.md) - [Transports](./tran/index.md) diff --git a/docs/ref/api/util/index.md b/docs/ref/api/util/index.md index 24c88d9ce..eeb139064 100644 --- a/docs/ref/api/util/index.md +++ b/docs/ref/api/util/index.md @@ -10,4 +10,5 @@ of other uses. - [nng_id_map](nng_id_map.md) - [nng_msleep](nng_msleep.md) - [nng_random](nng_random.md) +- [nng_strerror](nng_strerror.md) - [nng_version](nng_version.md) diff --git a/docs/ref/api/util/nng_strerror.md b/docs/ref/api/util/nng_strerror.md new file mode 100644 index 000000000..82d2f8406 --- /dev/null +++ b/docs/ref/api/util/nng_strerror.md @@ -0,0 +1,33 @@ +# nng_strerror + +## NAME + +nng_strerror --- return an error description + +## SYNOPSIS + +```c +#include + +const char *nng_strerror(int err); +``` + +## DESCRIPTION + +The `nng_strerror` returns the human-readable description of the +given error in `err`. + +The returned error message is provided in US English, but in the +future locale-specific strings may be presented instead. + +> [!NOTE] +> The specific strings associated with specific error messages are +> subject to change. +> Therefore applications must not depend on the message, +> but may use them verbatim when supplying information to end-users, such +> as in diagnostic messages or log entries. + +## RETURN VALUES + +This function returns the human-readable error message, terminated +by a `NUL` byte. From 40aaa985f9a4a5574416d4ed9de661c88a123793 Mon Sep 17 00:00:00 2001 From: Garrett D'Amore Date: Sun, 6 Oct 2024 21:39:58 -0700 Subject: [PATCH 044/222] Minor indexing markup fix --- docs/ref/api/util/nng_id_map.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/ref/api/util/nng_id_map.md b/docs/ref/api/util/nng_id_map.md index a7057ba03..0fbf64272 100644 --- a/docs/ref/api/util/nng_id_map.md +++ b/docs/ref/api/util/nng_id_map.md @@ -74,10 +74,10 @@ This can be used to replace a previously allocated identifier. If the identifier was not previously allocated, then it is allocated as part of the call. This function does not necessarily honor the identifier range limits set for the map when it was allocated. -The {{:`nng_id_alloc`}} function allocates a new identifier from the range for the map, and associates it with +The {{i:`nng_id_alloc`}} function allocates a new identifier from the range for the map, and associates it with the supplied _value_. -The {{:`nng_id_remove`}} function removes the identifier and its associated value from the table. +The {{i:`nng_id_remove`}} function removes the identifier and its associated value from the table. ### Iteration From fb3414eb0677940f6011da98623eca5d4dfa862e Mon Sep 17 00:00:00 2001 From: Garrett D'Amore Date: Sun, 6 Oct 2024 21:52:44 -0700 Subject: [PATCH 045/222] Fix indexing for nng_strerror.md. --- docs/ref/api/util/nng_strerror.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/ref/api/util/nng_strerror.md b/docs/ref/api/util/nng_strerror.md index 82d2f8406..a48f9f54e 100644 --- a/docs/ref/api/util/nng_strerror.md +++ b/docs/ref/api/util/nng_strerror.md @@ -14,10 +14,10 @@ const char *nng_strerror(int err); ## DESCRIPTION -The `nng_strerror` returns the human-readable description of the +The {{i:`nng_strerror`}} returns the human-readable description of the given error in `err`. -The returned error message is provided in US English, but in the +The returned {{i:error message}} is provided in US English, but in the future locale-specific strings may be presented instead. > [!NOTE] From 014ba417d73248f65d4d0b53ba19d12b5cde7b4d Mon Sep 17 00:00:00 2001 From: Garrett D'Amore Date: Sun, 6 Oct 2024 21:53:19 -0700 Subject: [PATCH 046/222] Converted nng_strdup and nng_strfree to mdbook. --- docs/man/libnng.3.adoc | 13 +++++--- docs/man/nng_strdup.3.adoc | 56 ------------------------------- docs/man/nng_strfree.3.adoc | 58 --------------------------------- docs/ref/SUMMARY.md | 1 + docs/ref/api/util/index.md | 1 + docs/ref/api/util/nng_strdup.md | 54 ++++++++++++++++++++++++++++++ 6 files changed, 64 insertions(+), 119 deletions(-) delete mode 100644 docs/man/nng_strdup.3.adoc delete mode 100644 docs/man/nng_strfree.3.adoc create mode 100644 docs/ref/api/util/nng_strdup.md diff --git a/docs/man/libnng.3.adoc b/docs/man/libnng.3.adoc index 4d2cc5bb1..96b2a1387 100644 --- a/docs/man/libnng.3.adoc +++ b/docs/man/libnng.3.adoc @@ -26,19 +26,22 @@ intended to solve common communication problems in distributed applications. It provides a C language API. + + === Socket Functions The following functions operate on sockets. diff --git a/docs/man/nng_strdup.3.adoc b/docs/man/nng_strdup.3.adoc deleted file mode 100644 index 91c4854dd..000000000 --- a/docs/man/nng_strdup.3.adoc +++ /dev/null @@ -1,56 +0,0 @@ -= nng_strdup(3) -// -// Copyright 2018 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_strdup - duplicate string - -== SYNOPSIS - -[source, c] ----- -#include - -char *nng_strdup(const char *src); ----- - -== DESCRIPTION - -The `nng_strdup()` duplicates the string _src_ and returns it. - -This is logically equivalent to using xref:nng_alloc.3.adoc[`nng_alloc()`] -to allocate a region of memory of `strlen(s) + 1` bytes, and then -using `strcpy()` to copy the string into the destination before -returning it. - -The returned string should be deallocated with -xref:nng_strfree.3.adoc[`nng_strfree()`], or may be deallocated using the -xref:nng_free.3.adoc[`nng_free()`] using the length of the returned string plus -one (for the `NUL` terminating byte). - -IMPORTANT: Do not use the system `free()` or similar functions to deallocate -the string, since those may use a different memory arena! - -== RETURN VALUES - -This function returns the new string on success, and `NULL` on failure. - -== ERRORS - -No errors are returned, but a `NULL` return value should be -treated the same as `NNG_ENOMEM`. - -== SEE ALSO - -[.text-left] -xref:nng_alloc.3.adoc[nng_alloc(3)], -xref:nng_free.3.adoc[nng_free(3)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_strfree.3.adoc b/docs/man/nng_strfree.3.adoc deleted file mode 100644 index 9250b834e..000000000 --- a/docs/man/nng_strfree.3.adoc +++ /dev/null @@ -1,58 +0,0 @@ -= nng_strfree(3) -// -// Copyright 2018 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_strfree - free memory - -== SYNOPSIS - -[source, c] ----- -#include - -void nng_strfree(char *str); ----- - -== DESCRIPTION - -The `nng_strfree()` function deallocates the string _str_. -This is equivalent to using xref:nng_free.3.adoc[`nng_free()`] with -the length of _str_ plus one (for the `NUL` terminating byte) as -the size. - -IMPORTANT: This should only be used with strings that were allocated -by xref:nng_strdup.3.adoc[`nng_strdup()`] or -xref:nng_alloc.3.adoc[`nng_alloc()`]. -In all cases, the allocation size of the string must be the same -as `strlen(__str__) + 1`. - -IMPORTANT: Consequently, if the a string created with -xref:nng_strdup.3.adoc[`nng_strdup()`] is modified to be shorter, then -it is incorrect to call this function. -(The xref:nng_free.3.adoc[`nng_free()`] function can be used instead in that -case, using the length of the original string plus one for the size.) - -== RETURN VALUES - -None. - -== ERRORS - -None. - -== SEE ALSO - -[.text-left] -xref:nng_alloc.3.adoc[nng_alloc(3)], -xref:nng_free.3.adoc[nng_free(3)], -xref:nng_strdup.3.adoc[nng_strdup(3)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/ref/SUMMARY.md b/docs/ref/SUMMARY.md index 58e596953..ac627ee48 100644 --- a/docs/ref/SUMMARY.md +++ b/docs/ref/SUMMARY.md @@ -13,6 +13,7 @@ - [nng_id_map](./api/util/nng_id_map.md) - [nng_msleep](./api/util/nng_msleep.md) - [nng_random](./api/util/nng_random.md) + - [nng_strdup](./api/util/nng_strdup.md) - [nng_strerror](./api/util/nng_strerror.md) - [nng_version](./api/util/nng_version.md) diff --git a/docs/ref/api/util/index.md b/docs/ref/api/util/index.md index eeb139064..1f202c0f5 100644 --- a/docs/ref/api/util/index.md +++ b/docs/ref/api/util/index.md @@ -10,5 +10,6 @@ of other uses. - [nng_id_map](nng_id_map.md) - [nng_msleep](nng_msleep.md) - [nng_random](nng_random.md) +- [nng_strdup](nng_strdup.md) - [nng_strerror](nng_strerror.md) - [nng_version](nng_version.md) diff --git a/docs/ref/api/util/nng_strdup.md b/docs/ref/api/util/nng_strdup.md new file mode 100644 index 000000000..32d3fba2b --- /dev/null +++ b/docs/ref/api/util/nng_strdup.md @@ -0,0 +1,54 @@ +# nng_strdup + +## NAME + +nng_strdup --- duplicate string + +## SYNOPSIS + +```c +#include + +char *nng_strdup(const char *src); +void nng_strfree(char *str); +``` + +## DESCRIPTION + +The {{i:`nng_strdup`}} duplicates the string _src_ and returns it. + +This is logically equivalent to using [`nng_alloc`][nng_alloc] +to allocate a region of memory of `strlen(s) + 1` bytes, and then +using `strcpy` to copy the string into the destination before +returning it. + +The returned string should be deallocated with +{{i:`nng_strfree`}}, or may be deallocated using the +[`nng_free`][nng_free] using the length of the returned string plus +one (for the `NUL` terminating byte). + +> [!IMPORTANT] +> Do not use the system `free` or similar functions to deallocate +> the string, since those may use a different memory arena! + +> [!IMPORTANT] +> If a string created with +> `nng_strdup` is modified to be shorter, then it is incorrect to free it with `nng_strfree`. +> (The [`nng_free`][nng_free] function can be used instead in that +> case, using the length of the original string plus one to account for the `NUL` byte, for the size.) + +## RETURN VALUES + +The `nng_strdup` function returns the new string on success, and `NULL` on failure. + +## ERRORS + +No errors are returned from `nng_strdup`, but a `NULL` return value should be +treated the same as `NNG_ENOMEM`. + +## SEE ALSO + +[nng_alloc][nng_alloc] + +[nng_alloc]: ../util/nng_alloc.md +[nng_free]: ../util/nng_alloc.md From 0481a77fcd1afd20bc71d784d9e5e08c64f60960 Mon Sep 17 00:00:00 2001 From: Garrett D'Amore Date: Sun, 6 Oct 2024 22:23:26 -0700 Subject: [PATCH 047/222] Bump checkout action to v4. --- .github/workflows/coverage.yml | 41 +++++++++++++++++----------------- .github/workflows/darwin.yml | 2 +- .github/workflows/linux.yml | 27 +++++++++++----------- .github/workflows/windows.yml | 2 +- 4 files changed, 35 insertions(+), 37 deletions(-) diff --git a/.github/workflows/coverage.yml b/.github/workflows/coverage.yml index 4350ae5d1..d504d1fb1 100644 --- a/.github/workflows/coverage.yml +++ b/.github/workflows/coverage.yml @@ -1,38 +1,37 @@ name: coverage on: [push] jobs: - linux-coverage: name: linux - runs-on: [ ubuntu-latest ] + runs-on: [ubuntu-latest] steps: - - name: Check out code - uses: actions/checkout@v1 + - name: Check out code + uses: actions/checkout@v4 - - name: Install mbedTLS - run: sudo apt-get install libmbedtls-dev + - name: Install mbedTLS + run: sudo apt-get install libmbedtls-dev - - name: Install ninja - run: sudo apt-get install ninja-build + - name: Install ninja + run: sudo apt-get install ninja-build - - name: Configure - run: mkdir build && cd build && cmake -G Ninja -DCMAKE_BUILD_TYPE=Debug -DNNG_ENABLE_COVERAGE=ON -DNNG_ENABLE_TLS=ON .. + - name: Configure + run: mkdir build && cd build && cmake -G Ninja -DCMAKE_BUILD_TYPE=Debug -DNNG_ENABLE_COVERAGE=ON -DNNG_ENABLE_TLS=ON .. - - name: build - run: cd build && ninja + - name: build + run: cd build && ninja - - name: Test - run: cd build && ctest --output-on-failure + - name: Test + run: cd build && ctest --output-on-failure - - name: Upload report - uses: codecov/codecov-action@v1 - with: - token: ${{ secrets.CODECOV_TOKEN }} - yml: ./.codecov.yml + - name: Upload report + uses: codecov/codecov-action@v1 + with: + token: ${{ secrets.CODECOV_TOKEN }} + yml: ./.codecov.yml darwin-coverage: name: darwin - runs-on: [ macos-latest ] + runs-on: [macos-latest] steps: - name: Check out code uses: actions/checkout@v1 @@ -44,7 +43,7 @@ jobs: run: brew install ninja - name: Configure - run: mkdir build && cd build && cmake -G Ninja -DCMAKE_BUILD_TYPE=Debug -DNNG_ENABLE_COVERAGE=ON -DNNG_ENABLE_TLS=ON .. + run: mkdir build && cd build && cmake -G Ninja -DCMAKE_BUILD_TYPE=Debug -DNNG_ENABLE_COVERAGE=ON -DNNG_ENABLE_TLS=ON .. - name: build run: cd build && ninja diff --git a/.github/workflows/darwin.yml b/.github/workflows/darwin.yml index 5029198e8..cc683c0a0 100644 --- a/.github/workflows/darwin.yml +++ b/.github/workflows/darwin.yml @@ -6,7 +6,7 @@ jobs: runs-on: [macos-latest] steps: - name: Check out code - uses: actions/checkout@v1 + uses: actions/checkout@v4 - name: Install Mbed TLS run: brew install mbedtls diff --git a/.github/workflows/linux.yml b/.github/workflows/linux.yml index d7386fd9e..c40b65f71 100644 --- a/.github/workflows/linux.yml +++ b/.github/workflows/linux.yml @@ -1,25 +1,24 @@ name: linux on: [push, pull_request] jobs: - build: name: build - runs-on: [ ubuntu-latest ] + runs-on: [ubuntu-latest] steps: - - name: Check out code - uses: actions/checkout@v1 + - name: Check out code + uses: actions/checkout@v4 - - name: Install mbedTLS - run: sudo apt-get install libmbedtls-dev + - name: Install mbedTLS + run: sudo apt-get install libmbedtls-dev - - name: Install ninja - run: sudo apt-get install ninja-build + - name: Install ninja + run: sudo apt-get install ninja-build - - name: Configure - run: mkdir build && cd build && cmake -G Ninja -D NNG_ENABLE_TLS=ON .. + - name: Configure + run: mkdir build && cd build && cmake -G Ninja -D NNG_ENABLE_TLS=ON .. - - name: Build - run: cd build && ninja + - name: Build + run: cd build && ninja - - name: Test - run: cd build && ctest --output-on-failure \ No newline at end of file + - name: Test + run: cd build && ctest --output-on-failure diff --git a/.github/workflows/windows.yml b/.github/workflows/windows.yml index 2a031b2bd..9f9791f28 100644 --- a/.github/workflows/windows.yml +++ b/.github/workflows/windows.yml @@ -6,7 +6,7 @@ jobs: runs-on: [windows-latest] steps: - name: Check out code - uses: actions/checkout@v1 + uses: actions/checkout@v4 - name: vcpkg build id: vcpkg From 8a743fa66b59d0eefce0c2f76641b8556cf55cc7 Mon Sep 17 00:00:00 2001 From: Garrett D'Amore Date: Sun, 6 Oct 2024 22:33:45 -0700 Subject: [PATCH 048/222] Actually enable UDP. Also fix some UWYI includes. Signed-off-by: jaylin --- src/core/defs.h | 6 ++++-- src/core/taskq.h | 5 +++-- src/sp/transport/CMakeLists.txt | 3 ++- 3 files changed, 9 insertions(+), 5 deletions(-) diff --git a/src/core/defs.h b/src/core/defs.h index 8adb06c6c..ebf6563af 100644 --- a/src/core/defs.h +++ b/src/core/defs.h @@ -11,8 +11,10 @@ #ifndef CORE_DEFS_H #define CORE_DEFS_H -#include #include +#include + +#include // C compilers may get unhappy when named arguments are not used. While // there are things like __attribute__((unused)) which are arguably @@ -24,7 +26,7 @@ if (!(x)) \ nni_panic("%s: %d: assert err: %s", __FILE__, __LINE__, #x) #else -#define NNI_ASSERT(x) ((void)(0)) +#define NNI_ASSERT(x) ((void) (0)) #endif // Returns the size of an array in elements. (Convenience.) diff --git a/src/core/taskq.h b/src/core/taskq.h index b439dae4f..ccc54f61a 100644 --- a/src/core/taskq.h +++ b/src/core/taskq.h @@ -13,6 +13,7 @@ #include "core/defs.h" #include "core/list.h" +#include "core/platform.h" typedef struct nni_taskq nni_taskq; typedef struct nni_task nni_task; @@ -67,9 +68,9 @@ extern void nni_taskq_sys_fini(void); // consuming structures. struct nni_task { nni_list_node task_node; - void * task_arg; + void *task_arg; nni_cb task_cb; - nni_taskq * task_tq; + nni_taskq *task_tq; unsigned task_busy; bool task_prep; nni_mtx task_mtx; diff --git a/src/sp/transport/CMakeLists.txt b/src/sp/transport/CMakeLists.txt index 3d91f6352..224df1dfc 100644 --- a/src/sp/transport/CMakeLists.txt +++ b/src/sp/transport/CMakeLists.txt @@ -1,5 +1,5 @@ # -# Copyright 2023 Staysail Systems, Inc. +# Copyright 2024 Staysail Systems, Inc. # # This software is supplied under the terms of the MIT License, a # copy of which should be located in the distribution where this @@ -15,6 +15,7 @@ add_subdirectory(inproc) add_subdirectory(ipc) add_subdirectory(tcp) add_subdirectory(tls) +add_subdirectory(udp) add_subdirectory(ws) add_subdirectory(mqtts) add_subdirectory(zerotier) From 18566a33483c4601a899b37666a5ca603f3be42b Mon Sep 17 00:00:00 2001 From: Garrett D'Amore Date: Sun, 6 Oct 2024 22:59:29 -0700 Subject: [PATCH 049/222] Bump codecov to v4 --- .github/workflows/coverage.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/coverage.yml b/.github/workflows/coverage.yml index d504d1fb1..d37da7556 100644 --- a/.github/workflows/coverage.yml +++ b/.github/workflows/coverage.yml @@ -24,7 +24,7 @@ jobs: run: cd build && ctest --output-on-failure - name: Upload report - uses: codecov/codecov-action@v1 + uses: codecov/codecov-action@v4 with: token: ${{ secrets.CODECOV_TOKEN }} yml: ./.codecov.yml From 4d77845d4ab857284f30242cd385c9ae0f6e4ca0 Mon Sep 17 00:00:00 2001 From: Garrett D'Amore Date: Mon, 7 Oct 2024 00:14:23 -0700 Subject: [PATCH 050/222] Fix case for infinite sleep. If one tries to sleep indefinitely, a sign bug leads to constantly waking calls, which causes an infinite cycle in the expire loop. --- src/core/aio.c | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/src/core/aio.c b/src/core/aio.c index 10508b19e..425146098 100644 --- a/src/core/aio.c +++ b/src/core/aio.c @@ -754,12 +754,13 @@ nni_sleep_aio(nng_duration ms, nng_aio *aio) default: // If the timeout on the aio is shorter than our sleep time, // then let it still wake up early, but with NNG_ETIMEDOUT. - if (ms > aio->a_timeout) { + if ((ms == NNG_DURATION_INFINITE) || (ms > aio->a_timeout)) { aio->a_expire_ok = false; ms = aio->a_timeout; } } - aio->a_expire = nni_clock() + ms; + aio->a_expire = + ms == NNG_DURATION_INFINITE ? NNI_TIME_NEVER : nni_clock() + ms; if ((rv = nni_aio_schedule(aio, nni_sleep_cancel, NULL)) != 0) { nni_aio_finish_error(aio, rv); From d054d74b1aaa34366185882a5daa5f4f25b363c4 Mon Sep 17 00:00:00 2001 From: Garrett D'Amore Date: Mon, 7 Oct 2024 00:16:00 -0700 Subject: [PATCH 051/222] Finally, actually register the UDP transport. --- src/sp/transport.c | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/src/sp/transport.c b/src/sp/transport.c index 6612c619e..6beeac17d 100644 --- a/src/sp/transport.c +++ b/src/sp/transport.c @@ -67,6 +67,9 @@ extern void nni_nmq_broker_tls_register(); #ifdef NNG_TRANSPORT_TLS extern void nni_sp_tls_register(void); #endif +#ifdef NNG_TRANSPORT_UDP +extern void nni_sp_udp_register(void); +#endif #ifdef NNG_TRANSPORT_WS extern void nni_sp_ws_register(void); #ifdef NNG_TRANSPORT_MQTT_BROKER_WS @@ -108,6 +111,9 @@ nni_sp_tran_sys_init(void) #ifdef NNG_TRANSPORT_TLS nni_sp_tls_register(); #endif +#ifdef NNG_TRANSPORT_UDP + nni_sp_udp_register(); +#endif #ifdef NNG_TRANSPORT_WS nni_sp_ws_register(); #ifdef NNG_TRANSPORT_MQTT_BROKER_WS From 6e0916cdd84472ed1ee7e7107aed05812a818e0b Mon Sep 17 00:00:00 2001 From: Garrett D'Amore Date: Mon, 7 Oct 2024 00:30:24 -0700 Subject: [PATCH 052/222] Missed another instance of codecov-action@v1 --- .github/workflows/coverage.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/coverage.yml b/.github/workflows/coverage.yml index d37da7556..b886a0f59 100644 --- a/.github/workflows/coverage.yml +++ b/.github/workflows/coverage.yml @@ -52,7 +52,7 @@ jobs: run: cd build && ctest --output-on-failure - name: Upload report - uses: codecov/codecov-action@v1 + uses: codecov/codecov-action@v4 with: token: ${{ secrets.CODECOV_TOKEN }} yml: ./.codecov.yml From 0989569952ea9a434a08416338d5822a029cfac3 Mon Sep 17 00:00:00 2001 From: Garrett D'Amore Date: Mon, 7 Oct 2024 00:38:00 -0700 Subject: [PATCH 053/222] Missed config option for UDP --- cmake/NNGOptions.cmake | 3 +++ 1 file changed, 3 insertions(+) diff --git a/cmake/NNGOptions.cmake b/cmake/NNGOptions.cmake index b1917b343..e0bd1763b 100644 --- a/cmake/NNGOptions.cmake +++ b/cmake/NNGOptions.cmake @@ -210,6 +210,9 @@ mark_as_advanced(NNG_TRANSPORT_WSS) option (NNG_TRANSPORT_FDC "Enable File Descriptor transport (EXPERIMENTAL)" ON) mark_as_advanced(NNG_TRANSPORT_FDC) +option (NNG_TRANSPORT_UDP "Enable UDP transport (EXPERIMENTAL)" ON) +mark_as_advanced(NNG_TRANSPORT_UDP) + # ZeroTier option (NNG_TRANSPORT_ZEROTIER "Enable ZeroTier transport (requires libzerotiercore)." OFF) mark_as_advanced(NNG_TRANSPORT_ZEROTIER) From f3763808dd39103a42ebf863ce03ea727a1ea995 Mon Sep 17 00:00:00 2001 From: Garrett D'Amore Date: Mon, 7 Oct 2024 00:52:42 -0700 Subject: [PATCH 054/222] udp: fix leaks on EP destroy --- src/sp/transport/udp/udp.c | 25 ++++++++++++++++--------- 1 file changed, 16 insertions(+), 9 deletions(-) diff --git a/src/sp/transport/udp/udp.c b/src/sp/transport/udp/udp.c index 4555c7493..8bf5a4d9f 100644 --- a/src/sp/transport/udp/udp.c +++ b/src/sp/transport/udp/udp.c @@ -9,6 +9,7 @@ #include "core/aio.h" #include "core/defs.h" #include "core/idhash.h" +#include "core/message.h" #include "core/nng_impl.h" #include "core/options.h" #include "core/platform.h" @@ -319,6 +320,7 @@ udp_pipe_destroy(udp_pipe *p) nni_lmq_get(&p->rx_mq, &m); nni_msg_free(m); } + nni_lmq_fini(&p->rx_mq); NNI_ASSERT(nni_list_empty(&p->rx_aios)); NNI_FREE_STRUCT(p); @@ -1119,6 +1121,12 @@ udp_ep_rele(udp_ep *ep) nni_aio_fini(&ep->resaio); nni_aio_fini(&ep->tx_aio); nni_aio_fini(&ep->rx_aio); + + for (int i = 0; i < ep->tx_ring.size; i++) { + nni_msg_free(ep->tx_ring.descs[i].payload); + ep->tx_ring.descs[i].payload = NULL; + } + nni_msg_free(ep->rx_payload); // safe even if msg is null nni_id_map_fini(&ep->pipes); NNI_FREE_STRUCTS(ep->tx_ring.descs, ep->tx_ring.size); NNI_FREE_STRUCT(ep); @@ -1276,7 +1284,7 @@ udp_ep_init(udp_ep **epp, nng_url *url, nni_sock *sock) ep->af = NNG_AF_INET; } else if (strcmp(url->u_scheme, "udp6") == 0) { ep->af = NNG_AF_INET6; - } else { + } else { NNI_FREE_STRUCT(ep); return (NNG_EADDRINVAL); } @@ -1370,22 +1378,21 @@ udp_dialer_init(void **dp, nng_url *url, nni_dialer *ndialer) static int udp_listener_init(void **lp, nng_url *url, nni_listener *nlistener) { - udp_ep *ep; - int rv; - nni_sock *sock = nni_listener_sock(nlistener); + udp_ep *ep; + int rv; + nni_sock *sock = nni_listener_sock(nlistener); + nng_sockaddr sa; // Check for invalid URL components. - if ((rv = udp_check_url(url, true)) != 0) { + if (((rv = udp_check_url(url, true)) != 0) || + ((rv = nni_url_to_address(&sa, url)) != 0)) { return (rv); } if ((rv = udp_ep_init(&ep, url, sock)) != 0) { return (rv); } - - if ((rv = nni_url_to_address(&ep->self_sa, url)) != 0) { - return (rv); - } + ep->self_sa = sa; #ifdef NNG_ENABLE_STATS nni_listener_add_stat(nlistener, &ep->st_rcv_max); From 0fd7ec869040bd79ebc27bcbb741495acff432bb Mon Sep 17 00:00:00 2001 From: Garrett D'Amore Date: Fri, 11 Oct 2024 17:25:42 -0700 Subject: [PATCH 055/222] Converted condition variable docs to mdbook. This also is implemented using a single unified manual page that should be easier to reference. Signed-off-by: jaylin --- docs/man/libnng.3.adoc | 12 ++-- docs/man/nng_cv_alloc.3supp.adoc | 60 ---------------- docs/man/nng_cv_free.3supp.adoc | 42 ----------- docs/man/nng_cv_until.3supp.adoc | 91 ------------------------ docs/man/nng_cv_wait.3supp.adoc | 86 ----------------------- docs/man/nng_cv_wake.3supp.adoc | 61 ---------------- docs/man/nng_cv_wake1.3supp.adoc | 61 ---------------- docs/ref/SUMMARY.md | 1 + docs/ref/api/thr/index.md | 1 + docs/ref/api/thr/nng_cv.md | 115 +++++++++++++++++++++++++++++++ docs/ref/api/thr/nng_mtx.md | 2 +- 11 files changed, 124 insertions(+), 408 deletions(-) delete mode 100644 docs/man/nng_cv_alloc.3supp.adoc delete mode 100644 docs/man/nng_cv_free.3supp.adoc delete mode 100644 docs/man/nng_cv_until.3supp.adoc delete mode 100644 docs/man/nng_cv_wait.3supp.adoc delete mode 100644 docs/man/nng_cv_wake.3supp.adoc delete mode 100644 docs/man/nng_cv_wake1.3supp.adoc create mode 100644 docs/ref/api/thr/nng_cv.md diff --git a/docs/man/libnng.3.adoc b/docs/man/libnng.3.adoc index 96b2a1387..fd4424cd6 100644 --- a/docs/man/libnng.3.adoc +++ b/docs/man/libnng.3.adoc @@ -281,12 +281,12 @@ as a convenience to aid in creating portable applications. |=== // |xref:nng_clock.3supp.adoc[nng_clock()]|get time -|xref:nng_cv_alloc.3supp.adoc[nng_cv_alloc()]|allocate condition variable -|xref:nng_cv_free.3supp.adoc[nng_cv_free()]|free condition variable -|xref:nng_cv_until.3supp.adoc[nng_cv_until()]|wait for condition or timeout -|xref:nng_cv_wait.3supp.adoc[nng_cv_wait()]|wait for condition -|xref:nng_cv_wake.3supp.adoc[nng_cv_wake()]|wake all waiters -|xref:nng_cv_wake1.3supp.adoc[nng_cv_wake1()]|wake one waiter +// |xref:nng_cv_alloc.3supp.adoc[nng_cv_alloc()]|allocate condition variable +// |xref:nng_cv_free.3supp.adoc[nng_cv_free()]|free condition variable +// |xref:nng_cv_until.3supp.adoc[nng_cv_until()]|wait for condition or timeout +// |xref:nng_cv_wait.3supp.adoc[nng_cv_wait()]|wait for condition +// |xref:nng_cv_wake.3supp.adoc[nng_cv_wake()]|wake all waiters +// |xref:nng_cv_wake1.3supp.adoc[nng_cv_wake1()]|wake one waiter // |xref:nng_id_map.3supp.adoc[nng_id_map]|identifier based mapping table // |xref:nng_msleep.3supp.adoc[nng_msleep()]|sleep for milliseconds // |xref:nng_mtx_alloc.3supp.adoc[nng_mtx_alloc()]|allocate mutex diff --git a/docs/man/nng_cv_alloc.3supp.adoc b/docs/man/nng_cv_alloc.3supp.adoc deleted file mode 100644 index 9e58e3f1f..000000000 --- a/docs/man/nng_cv_alloc.3supp.adoc +++ /dev/null @@ -1,60 +0,0 @@ -= nng_cv_alloc(3supp) -// -// Copyright 2018 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_cv_alloc - allocate condition variable - -== SYNOPSIS - -[source, c] ----- -#include -#include - -typedef struct nng_cv nng_cv; - -int nng_cv_alloc(nng_cv **cvp, nng_mtx *mtx); ----- - -== DESCRIPTION - -The `nng_cv_alloc()` function allocates a condition variable, using -the mutex _mtx_, and returns it in _cvp_. - -Every condition variable is associated with a mutex, which must be -owned when a thread waits for the condition using -xref:nng_cv_wait.3supp.adoc[`nng_cv_wait()`] or -xref:nng_cv_until.3supp.adoc[`nng_cv_until()`]. -The mutex must also be owned when signaling the condition using the -xref:nng_cv_wake.3supp.adoc[`nng_cv_wake()`] or -xref:nng_cv_wake1.3supp.adoc[`nng_cv_wake1()`] functions. - -== RETURN VALUES - -This function returns 0 on success, and non-zero otherwise. - -== ERRORS - -[horizontal] -`NNG_ENOMEM`:: Insufficient free memory exists. - -== SEE ALSO - -[.text-left] -xref:nng_cv_free.3supp.adoc[nng_cv_free(3supp)], -xref:nng_cv_until.3supp.adoc[nng_cv_until(3supp)], -xref:nng_cv_wait.3supp.adoc[nng_cv_wait(3supp)], -xref:nng_cv_wake.3supp.adoc[nng_cv_wake(3supp)], -xref:nng_cv_wake1.3supp.adoc[nng_cv_wake1(3supp)], -xref:nng_mtx_alloc.3supp.adoc[nng_mtx_alloc(3supp)], -xref:nng_strerror.3.adoc[nng_strerror(3)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_cv_free.3supp.adoc b/docs/man/nng_cv_free.3supp.adoc deleted file mode 100644 index 0610b52f9..000000000 --- a/docs/man/nng_cv_free.3supp.adoc +++ /dev/null @@ -1,42 +0,0 @@ -= nng_cv_free(3supp) -// -// Copyright 2018 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_cv_free - free condition variable - -== SYNOPSIS - -[source, c] ----- -#include -#include - -void nng_cv_free(nng_cv *cv); ----- - -== DESCRIPTION - -The `nng_cv_free()` function frees the condition variable _cv_. - -== RETURN VALUES - -None. - -== ERRORS - -None. - -== SEE ALSO - -[.text-left] -xref:nng_cv_alloc.3supp.adoc[nng_cv_alloc(3supp)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_cv_until.3supp.adoc b/docs/man/nng_cv_until.3supp.adoc deleted file mode 100644 index 9cf7c714f..000000000 --- a/docs/man/nng_cv_until.3supp.adoc +++ /dev/null @@ -1,91 +0,0 @@ -= nng_cv_until(3supp) -// -// Copyright 2021 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_cv_until - wait for condition or timeout - -== SYNOPSIS - -[source, c] ----- -#include -#include - -int nng_cv_until(nng_cv *cv, nng_time when); ----- - -== DESCRIPTION - -The `nng_cv_until()` waits until either the condition variable _cv_ is signaled -by another thread calling either xref:nng_cv_wake.3supp.adoc[`nng_cv_wake()`] or -xref:nng_cv_wake1.3supp.adoc[`nng_cv_wake1()`], or the system clock (as tracked -by xref:nng_clock.3supp.adoc[`nng_clock()`]) reaches _when_. - -The caller must have have ownership of the mutex that was used when -_cv_ was allocated. -This function will drop the ownership of that mutex, and reacquire it -atomically just before returning to the caller. -(The waiting is done without holding the mutex.) - -NOTE: Any condition may be used or checked, but the condition must be -checked, as it is possible for this function to wake up spuriously. -The best way to do this is inside a loop that repeats until the condition -tests for true. - -== EXAMPLE - -The following example demonstrates use of this function: - -.Example 1: Waiting for the condition -[source, c] ----- - - 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 2: Signaling the condition -[source, c] ----- - nng_mtx_lock(m); - condition_true = true; - nng_cv_wake(cv); - nng_mtx_unlock(m); ----- - -== RETURN VALUES - -None. - -== ERRORS - -None. - -== SEE ALSO - -[.text-left] -xref:nng_cv_alloc.3supp.adoc[nng_cv_alloc(3supp)], -xref:nng_cv_wait.3supp.adoc[nng_cv_wait(3supp)], -xref:nng_cv_wake.3supp.adoc[nng_cv_wake(3supp)], -xref:nng_cv_wake1.3supp.adoc[nng_cv_wake1(3supp)], -xref:nng_mtx_alloc.3supp.adoc[nng_mtx_alloc(3supp)], -xref:nng_mtx_lock.3supp.adoc[nng_mtx_lock(3supp)], -xref:nng_mtx_unlock.3supp.adoc[nng_mtx_unlock(3supp)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_cv_wait.3supp.adoc b/docs/man/nng_cv_wait.3supp.adoc deleted file mode 100644 index 1d9c16be4..000000000 --- a/docs/man/nng_cv_wait.3supp.adoc +++ /dev/null @@ -1,86 +0,0 @@ -= nng_cv_wait(3supp) -// -// Copyright 2018 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_cv_wait - wait for condition - -== SYNOPSIS - -[source, c] ----- -#include -#include - -void nng_cv_wait(nng_cv *cv); ----- - -== DESCRIPTION - -The `nng_cv_wait()` waits for the condition variable _cv_ to be signaled -by another thread calling either xref:nng_cv_wake.3supp.adoc[`nng_cv_wake()`] or -xref:nng_cv_wake1.3supp.adoc[`nng_cv_wake1()`]. - -The caller must have have ownership of the mutex that was used when -_cv_ was allocated. -This function will drop the ownership of that mutex, and reacquire it -atomically just before returning to the caller. -(The waiting is done without holding the mutex.) - -NOTE: Any condition may be used or checked, but the condition must be -checked, as it is possible for this function to wake up spuriously. -The best way to do this is inside a loop that repeats until the condition -tests for true. - -== EXAMPLE - -The following example demonstrates use of this function: - -.Example 1: Waiting for the condition -[source, c] ----- - - nng_mtx_lock(m); // assume cv was allocated using m - while (!condition_true) { - nng_cv_wait(cv); - } - // condition_true is true - nng_mtx_unlock(m); ----- - -.Example 2: Signaling the condition -[source, c] ----- - nng_mtx_lock(m); - condition_true = true; - nng_cv_wake(cv); - nng_mtx_unlock(m); ----- - -== RETURN VALUES - -None. - -== ERRORS - -None. - -== SEE ALSO - -[.text-left] -xref:nng_cv_alloc.3supp.adoc[nng_cv_alloc(3supp)], -xref:nng_cv_until.3supp.adoc[nng_cv_until(3supp)], -xref:nng_cv_wake.3supp.adoc[nng_cv_wake(3supp)], -xref:nng_cv_wake1.3supp.adoc[nng_cv_wake1(3supp)], -xref:nng_mtx_alloc.3supp.adoc[nng_mtx_alloc(3supp)], -xref:nng_mtx_lock.3supp.adoc[nng_mtx_lock(3supp)], -xref:nng_mtx_unlock.3supp.adoc[nng_mtx_unlock(3supp)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_cv_wake.3supp.adoc b/docs/man/nng_cv_wake.3supp.adoc deleted file mode 100644 index 6ee2945d7..000000000 --- a/docs/man/nng_cv_wake.3supp.adoc +++ /dev/null @@ -1,61 +0,0 @@ -= nng_cv_wake(3supp) -// -// Copyright 2020 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_cv_wake - wake all waiters - -== SYNOPSIS - -[source, c] ----- -#include -#include - -void nng_cv_wake(nng_cv *cv); ----- - -== DESCRIPTION - -The `nng_cv_wake()` wakes any threads waiting for the condition variable _cv_ -to be signaled in the xref:nng_cv_wait.3supp.adoc[`nng_cv_wait()`] or -xref:nng_cv_until.3supp.adoc[`nng_cv_until()`] functions. - -The caller must have have ownership of the mutex that was used when -_cv_ was allocated. - -NOTE: The caller should already have set the condition that the waiters -will check, while holding the mutex. - -TIP: This function wakes all threads, which is generally safer but can -lead to a performance problem when there are many waiters, as they are all -woken simultaneously and may contend for resources. -See xref:nng_cv_wake1.3supp.adoc[`nng_cv_wake1()`] for a solution to this problem. - -== RETURN VALUES - -None. - -== ERRORS - -None. - -== SEE ALSO - -[.text-left] -xref:nng_cv_alloc.3supp.adoc[nng_cv_alloc(3supp)], -xref:nng_cv_until.3supp.adoc[nng_cv_until(3supp)], -xref:nng_cv_wait.3supp.adoc[nng_cv_wait(3supp)], -xref:nng_cv_wake1.3supp.adoc[nng_cv_wake1(3supp)], -xref:nng_mtx_alloc.3supp.adoc[nng_mtx_alloc(3supp)], -xref:nng_mtx_lock.3supp.adoc[nng_mtx_lock(3supp)], -xref:nng_mtx_unlock.3supp.adoc[nng_mtx_unlock(3supp)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_cv_wake1.3supp.adoc b/docs/man/nng_cv_wake1.3supp.adoc deleted file mode 100644 index 4f8b8326d..000000000 --- a/docs/man/nng_cv_wake1.3supp.adoc +++ /dev/null @@ -1,61 +0,0 @@ -= nng_cv_wake1(3supp) -// -// Copyright 2018 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_cv_wake1 - wake one waiter - -== SYNOPSIS - -[source, c] ----- -#include -#include - -void nng_cv_wake1(nng_cv *cv); ----- - -== DESCRIPTION - -The `nng_cv_wake1()` wakes at most one thread waiting for the condition -variable _cv_ -to be signaled in the xref:nng_cv_wait.3supp.adoc[`nng_cv_wait()`] or -xref:nng_cv_until.3supp.adoc[`nng_cv_until()`] functions. - -The caller must have have ownership of the mutex that was used when -_cv_ was allocated. - -NOTE: The caller should already have set the condition that the waiters -will check, while holding the mutex. - -NOTE: The caller cannot predict which waiter will be woken, and so the design must -ensure that it is sufficient that _any_ waiter be woken. -When in doubt, it is safer to use xref:nng_cv_wake.3supp.adoc[`nng_cv_wake()`]. - -== RETURN VALUES - -None. - -== ERRORS - -None. - -== SEE ALSO - -[.text-left] -xref:nng_cv_alloc.3supp.adoc[nng_cv_alloc(3supp)], -xref:nng_cv_until.3supp.adoc[nng_cv_until(3supp)], -xref:nng_cv_wait.3supp.adoc[nng_cv_wait(3supp)], -xref:nng_cv_wake.3supp.adoc[nng_cv_wake(3supp)], -xref:nng_mtx_alloc.3supp.adoc[nng_mtx_alloc(3supp)], -xref:nng_mtx_lock.3supp.adoc[nng_mtx_lock(3supp)], -xref:nng_mtx_unlock.3supp.adoc[nng_mtx_unlock(3supp)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/ref/SUMMARY.md b/docs/ref/SUMMARY.md index ac627ee48..1d7065c26 100644 --- a/docs/ref/SUMMARY.md +++ b/docs/ref/SUMMARY.md @@ -4,6 +4,7 @@ - [Threading Functions](./api/thr/index.md) + - [nng_cv](./api/thr/nng_cv.md) - [nng_mtx](./api/thr/nng_mtx.md) - [Utility Functions](./api/util/index.md) diff --git a/docs/ref/api/thr/index.md b/docs/ref/api/thr/index.md index d9d168ac8..6355cfefe 100644 --- a/docs/ref/api/thr/index.md +++ b/docs/ref/api/thr/index.md @@ -1,3 +1,4 @@ # Threading Functions +- [nng_cv](nng_cv.md) - [nng_mtx](nng_mtx.md) diff --git a/docs/ref/api/thr/nng_cv.md b/docs/ref/api/thr/nng_cv.md new file mode 100644 index 000000000..29a149a0e --- /dev/null +++ b/docs/ref/api/thr/nng_cv.md @@ -0,0 +1,115 @@ +# nng_cv + +## NAME + +nng_cv --- condition variable + +## SYNOPSIS + +```c +#include + +typedef struct nng_cv nng_cv; + +int nng_cv_alloc(nng_cv **cvp, nng_mtx *mtx); +void nng_cv_free(nng_cv *cv); +int nng_cv_until(nng_cv *cv, nng_time when); +void nng_cv_wait(nng_cv *cv); +void nng_cv_wake(nng_cv *cv); +void nng_cv_wake1(nng_cv *cv); +``` + +## DESCRIPTION + +The {{i:`nng_cv`}} structure implements a {{i:condition variable}}, associated with the +the [mutex][nng_mtx] _mtx_ which was supplied when it was created. + +Condition variables provide for a way to wait on an arbitrary condition, and to be woken +when the condition is signaled. +The mutex is dropped while the caller is asleep, and reacquired atomically when the caller +is woken. + +> [!IMPORTANT] +> +> The caller of `nng_cv_until`, `nng_cv_wait`, `nng_cv_wake`, and `nng_cv_wake1` _must_ +> have ownership of the mutex _mtx_ when calling these functions. + +### Initialization and Teardown + +The {{i:`nng_cv_alloc`}} function allocates a condition variable, and associated with the mutex _mtx_, +and returns a pointer to it in _cvp_. +The {{i:`nng_cv_free`}} function deallocates the condition variable _cv_. + +### Waiting for the Condition + +The {{i:`nng_cv_until`}} and {{i:`nng_cv_wait`}} functions put the caller to sleep until the condition +variable _cv_ is signaled, or (in the case of `nng_cv_until`), the specified time _when_ +(as determined by [`nng_clock`][nng_clock] is reached. + +While `nng_cv_wait` never fails and so has no return value, the `nng_cv_until` function can +return `NNG_ETIMEDOUT` if the time is reached before condition _cv_ is signaled by +either `nng_cv_wake` or `nng_cv_wake1`. + +### Signaling the Condition + +The {{i:`nng_cv_wake`}} and {{i:`nng_cv_wake1`}} functions wake threads waiting in +`nng_cv_until` or `nng_cv_wake`. The difference between these functions is that +`nng_cv_wake` will wake _every_ thread, whereas `nng_cv_wake1` will wake up exactly +one thread (which may be chosen randomly). + +> [!TIP] +> Use of `nng_cv_wake1` may be used to reduce the "thundering herd" syndrom of waking +> all threads concurrently, but should only be used in circumstances where the application +> does not depend on _which_ thread will be woken. When in doubt, `nng_cv_wake` is safer. + +## EXAMPLE + +### Example 1: Allocating the condition variable + +```c + nng_mtx *m; + nng_cv *cv; + nng_mtx_alloc(&m); // error checks elided + nng_cv_alloc(&cv, m); +``` + +### Example 2: Waiting for the condition + +```c + 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 + +```c + nng_mtx_lock(m); + condition_true = true; + nng_cv_wake(cv); + nng_mtx_unlock(m); +``` + +## RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +## ERRORS + +- `NNG_ENOMEM`: Insufficient free memory exists. +- `NNG_ETIMEDOUT`: The time specified by _when_ is reached without the condition being signaled. + +## SEE ALSO + +[nng_clock][nng_clock], +[nng_mtx][nng_mtx] + +[nng_clock]: ../util/nng_clock.md +[nng_mtx]: ../thr/nng_mtx.md diff --git a/docs/ref/api/thr/nng_mtx.md b/docs/ref/api/thr/nng_mtx.md index 37249e4f8..027354238 100644 --- a/docs/ref/api/thr/nng_mtx.md +++ b/docs/ref/api/thr/nng_mtx.md @@ -1,4 +1,4 @@ -# nng_id_map +# nng_mutex ## NAME From 15c04c85402745cdeb3adaf65115fe8d9d8f5cc9 Mon Sep 17 00:00:00 2001 From: Garrett D'Amore Date: Fri, 11 Oct 2024 22:32:04 -0700 Subject: [PATCH 056/222] Convert nng_socket_pair. Also some cleanups on the organization of the mdbook. --- docs/man/libnng.3.adoc | 2 +- docs/man/nng_socket_pair.3supp.adoc | 52 ----------------------------- docs/ref/SUMMARY.md | 5 +-- docs/ref/api.md | 4 --- docs/ref/api/index.md | 4 +++ docs/ref/api/thr/index.md | 6 +++- docs/ref/api/util/index.md | 19 ++++++----- docs/ref/tran/socket.md | 6 ++-- 8 files changed, 26 insertions(+), 72 deletions(-) delete mode 100644 docs/man/nng_socket_pair.3supp.adoc delete mode 100644 docs/ref/api.md create mode 100644 docs/ref/api/index.md diff --git a/docs/man/libnng.3.adoc b/docs/man/libnng.3.adoc index fd4424cd6..f2e7494fe 100644 --- a/docs/man/libnng.3.adoc +++ b/docs/man/libnng.3.adoc @@ -295,7 +295,7 @@ as a convenience to aid in creating portable applications. // |xref:nng_mtx_unlock.3supp.adoc[nng_mtx_unlock()]|unlock mutex |xref:nng_opts_parse.3supp.adoc[nng_opts_parse()]|parse command line options // |xref:nng_random.3supp.adoc[nng_random()]|get random number -|xref:nng_socket_pair.3supp.adoc[nng_socket_pair()]|create connected pair of BSD sockets +// |xref:nng_socket_pair.3supp.adoc[nng_socket_pair()]|create connected pair of BSD sockets |xref:nng_thread_create.3supp.adoc[nng_thread_create()]|create thread |xref:nng_thread_destroy.3supp.adoc[nng_thread_destroy()]|reap thread |xref:nng_thread_set_name.3supp.adoc[nng_thread_set_name()]|set thread name diff --git a/docs/man/nng_socket_pair.3supp.adoc b/docs/man/nng_socket_pair.3supp.adoc deleted file mode 100644 index 7718e27b9..000000000 --- a/docs/man/nng_socket_pair.3supp.adoc +++ /dev/null @@ -1,52 +0,0 @@ -= nng_socket_pair(3supp) -// -// 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 -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_socket_pair - create a connected pair of BSD sockets - -== SYNOPSIS - -[source, c] ----- -#include - -int nng_socket_pair(int fds[2]); ----- - -== DESCRIPTION - -The `nng_socket_pair()` function creates a pair of connected BSD sockets. -These sockets, which are returned in the _fds_ array, are suitable for -use with the xref:nng_socket.7.adoc[_socket_] transport. - -On POSIX platforms, this is a thin wrapper around the standard `socketpair()` function, -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 a shared filesystem or TCP connection. - -== RETURN VALUES - -This function returns 0 on success, and non-zero otherwise. - -== ERRORS - -[horizontal] -`NNG_ENOMEM`:: Insufficient memory exists. -`NNG_ENOTSUP`:: This platform does not support socket pairs. - -== SEE ALSO - -[.text-left] -xref:nng_socket.7.adoc[nng_socket(7)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/ref/SUMMARY.md b/docs/ref/SUMMARY.md index 1d7065c26..c68fb2b31 100644 --- a/docs/ref/SUMMARY.md +++ b/docs/ref/SUMMARY.md @@ -1,8 +1,8 @@ # Summary -- [API](./api.md) +- [API](./api/index.md) - - [Threading Functions](./api/thr/index.md) + - [Threading and Synchronization](./api/thr/index.md) - [nng_cv](./api/thr/nng_cv.md) - [nng_mtx](./api/thr/nng_mtx.md) @@ -14,6 +14,7 @@ - [nng_id_map](./api/util/nng_id_map.md) - [nng_msleep](./api/util/nng_msleep.md) - [nng_random](./api/util/nng_random.md) + - [nng_socket_pair](./api/util/nng_socket_pair.md) - [nng_strdup](./api/util/nng_strdup.md) - [nng_strerror](./api/util/nng_strerror.md) - [nng_version](./api/util/nng_version.md) diff --git a/docs/ref/api.md b/docs/ref/api.md deleted file mode 100644 index 84d0501f5..000000000 --- a/docs/ref/api.md +++ /dev/null @@ -1,4 +0,0 @@ -# API - -- [Threading Support](api/thr/) -- [Utility Functions](api/util/) diff --git a/docs/ref/api/index.md b/docs/ref/api/index.md new file mode 100644 index 000000000..6ad8257f5 --- /dev/null +++ b/docs/ref/api/index.md @@ -0,0 +1,4 @@ +# API + +- [Threading and Synchronization](api/thr/) +- [Utility Functions](api/util/) diff --git a/docs/ref/api/thr/index.md b/docs/ref/api/thr/index.md index 6355cfefe..bdd8bef48 100644 --- a/docs/ref/api/thr/index.md +++ b/docs/ref/api/thr/index.md @@ -1,4 +1,8 @@ -# Threading Functions +# Threading and Synchronization + +These interfaces are likely to be useful when implementing concurrent designs. +Furthermore, because NNG itself is based on concurrency, the synchronization primitives +are likely to be useful in callback functions and similar situations. - [nng_cv](nng_cv.md) - [nng_mtx](nng_mtx.md) diff --git a/docs/ref/api/util/index.md b/docs/ref/api/util/index.md index 1f202c0f5..cc6ee7e2f 100644 --- a/docs/ref/api/util/index.md +++ b/docs/ref/api/util/index.md @@ -2,14 +2,15 @@ This section documents various utility functions that may help with application portability. These are not fundamental to NNG -or Scalability Protocols, but we find them useful for a variety +or Scalability Protocols, but they are likely useful for a variety of other uses. -- [nng_alloc](nng_alloc.md) -- [nng_clock](nng_clock.md) -- [nng_id_map](nng_id_map.md) -- [nng_msleep](nng_msleep.md) -- [nng_random](nng_random.md) -- [nng_strdup](nng_strdup.md) -- [nng_strerror](nng_strerror.md) -- [nng_version](nng_version.md) +- [nng_alloc](nng_alloc.md) --- allocate memory +- [nng_clock](nng_clock.md) --- get time +- [nng_id_map](nng_id_map.md) --- identifier based mapping table +- [nng_msleep](nng_msleep.md) --- sleep milliseconds +- [nng_random](nng_random.md) --- get random number +- [nng_socket_pair](nng_socket_pair.md) --- create a connected pair of BSD sockets +- [nng_strdup](nng_strdup.md) --- duplicate string +- [nng_strerror](nng_strerror.md) --- return an error description +- [nng_version](nng_version.md) --- report library version diff --git a/docs/ref/tran/socket.md b/docs/ref/tran/socket.md index 0b7d5a457..c55966a87 100644 --- a/docs/ref/tran/socket.md +++ b/docs/ref/tran/socket.md @@ -4,10 +4,10 @@ The {{i:_socket_ transport}} supports communication between peers across arbitrary BSD sockets, such as those that are -created with [`nng_socket_pair()`][nng_socket_pair]. +created with [`nng_socket_pair`][nng_socket_pair]. This transport only supports [listeners][listener], -using [`nng_listener_create()`][nng_listener_create]. +using [`nng_listener_create`][nng_listener_create]. > [!NOTE] > Attempts to create [dialers][dialer] using this transport will result in `NNG_ENOTSUP`. @@ -63,7 +63,7 @@ Additionally, the following options may be supported on pipes when the platform [dialer]: [TODO.md] [nng_sockaddr]: [TODO.md] [nng_listener_create]: [TODO.md] -[nng_socket_pair]: [TODO.md] +[nng_socket_pair]: ../../api/util/nng_socket_pair.md [NNG_OPT_LOCADDR]: [TODO.md] [NNG_OPT_REMADDR]: [TODO.md] [NNG_OPT_URL]: [TODO.md] From 9a352f2f9c3ca7cda1f21e84eadceab17e221164 Mon Sep 17 00:00:00 2001 From: Garrett D'Amore Date: Fri, 11 Oct 2024 22:42:44 -0700 Subject: [PATCH 057/222] more mdbook stuff --- docs/ref/SUMMARY.md | 2 +- docs/ref/api/index.md | 4 +++- docs/ref/api/thr/index.md | 4 ++-- docs/ref/tran/index.md | 2 ++ 4 files changed, 8 insertions(+), 4 deletions(-) diff --git a/docs/ref/SUMMARY.md b/docs/ref/SUMMARY.md index c68fb2b31..e39a9969c 100644 --- a/docs/ref/SUMMARY.md +++ b/docs/ref/SUMMARY.md @@ -1,6 +1,6 @@ # Summary -- [API](./api/index.md) +- [API Reference](./api/index.md) - [Threading and Synchronization](./api/thr/index.md) diff --git a/docs/ref/api/index.md b/docs/ref/api/index.md index 6ad8257f5..403045d2c 100644 --- a/docs/ref/api/index.md +++ b/docs/ref/api/index.md @@ -1,4 +1,6 @@ -# API +# API Reference + +This section is a reference guide for the NNG programming interfaces. - [Threading and Synchronization](api/thr/) - [Utility Functions](api/util/) diff --git a/docs/ref/api/thr/index.md b/docs/ref/api/thr/index.md index bdd8bef48..5f60ed661 100644 --- a/docs/ref/api/thr/index.md +++ b/docs/ref/api/thr/index.md @@ -4,5 +4,5 @@ These interfaces are likely to be useful when implementing concurrent designs. Furthermore, because NNG itself is based on concurrency, the synchronization primitives are likely to be useful in callback functions and similar situations. -- [nng_cv](nng_cv.md) -- [nng_mtx](nng_mtx.md) +- [nng_cv](nng_cv.md) --- condition variable +- [nng_mtx](nng_mtx.md) --- mutual exclusion lock diff --git a/docs/ref/tran/index.md b/docs/ref/tran/index.md index 25f32a7f7..8cefa14b6 100644 --- a/docs/ref/tran/index.md +++ b/docs/ref/tran/index.md @@ -1,4 +1,6 @@ # Transports +This section documents transports for Scalabity Protocols implemented by NNG. + - [BSD Socket](socket.md) - [UDP](udp.md) From 5cb5edfd0bd3366374ea1e244751e14f55f9db39 Mon Sep 17 00:00:00 2001 From: Garrett D'Amore Date: Fri, 11 Oct 2024 23:03:08 -0700 Subject: [PATCH 058/222] Add missing nng_socket_pair.md --- docs/ref/api/util/nng_socket_pair.md | 42 ++++++++++++++++++++++++++++ 1 file changed, 42 insertions(+) create mode 100644 docs/ref/api/util/nng_socket_pair.md diff --git a/docs/ref/api/util/nng_socket_pair.md b/docs/ref/api/util/nng_socket_pair.md new file mode 100644 index 000000000..454c15fca --- /dev/null +++ b/docs/ref/api/util/nng_socket_pair.md @@ -0,0 +1,42 @@ +# nng_socket_pair + +## NAME + +nng_socket_pair --- create a connected pair of BSD sockets + +## SYNOPSIS + +```c +#include + +int nng_socket_pair(int fds[2]); +``` + +## DESCRIPTION + +The `nng_socket_pair` function creates a pair of connected BSD sockets. +These sockets, which are returned in the _fds_ array, are suitable for +use with the [BSD socket transport][socket]. + +On POSIX platforms, this is a thin wrapper around the standard `socketpair` function, +using the {{i:`AF_UNIX`}} family and the `SOCK_STREAM` socket type. +{{footnote: At present only POSIX platforms implementing `socketpair` support 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. + +## RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +## ERRORS + +- `NNG_ENOMEM`: Insufficient memory exists. +- `NNG_ENOTSUP`: This platform does not support socket pairs. + +## SEE ALSO + +[BSD Socket Transport][socket] + +[socket]: ../../tran/socket.md From 0b84bdd6291c9120c0806d2b1e19275acc40826f Mon Sep 17 00:00:00 2001 From: Garrett D'Amore Date: Fri, 11 Oct 2024 23:02:16 -0700 Subject: [PATCH 059/222] Convert thread documentation to mdbook. Also conslidate this man page. Signed-off-by: jaylin --- docs/man/libnng.3.adoc | 6 +- docs/man/nng_thread_create.3supp.adoc | 87 ------------------------- docs/man/nng_thread_destroy.3supp.adoc | 47 ------------- docs/man/nng_thread_set_name.3supp.adoc | 48 -------------- docs/ref/SUMMARY.md | 1 + docs/ref/api/thr/index.md | 1 + docs/ref/api/thr/nng_thread.md | 84 ++++++++++++++++++++++++ 7 files changed, 89 insertions(+), 185 deletions(-) delete mode 100644 docs/man/nng_thread_create.3supp.adoc delete mode 100644 docs/man/nng_thread_destroy.3supp.adoc delete mode 100644 docs/man/nng_thread_set_name.3supp.adoc create mode 100644 docs/ref/api/thr/nng_thread.md diff --git a/docs/man/libnng.3.adoc b/docs/man/libnng.3.adoc index f2e7494fe..e03c6b146 100644 --- a/docs/man/libnng.3.adoc +++ b/docs/man/libnng.3.adoc @@ -296,9 +296,9 @@ as a convenience to aid in creating portable applications. |xref:nng_opts_parse.3supp.adoc[nng_opts_parse()]|parse command line options // |xref:nng_random.3supp.adoc[nng_random()]|get random number // |xref:nng_socket_pair.3supp.adoc[nng_socket_pair()]|create connected pair of BSD sockets -|xref:nng_thread_create.3supp.adoc[nng_thread_create()]|create thread -|xref:nng_thread_destroy.3supp.adoc[nng_thread_destroy()]|reap thread -|xref:nng_thread_set_name.3supp.adoc[nng_thread_set_name()]|set thread name +// |xref:nng_thread_create.3supp.adoc[nng_thread_create()]|create thread +// |xref:nng_thread_destroy.3supp.adoc[nng_thread_destroy()]|reap thread +// |xref:nng_thread_set_name.3supp.adoc[nng_thread_set_name()]|set thread name |=== === Byte Streams diff --git a/docs/man/nng_thread_create.3supp.adoc b/docs/man/nng_thread_create.3supp.adoc deleted file mode 100644 index 129bddead..000000000 --- a/docs/man/nng_thread_create.3supp.adoc +++ /dev/null @@ -1,87 +0,0 @@ -= nng_thread_create(3supp) -// -// Copyright 2018 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_thread_create - create thread - -== SYNOPSIS - -[source, c] ----- -#include -#include - -typedef struct nng_thread nng_thread; - -int nng_thread_create(nng_thread **thrp, void (*func)(void *), void *arg); ----- - -== DESCRIPTION - -The `nng_thread_create()` function creates a single thread of execution, -running _func_ with the argument _arg_. -The thread is started immediately. -A pointer to the thread object is returned in _thrp_. - -The intention of this program is to facilitate writing parallel programs. -Threads created by this program will be based upon the underlying -threading mechanism of the system that _NNG_ is running on. -This may include use of coroutines. - -Using threads created by this function can make it easy to write -programs that use simple sequential execution, using functions in the -_NNG_ suite that would otherwise normally wait synchronously for completion. - -When the thread is no longer needed, the -xref:nng_thread_destroy.3supp.adoc[`nng_thread_destroy()`] -function should be used to reap it. -(This function will block waiting for _func_ to return.) - -IMPORTANT: Thread objects created by this function may not be real system -level threads capable of performing blocking I/O operations using normal blocking -system calls. -If use of blocking system calls is required (not including APIs provided -by the _NNG_ library itself of course), then real OS-specific threads -should be created instead (such as with `pthread_create()` or similar -functions.) - -IMPORTANT: Thread objects created by this function cannot be passed -to any system threading functions. - -TIP: The system may impose limits on the number of threads that can be -created. -Typically applications should not create more than a dozen of these. -If greater concurrency or scalability is needed, consider instead using -an asynchronous model using xref:nng_aio.5.adoc[`nng_aio`] structures. - -TIP: Threads can be synchronized using -xref:nng_mtx_alloc.3supp.adoc[mutexes] and -xref:nng_cv_alloc.3supp.adoc[condition variables]. - -== RETURN VALUES - -This function returns 0 on success, and non-zero otherwise. - -== ERRORS - -[horizontal] -`NNG_ENOMEM`:: Insufficient free memory exists. - -== SEE ALSO - -[.text-left] -xref:nng_strerror.3.adoc[nng_strerror(3)], -xref:nng_cv_alloc.3supp.adoc[nng_cv_alloc(3supp)], -xref:nng_mtx_alloc.3supp.adoc[nng_mtx_alloc(3supp)], -xref:nng_thread_destroy.3supp.adoc[nng_thread_destroy(3supp)], -xref:nng_aio.5.adoc[nng_aio(5)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_thread_destroy.3supp.adoc b/docs/man/nng_thread_destroy.3supp.adoc deleted file mode 100644 index 95eed8131..000000000 --- a/docs/man/nng_thread_destroy.3supp.adoc +++ /dev/null @@ -1,47 +0,0 @@ -= nng_thread_destroy(3supp) -// -// Copyright 2018 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_thread_destroy - reap thread - -== SYNOPSIS - -[source, c] ----- -#include -#include - -void nng_thread_destroy(nng_thread *thread); ----- - -== DESCRIPTION - -The `nng_thread_destroy()` function reaps the _thread_. -It waits for the thread function to return, and then deallocates -the resources for the thread. - -IMPORTANT: Do not call this function from the thread function itself, -or a deadlock will occur. - -== RETURN VALUES - -None. - -== ERRORS - -None. - -== SEE ALSO - -[.text-left] -xref:nng_thread_create.3supp.adoc[nng_thread_create(3supp)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_thread_set_name.3supp.adoc b/docs/man/nng_thread_set_name.3supp.adoc deleted file mode 100644 index 36dd8267c..000000000 --- a/docs/man/nng_thread_set_name.3supp.adoc +++ /dev/null @@ -1,48 +0,0 @@ -= nng_thread_set_name(3supp) -// -// Copyright 2020 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 -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_thread_set_name - set thread name - -== SYNOPSIS - -[source, c] ----- -#include -#include - -void nng_thread_set_name(nng_thread *thread, const char *name); ----- - -== DESCRIPTION - -The `nng_thread_set_name()` function attempts to set the name for the _thread_ to _name_. - -If _thread_ is `NULL`, then the name is set for the current thread. - -Support for this, and how names are exposed, varies between platform implementations. -This function is intended to facilitate debugging applications that may have many threads. - -TIP: Internal threads created by _NNG_ will have names beginning with `nng:`. - -== RETURN VALUES - -None. - -== ERRORS - -None. - -== SEE ALSO - -[.text-left] -xref:nng_thread_create.3supp.adoc[nng_thread_create(3supp)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/ref/SUMMARY.md b/docs/ref/SUMMARY.md index e39a9969c..250763810 100644 --- a/docs/ref/SUMMARY.md +++ b/docs/ref/SUMMARY.md @@ -6,6 +6,7 @@ - [nng_cv](./api/thr/nng_cv.md) - [nng_mtx](./api/thr/nng_mtx.md) + - [nng_thread](./api/thr/nng_thread.md) - [Utility Functions](./api/util/index.md) diff --git a/docs/ref/api/thr/index.md b/docs/ref/api/thr/index.md index 5f60ed661..28d628d9e 100644 --- a/docs/ref/api/thr/index.md +++ b/docs/ref/api/thr/index.md @@ -6,3 +6,4 @@ are likely to be useful in callback functions and similar situations. - [nng_cv](nng_cv.md) --- condition variable - [nng_mtx](nng_mtx.md) --- mutual exclusion lock +- [nng_thread](nng_thread.md) -- thread of execution diff --git a/docs/ref/api/thr/nng_thread.md b/docs/ref/api/thr/nng_thread.md new file mode 100644 index 000000000..e13e77c65 --- /dev/null +++ b/docs/ref/api/thr/nng_thread.md @@ -0,0 +1,84 @@ +# nng_thread + +## NAME + +nng_thread --- thread of execution + +## SYNOPSIS + +```c +#include + +typedef struct nng_thread nng_thread; + +int nng_thread_create(nng_thread **thrp, void (*func)(void *), void *arg); +void nng_thread_destroy(nng_thread *thr); +void nng_thread_set_name(nng_thread *thr, const char *name); +``` + +### DESCRIPTION + +The {{i:`nng_thread`}} structure is used to represent a {{i:thread}} of execution. + +In NNG, a thread has an execution fuction _func_, and can be assumed to run this concurrently +to other threads, including the main thread of the application. The thread persists +until the function _func_ returns. + +> [!TIP] +> The detail of whether the thread represents an operating system thread, +> a process, or a "green" thread (also known as a a fiber or coroutine) is determined by the platform. +> Portable applications should avoid depending on this implementation detail. + +The `nng_thread_create` function creates a thread, +running _func_ with the argument _arg_. +The thread is started immediately. +A pointer to the thread object is returned in _thrp_. + +Using threads created by this function can make it easy to write +programs that use simple sequential execution, using functions in the +_NNG_ suite that would otherwise normally wait synchronously for completion. + +When the thread is no longer needed, the {{i: `nng_thread_destroy`}} +function should be used to reap it. +(This function will block waiting for _func_ to return.) + +> [!IMPORTANT] +> Thread objects created by this function may not be real system-level +> threads capable of performing blocking I/O operations using normal blocking system calls. +> If use of blocking system calls is required (not including APIs provided +> by the _NNG_ library itself of course), then real OS-specific threads +> should be created instead (such as with `pthread_create` or similar functions.) + +> [!IMPORTANT] +> Thread objects created by this function cannot be passed to any system threading functions. + +> [!TIP] +> The system may impose limits on the number of threads that can be created. +> Typically applications should not create more than a dozen of these. +> If greater concurrency or scalability is needed, consider instead using +> an asynchronous model using [`nng_aio`][aio] structures. + +> [!TIP] +> Threads can be synchronized using [mutexes][mutex] and +> [condition variables][condvar]. + +In order to facilitate debugging, {{i:`nng_thread_set_name`}} may be called +to provide a name for the thread. This may change how the thread is represented +in debuggers. Not all platforms support setting the thread name. + +## RETURN VALUES + +The `nng_thread_create` function returns 0 on success, and non-zero otherwise. + +## ERRORS + +- `NNG_ENOMEM`: Insufficient free memory exists. + +## SEE ALSO + +[nng_cv][condvar], +[nng_mutex][mutex] + +[condvar]: ../thr/nng_cv.md +[mutex]: ../thr/nng_mtx.md +[aio]: TODO.md From 73303401ed48688cd353d2f5e840081ce0cab858 Mon Sep 17 00:00:00 2001 From: Garrett D'Amore Date: Fri, 11 Oct 2024 23:18:10 -0700 Subject: [PATCH 060/222] nng_opts_parse converted to mdbook. --- docs/man/libnng.3.adoc | 14 +-- docs/ref/SUMMARY.md | 1 + .../api/util/nng_opts_parse.md} | 100 +++++++----------- 3 files changed, 50 insertions(+), 65 deletions(-) rename docs/{man/nng_opts_parse.3supp.adoc => ref/api/util/nng_opts_parse.md} (67%) diff --git a/docs/man/libnng.3.adoc b/docs/man/libnng.3.adoc index e03c6b146..67226962a 100644 --- a/docs/man/libnng.3.adoc +++ b/docs/man/libnng.3.adoc @@ -275,11 +275,13 @@ Common functionality for message logging. === Supplemental API -These supplemental functions are not intrinsic to building -network applications with _NNG_, but they are made available -as a convenience to aid in creating portable applications. +NOTE: All these functions have been moved to new mdbook docs. -|=== +// These supplemental functions are not intrinsic to building +// network applications with _NNG_, but they are made available +// as a convenience to aid in creating portable applications. +// +// |=== // |xref:nng_clock.3supp.adoc[nng_clock()]|get time // |xref:nng_cv_alloc.3supp.adoc[nng_cv_alloc()]|allocate condition variable // |xref:nng_cv_free.3supp.adoc[nng_cv_free()]|free condition variable @@ -293,13 +295,13 @@ as a convenience to aid in creating portable applications. // |xref:nng_mtx_free.3supp.adoc[nng_mtx_free()]|free mutex // |xref:nng_mtx_lock.3supp.adoc[nng_mtx_lock()]|lock mutex // |xref:nng_mtx_unlock.3supp.adoc[nng_mtx_unlock()]|unlock mutex -|xref:nng_opts_parse.3supp.adoc[nng_opts_parse()]|parse command line options +// |xref:nng_opts_parse.3supp.adoc[nng_opts_parse()]|parse command line options // |xref:nng_random.3supp.adoc[nng_random()]|get random number // |xref:nng_socket_pair.3supp.adoc[nng_socket_pair()]|create connected pair of BSD sockets // |xref:nng_thread_create.3supp.adoc[nng_thread_create()]|create thread // |xref:nng_thread_destroy.3supp.adoc[nng_thread_destroy()]|reap thread // |xref:nng_thread_set_name.3supp.adoc[nng_thread_set_name()]|set thread name -|=== +// |=== === Byte Streams diff --git a/docs/ref/SUMMARY.md b/docs/ref/SUMMARY.md index 250763810..d6663a785 100644 --- a/docs/ref/SUMMARY.md +++ b/docs/ref/SUMMARY.md @@ -14,6 +14,7 @@ - [nng_clock](./api/util/nng_clock.md) - [nng_id_map](./api/util/nng_id_map.md) - [nng_msleep](./api/util/nng_msleep.md) + - [nng_opts_parse](./api/util/nng_opts_parse.md) - [nng_random](./api/util/nng_random.md) - [nng_socket_pair](./api/util/nng_socket_pair.md) - [nng_strdup](./api/util/nng_strdup.md) diff --git a/docs/man/nng_opts_parse.3supp.adoc b/docs/ref/api/util/nng_opts_parse.md similarity index 67% rename from docs/man/nng_opts_parse.3supp.adoc rename to docs/ref/api/util/nng_opts_parse.md index beb9e1bf5..ddcea8321 100644 --- a/docs/man/nng_opts_parse.3supp.adoc +++ b/docs/ref/api/util/nng_opts_parse.md @@ -1,22 +1,12 @@ -= nng_opts_parse(3supp) -// -// Copyright 2018 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// +# nng_opts_parse -== NAME +## NAME -nng_opts_parse - parse command line options +nng_opts_parse --- parse command line options -== SYNOPSIS +## SYNOPSIS -[source, c] ----- +```c #include #include @@ -27,18 +17,19 @@ typedef struct nng_optspec { bool o_arg; // Option takes an argument if true } nng_optspec; -int nng_opts_parse(int argc, char *const *argv, const nng_optspec *spec, int *val, char **arg, int *idx); ----- +int nng_opts_parse(int argc, char *const *argv, + const nng_optspec *spec, int *val, char **arg, int *idx); +``` -== DESCRIPTION +## DESCRIPTION -The `nng_opts_parse()` is function is a supplemental function intended to -facilitate parsing command line arguments. -This function exists largely to stand in for `getopt()` from POSIX -systems, but it is available everywhere that _NNG_ is, and it includes -some capabilities missing from `getopt()`. +The {{i:`nng_opts_parse`}} function is a intended to facilitate parsing +{{i:command-line arguments}}. +This function exists largely to stand in for {{i:`getopt`}} from POSIX systems, +but it is available everywhere that _NNG_ is, and it includes +some capabilities missing from `getopt`. -The function parses arguments from `main()` (using _argc_ and _argv_), +The function parses arguments from `main` (using _argc_ and _argv_), starting at the index referenced by _idx_. (New invocations typically set the value pointed to by _idx_ to 1.) @@ -47,9 +38,9 @@ The value of the parsed option will be stored at the address indicated by _val_, and the value of _idx_ will be incremented to reflect the next option to parse. -TIP: For using this to parse command-line like strings that do not include -the command name itself, set the value referenced by _idx_ to zero -instead of one. +> [!TIP] +> For using this to parse command-line like strings that do not include +> the command name itself, set the value referenced by _idx_ to zero instead of one. If the option had an argument, a pointer to that is returned at the address referenced by _arg_. @@ -58,40 +49,39 @@ This function should be called repeatedly, until it returns either -1 (indicating the end of options is reached) or a non-zero error code is returned. -=== Option Specification +### Option Specification -The calling program must first create an array of `nng_optspec` structures +The calling program must first create an array of {{i:`nng_optspec`}} structures describing the options to be supported. This structure has the following members: -`o_name`:: +- `o_name`: The long style name for the option, such as "verbose". This will be parsed on the command line when it is prefixed with two dashes. It may be `NULL` if only a short option is to be supported. -`o_short`:: +- `o_short`: This is a single letter (at present only ASCII letters are supported). These options appear as just a single letter, and are prefixed with a single dash on the command line. The use of a slash in lieu of the dash is _not_ supported, in order to avoid confusion with path name arguments. This value may be set to 0 if no short option is needed. -`o_val`:: +- `o_val`: This is a numeric value that is unique to this option. - This value is assigned by the application program, and must be non-zero - for a valid option. + This value is assigned by the application program, and must be non-zero for a valid option. If this is zero, then it indicates the end of the specifications, and the rest of this structure is ignored. - The value will be returned to the caller in _val_ by `nng_opts_parse()` when + The value will be returned to the caller in _val_ by `nng_opts_parse` when this option is parsed from the command line. -`o_arg`:: +- `o_arg`: This value should be set to `true` if the option should take an argument. -=== Long Options +### Long Options Long options are parsed from the _argv_ array, and are indicated when the element being scanned starts with two dashes. @@ -102,28 +92,27 @@ the option as the next element in _argv_, or it can be appended to the option, separated from the option by an equals sign (`=`) or a colon (`:`). -=== Short Options +### Short Options -Short options appear by themselves in an _argv_ element, prefixed by a -dash (`-`). +Short options appear by themselves in an _argv_ element, prefixed by a dash (`-`). If the short option takes an argument, it can either be appended in the same element of _argv_, or may appear in the next _argv_ element. -NOTE: Option clustering, where multiple options can be crammed together in -a single _argv_ element, is not supported by this function (yet). +> [!NOTE] +> Option clustering, where multiple options can be crammed together in +> a single _argv_ element, is not supported by this function (yet). -=== Prefix Matching +### Prefix Matching When using long options, the parser will match if it is equal to a prefix of the `o_name` member of a option specification, provided that it do so unambiguously (meaning it must not match any other option specification.) -== EXAMPLE +## EXAMPLE The following program fragment demonstrates this function. -[source, c] ----- +```c enum { OPT_LOGFILE, OPT_VERBOSE }; char *logfile; // options to be set bool verbose; @@ -164,22 +153,15 @@ The following program fragment demonstrates this function. printf("Options error: %s\n", nng_strerror(rv)); exit(1); } ----- +``` -== RETURN VALUES +## RETURN VALUES This function returns 0 if an option parsed correctly, -1 if no more options are available to be parsed, or an error number otherwise. -== ERRORS +## ERRORS -[horizontal] -`NNG_EAMBIGUOUS`:: Parsed option matches more than one specification. -`NNG_ENOARG`:: Option requires an argument, but one is not present. -`NNG_EINVAL`:: An invalid (unknown) argument is present. - -== SEE ALSO - -[.text-left] -xref:nng_strerror.3.adoc[nng_strerror(3)], -xref:nng.7.adoc[nng(7)] +- `NNG_EAMBIGUOUS`: Parsed option matches more than one specification. +- `NNG_ENOARG`: Option requires an argument, but one is not present. +- `NNG_EINVAL`: An invalid (unknown) argument is present. From aa5e65c6ea098a67a59738fb057179c9acc914b6 Mon Sep 17 00:00:00 2001 From: Garrett D'Amore Date: Fri, 11 Oct 2024 23:22:11 -0700 Subject: [PATCH 061/222] Add ref for nng_opts_parse --- docs/ref/api/util/index.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/ref/api/util/index.md b/docs/ref/api/util/index.md index cc6ee7e2f..0650c21db 100644 --- a/docs/ref/api/util/index.md +++ b/docs/ref/api/util/index.md @@ -9,6 +9,7 @@ of other uses. - [nng_clock](nng_clock.md) --- get time - [nng_id_map](nng_id_map.md) --- identifier based mapping table - [nng_msleep](nng_msleep.md) --- sleep milliseconds +- [nng_opts_parse](nng_opts_parse.md) --- parse command line options - [nng_random](nng_random.md) --- get random number - [nng_socket_pair](nng_socket_pair.md) --- create a connected pair of BSD sockets - [nng_strdup](nng_strdup.md) --- duplicate string From 2952857a50ae4b64c8faae1c061999c03e64aca3 Mon Sep 17 00:00:00 2001 From: Garrett D'Amore Date: Fri, 11 Oct 2024 23:38:41 -0700 Subject: [PATCH 062/222] Convert nng_duration to mdbook. --- docs/man/nng_duration.5.adoc | 50 ------------------------------- docs/ref/SUMMARY.md | 1 + docs/ref/api/util/index.md | 1 + docs/ref/api/util/nng_duration.md | 33 ++++++++++++++++++++ 4 files changed, 35 insertions(+), 50 deletions(-) delete mode 100644 docs/man/nng_duration.5.adoc create mode 100644 docs/ref/api/util/nng_duration.md diff --git a/docs/man/nng_duration.5.adoc b/docs/man/nng_duration.5.adoc deleted file mode 100644 index fbd172b9f..000000000 --- a/docs/man/nng_duration.5.adoc +++ /dev/null @@ -1,50 +0,0 @@ -= nng_duration(5) -// -// Copyright 2018 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_duration - relative time in milliseconds - -== SYNOPSIS - -[source, c] ----- -#include - -typedef int32_t nng_duration; - -#define NNG_DURATION_INFINITE (-1) -#define NNG_DURATION_DEFAULT (-2) -#define NNG_DURATION_ZERO (0) ----- - -== DESCRIPTION - -An `nng_duration`(((duration))) is a relative time, measured in -milliseconds. -This type is most often used in conjunction with timers and timeouts. - -A couple of special values have been set aside, and carry special meanings. - -((`NNG_DURATION_DEFAULT`))::: -Indicates a context-specific default value should be used. - -((`NNG_DURATION_INFINITE`))::: -Effectively an infinite duration; used most often to disable timeouts. - -((`NNG_DURATION_ZERO`))::: -Zero length duration; used to perform a single polling operation. - -== SEE ALSO - -[.text-left] -xref:nng_options.5.adoc[nng_options(5)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/ref/SUMMARY.md b/docs/ref/SUMMARY.md index d6663a785..c994ecd5b 100644 --- a/docs/ref/SUMMARY.md +++ b/docs/ref/SUMMARY.md @@ -12,6 +12,7 @@ - [nng_alloc](./api/util/nng_alloc.md) - [nng_clock](./api/util/nng_clock.md) + - [nng_duration](./api/util/nng_duration.md) - [nng_id_map](./api/util/nng_id_map.md) - [nng_msleep](./api/util/nng_msleep.md) - [nng_opts_parse](./api/util/nng_opts_parse.md) diff --git a/docs/ref/api/util/index.md b/docs/ref/api/util/index.md index 0650c21db..0a3cb8916 100644 --- a/docs/ref/api/util/index.md +++ b/docs/ref/api/util/index.md @@ -7,6 +7,7 @@ of other uses. - [nng_alloc](nng_alloc.md) --- allocate memory - [nng_clock](nng_clock.md) --- get time +- [nng_duration](nng_duration.md) -- relative time in milliseconds - [nng_id_map](nng_id_map.md) --- identifier based mapping table - [nng_msleep](nng_msleep.md) --- sleep milliseconds - [nng_opts_parse](nng_opts_parse.md) --- parse command line options diff --git a/docs/ref/api/util/nng_duration.md b/docs/ref/api/util/nng_duration.md new file mode 100644 index 000000000..9ad762568 --- /dev/null +++ b/docs/ref/api/util/nng_duration.md @@ -0,0 +1,33 @@ +# nng_duration + +## NAME + +nng_duration --- relative time in milliseconds + +## SYNOPSIS + +```c +#include + +typedef int32_t nng_duration; + +#define NNG_DURATION_INFINITE (-1) +#define NNG_DURATION_DEFAULT (-2) +#define NNG_DURATION_ZERO (0) +``` + +## DESCRIPTION + +An {{i:`nng_duration`}}{{hi:duration}} is a relative time, measured in {{i:milliseconds}}. +This type is most often used in conjunction with timers and timeouts. + +A couple of special values have been set aside, and carry special meanings. + +- {{i:`NNG_DURATION_DEFAULT`}}: + Indicates a context-specific default value should be used. + +- {{i:`NNG_DURATION_INFINITE`}}: + Effectively an infinite duration; used most often to disable timeouts. + +- {{i:`NNG_DURATION_ZERO`}}: + Zero length duration; used to perform an immediate poll. From 172e18f8091a3312784e9bae7c165f3997390c5a Mon Sep 17 00:00:00 2001 From: Garrett D'Amore Date: Fri, 11 Oct 2024 23:48:07 -0700 Subject: [PATCH 063/222] Fix internal link for nng_opts_parse. --- docs/ref/api/util/nng_opts_parse.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/ref/api/util/nng_opts_parse.md b/docs/ref/api/util/nng_opts_parse.md index ddcea8321..40a0dd3d7 100644 --- a/docs/ref/api/util/nng_opts_parse.md +++ b/docs/ref/api/util/nng_opts_parse.md @@ -33,7 +33,7 @@ The function parses arguments from `main` (using _argc_ and _argv_), starting at the index referenced by _idx_. (New invocations typically set the value pointed to by _idx_ to 1.) -Options are parsed as specified by _spec_ (see <