diff options
Diffstat (limited to 'docs')
61 files changed, 122 insertions, 123 deletions
diff --git a/docs/man/libnng.3.adoc b/docs/man/libnng.3.adoc index 9c7109f3..b4bf9b0f 100644 --- a/docs/man/libnng.3.adoc +++ b/docs/man/libnng.3.adoc @@ -149,7 +149,7 @@ Asynchronous operations behave differently. These operations are initiated by the calling thread, but control returns immediately to the calling thread. When the operation is subsequently completed (regardless of whether this was successful or not), then a user supplied function -("`callback`") is executed. +is executed. A context structure, an xref:nng_aio.5.adoc[`nng_aio`], is allocated and associated with each asynchronous operation. diff --git a/docs/man/man7.desc b/docs/man/man7.desc index 0be7f47b..eae6694f 100644 --- a/docs/man/man7.desc +++ b/docs/man/man7.desc @@ -2,7 +2,7 @@ This sections documents various protocols and transports that are available in the distribution. (((protocol))) -Protocols represent "`patterns`" of communication, such as +Protocols implement communication patterns, such as request/reply, publish/subscribe, and so forth. A given xref:nng_socket.5.adoc[socket] is created with exactly one protocol, and that protocol defines the key behavior of the socket. diff --git a/docs/man/nn_bind.3compat.adoc b/docs/man/nn_bind.3compat.adoc index 7a9685bb..a4ca0043 100644 --- a/docs/man/nn_bind.3compat.adoc +++ b/docs/man/nn_bind.3compat.adoc @@ -1,6 +1,6 @@ = nn_bind(3compat) // -// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> +// Copyright 2020 Staysail Systems, Inc. <info@staysail.tech> // Copyright 2018 Capitar IT Group BV <info@capitar.com> // // This document is supplied under the terms of the MIT License, a @@ -26,10 +26,11 @@ int nn_bind(int sock, const char *url) The `nn_bind()` function arranges for the socket _sock_ to accept connections at the address specified by _url_. -An "`endpoint identifier`" for this socket's association with the _url_ is +An identifier for this socket's association with the _url_ is returned to the caller on success. -This ID can be used with xref:nn_shutdown.3compat.adoc[`nn_shutdown()`] to -"`unbind`" the socket from the address at _url_. +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_. diff --git a/docs/man/nn_connect.3compat.adoc b/docs/man/nn_connect.3compat.adoc index 2e669398..e498f8d3 100644 --- a/docs/man/nn_connect.3compat.adoc +++ b/docs/man/nn_connect.3compat.adoc @@ -26,10 +26,11 @@ int nn_connect(int sock, const char *url) The `nn_connect()` function arranges for the socket _sock_ to initiate connection to a peer at the address specified by _url_. -An "`endpoint identifier`" for this socket's association with the _url_ is +An identifier for this socket's association with the _url_ is returned to the caller on success. -This ID can be used with xref:nn_shutdown.3compat.adoc[`nn_shutdown()`] to -"`unbind`" the socket from the address at _url_. +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_. diff --git a/docs/man/nn_getsockopt.3compat.adoc b/docs/man/nn_getsockopt.3compat.adoc index 07da0a3c..743808b4 100644 --- a/docs/man/nn_getsockopt.3compat.adoc +++ b/docs/man/nn_getsockopt.3compat.adoc @@ -129,7 +129,7 @@ It can be changed to help with identifying different sockets with their different application-specific purposes. `NN_MAXTTL`:: -Maximum "`hops`" through proxies and devices a message may go through. +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. diff --git a/docs/man/nn_send.3compat.adoc b/docs/man/nn_send.3compat.adoc index 1a3efb0c..050bea17 100644 --- a/docs/man/nn_send.3compat.adoc +++ b/docs/man/nn_send.3compat.adoc @@ -38,7 +38,7 @@ 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 +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. diff --git a/docs/man/nn_setsockopt.3compat.adoc b/docs/man/nn_setsockopt.3compat.adoc index eadf6574..00371ef9 100644 --- a/docs/man/nn_setsockopt.3compat.adoc +++ b/docs/man/nn_setsockopt.3compat.adoc @@ -123,7 +123,7 @@ It can be changed to help with identifying different sockets with their different application-specific purposes. `NN_MAXTTL`:: -Maximum "`hops`" through proxies and devices a message may go through. +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. diff --git a/docs/man/nn_shutdown.3compat.adoc b/docs/man/nn_shutdown.3compat.adoc index eb9efd24..06a5cd5a 100644 --- a/docs/man/nn_shutdown.3compat.adoc +++ b/docs/man/nn_shutdown.3compat.adoc @@ -1,6 +1,6 @@ = nn_shutdown(3compat) // -// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> +// Copyright 2020 Staysail Systems, Inc. <info@staysail.tech> // Copyright 2018 Capitar IT Group BV <info@capitar.com> // // This document is supplied under the terms of the MIT License, a @@ -24,11 +24,11 @@ int nn_shutdown(int sock, int ep) == DESCRIPTION -The `nn_shutdown()` shuts down the "`endpoint`" _ep_ on the socket _sock_. +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. +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_. diff --git a/docs/man/nn_socket.3compat.adoc b/docs/man/nn_socket.3compat.adoc index bee2ffc0..c4bbb70a 100644 --- a/docs/man/nn_socket.3compat.adoc +++ b/docs/man/nn_socket.3compat.adoc @@ -40,7 +40,7 @@ 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. +`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: diff --git a/docs/man/nng.7.adoc b/docs/man/nng.7.adoc index 88c0266a..8511bdb0 100644 --- a/docs/man/nng.7.adoc +++ b/docs/man/nng.7.adoc @@ -102,10 +102,10 @@ messages may be dropped or reordered (Some protocols, such as xref:nng_req.7.adoc[_req_] may offer stronger guarantees by performing their own retry and validation schemes.) -Each socket can have zero, one, or many "endpoints", which are either +Each socket can have zero, one, or many endpoints, which are either _listeners_ or _dialers_. (A given socket may freely choose whether it uses listeners, dialers, or both.) -These "`endpoints`" provide access to underlying transports, such as TCP, etc. +These endpoints provide access to underlying transports, such as TCP, etc. Each endpoint is associated with a URL, which is a service address. For dialers, this will be the service address that will be contacted, whereas @@ -131,7 +131,7 @@ other than in a few specific circumstances. ==== Raw Mode (((cooked mode)))(((raw mode))) -Most applications will use _nng_ sockets in "`cooked`" mode. +Most applications will use _nng_ sockets in normal, or _cooked_, mode. This mode provides the full semantics of the protocol. For example, xref:nng_req.7.adoc[_req_] sockets will automatically match a reply to a request, and resend requests periodically if no reply @@ -140,7 +140,7 @@ was received. There are situations, such as with xref:nng_device.3.adoc[proxies], where it is desirable to bypass these semantics and simply pass messages to and from the socket with no extra semantic handling. -This is possible using "`raw`" mode sockets. +This is possible using _raw_ mode sockets. Raw mode sockets are generally constructed with a different function, such as xref:nng_req_open.3.adoc[`nng_req0_open_raw()`]. diff --git a/docs/man/nng_aio.5.adoc b/docs/man/nng_aio.5.adoc index 13cc49fc..414512c4 100644 --- a/docs/man/nng_aio.5.adoc +++ b/docs/man/nng_aio.5.adoc @@ -31,7 +31,7 @@ can only be used with a single operation at a time. Asynchronous operations are performed without blocking calling application threads. -Instead the application registers a "`callback`" function to be executed +Instead the application registers a callback function to be executed when the operation is complete (whether successfully or not). This callback will be executed exactly once. diff --git a/docs/man/nng_aio_finish.3.adoc b/docs/man/nng_aio_finish.3.adoc index f4c6edac..91ad188e 100644 --- a/docs/man/nng_aio_finish.3.adoc +++ b/docs/man/nng_aio_finish.3.adoc @@ -31,9 +31,9 @@ xref:nng_aio_result.3.adoc[`nng_aio_result()`]. This function causes the callback associated with the _aio_ to called. -IMPORTANT: It is mandatory that operation "`providers`" call this function -*EXACTLY ONCE* when they are finished with the operation. -After calling this function they *MUST NOT* perform any further accesses +IMPORTANT: It is mandatory that operation providers call this function +*exactly once* when they are finished with the operation. +After calling this function they *must not* perform any further accesses to the _aio_. NOTE: This function is only for I/O providers (those actually performing diff --git a/docs/man/nng_bus.7.adoc b/docs/man/nng_bus.7.adoc index 45c69f02..67b3d974 100644 --- a/docs/man/nng_bus.7.adoc +++ b/docs/man/nng_bus.7.adoc @@ -64,7 +64,7 @@ The _bus_ protocol has no protocol-specific options. === Protocol Headers -When using a xref:nng.7.adoc#raw_mode["`raw`"] _bus_ socket, received messages will +When using a _bus_ socket in xref:nng.7.adoc#raw_mode[raw mode], received messages will contain the incoming xref:nng_pipe.5.adoc[pipe] ID as the sole element in the header. If a message containing such a header is sent using a raw _bus_ socket, then, the message will be delivered to all connected pipes _except_ the one @@ -75,7 +75,7 @@ Such configurations are useful in the creation of rebroadcasters, and this capability prevents a message from being routed back to its source. If no header is present, then a message is sent to all connected pipes. -When using "`cooked`" _bus_ sockets, no message headers are present. +When using normal (cooked mode) _bus_ sockets, no message headers are present. == SEE ALSO diff --git a/docs/man/nng_compat.3compat.adoc b/docs/man/nng_compat.3compat.adoc index c70e1752..d259ced5 100644 --- a/docs/man/nng_compat.3compat.adoc +++ b/docs/man/nng_compat.3compat.adoc @@ -63,7 +63,7 @@ See the <<Caveats>> section below. === Compiling When compiling legacy _nanomsg_ applications, it will generally be -necessary to change the include search path to add the "`compat`" subdirectory +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`. diff --git a/docs/man/nng_ctx.5.adoc b/docs/man/nng_ctx.5.adoc index 86b89a33..b097d866 100644 --- a/docs/man/nng_ctx.5.adoc +++ b/docs/man/nng_ctx.5.adoc @@ -24,7 +24,7 @@ typedef struct nng_ctx_s nng_ctx == DESCRIPTION -An `nng_ctx`(((context))) is a handle to an underlying "`context`" object, +An `nng_ctx`(((context))) is a handle to an underlying context object, which keeps the protocol state for some stateful protocols. The purpose of a separate context object is to permit applications to share a single socket, with its various underlying @@ -51,7 +51,7 @@ See the protocol-specific documentation for further details about whether contexts are supported, and details about what options are supported for contexts. -Protocols that make use of contexts will also have a "`default`" context +Protocols that make use of contexts will also have a default context that is used when the socket global operations are used. Operations using the global context will generally not interfere with any other contexts, except that certain socket options may affect socket diff --git a/docs/man/nng_ctx_send.3.adoc b/docs/man/nng_ctx_send.3.adoc index 3284ac8a..8724c1aa 100644 --- a/docs/man/nng_ctx_send.3.adoc +++ b/docs/man/nng_ctx_send.3.adoc @@ -29,14 +29,14 @@ xref:nng_ctx.5.adoc[context] _ctx_ asynchronously. The message to send must have previously been set on the _aio_ using the xref:nng_aio_set_msg.3.adoc[`nng_aio_set_msg()`] function. -The function assumes "`ownership`" of the message. +The function assumes ownership of the message. If the message was successfully queued for delivery to the socket, then the _aio_ will be completed, and xref:nng_aio_result.3.adoc[`nng_aio_result()`] will return zero. In this case the socket will dispose of the message when it is finished with it. -NOTE: The operation will be "`completed`", and the callback associated +NOTE: The operation will be completed, and the callback associated with the _aio_ executed, as soon as the socket accepts the message for sending. This does _not_ indicate that the message was actually delivered, as it diff --git a/docs/man/nng_cv_until.3supp.adoc b/docs/man/nng_cv_until.3supp.adoc index 9300b295..87ba879c 100644 --- a/docs/man/nng_cv_until.3supp.adoc +++ b/docs/man/nng_cv_until.3supp.adoc @@ -37,7 +37,7 @@ 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`". +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. diff --git a/docs/man/nng_cv_wait.3supp.adoc b/docs/man/nng_cv_wait.3supp.adoc index 69a21208..1d9c16be 100644 --- a/docs/man/nng_cv_wait.3supp.adoc +++ b/docs/man/nng_cv_wait.3supp.adoc @@ -36,7 +36,7 @@ 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`". +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. diff --git a/docs/man/nng_cv_wake.3supp.adoc b/docs/man/nng_cv_wake.3supp.adoc index a42191c6..6ee2945d 100644 --- a/docs/man/nng_cv_wake.3supp.adoc +++ b/docs/man/nng_cv_wake.3supp.adoc @@ -1,6 +1,6 @@ = nng_cv_wake(3supp) // -// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> +// Copyright 2020 Staysail Systems, Inc. <info@staysail.tech> // Copyright 2018 Capitar IT Group BV <info@capitar.com> // // This document is supplied under the terms of the MIT License, a @@ -36,8 +36,8 @@ 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 problem known as the "`thundering herd`" when there are many -waiters, as they are all woken simultaneously. +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 diff --git a/docs/man/nng_cv_wake1.3supp.adoc b/docs/man/nng_cv_wake1.3supp.adoc index 2dd23129..4f8b8326 100644 --- a/docs/man/nng_cv_wake1.3supp.adoc +++ b/docs/man/nng_cv_wake1.3supp.adoc @@ -36,8 +36,7 @@ _cv_ was allocated. NOTE: The caller should already have set the condition that the waiters will check, while holding the mutex. -TIP: While this function avoids the "`thundering herd`" problem, the -caller cannot predict which waiter will be woken, and so the design must +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()`]. diff --git a/docs/man/nng_device.3.adoc b/docs/man/nng_device.3.adoc index a8a6ce27..b36d2e80 100644 --- a/docs/man/nng_device.3.adoc +++ b/docs/man/nng_device.3.adoc @@ -54,7 +54,7 @@ back to the sender. === Forwarders When both sockets are valid, then the result is a ((forwarder)) or proxy. -In this case sockets _s1_ and _s2_ must be "`compatible`" with each other, +In this case sockets _s1_ and _s2_ must be compatible with each other, which is to say that they should represent the opposite halves of a two protocol pattern, or both be the same protocol for a single protocol pattern. diff --git a/docs/man/nng_dial.3.adoc b/docs/man/nng_dial.3.adoc index 690537a5..00df455f 100644 --- a/docs/man/nng_dial.3.adoc +++ b/docs/man/nng_dial.3.adoc @@ -39,7 +39,7 @@ When the pipe is closed, the dialer attempts to re-establish the connection. Dialers will also periodically retry a connection automatically if an attempt to connect asynchronously fails. -TIP: While it is convenient to think of dialers as "`clients`", the relationship +TIP: While it is convenient to think of dialers as clients, the relationship between the listener or dialer is orthogonal to any server or client status that might be associated with a given protocol. For example, a xref:nng_req.7.adoc[_req_] diff --git a/docs/man/nng_dialer.5.adoc b/docs/man/nng_dialer.5.adoc index b484e185..eb4d7c10 100644 --- a/docs/man/nng_dialer.5.adoc +++ b/docs/man/nng_dialer.5.adoc @@ -25,7 +25,7 @@ typedef struct nng_dialer_s nng_dialer; == DESCRIPTION (((dialer))) -An `nng_dialer` is a handle to a "`dialer`" object, which is responsible for +An `nng_dialer` is a handle to a dialer object, which is responsible for creating a single xref:nng_pipe.5.adoc[`nng_pipe`] at a time by establishing an outgoing connection. @@ -35,8 +35,8 @@ destroyed. Dialer objects are created by the xref:nng_dialer_create.3.adoc[`nng_dialer_create()`] -or xref:nng_dial.3.adoc[`nng_dial()`] functions, and are always "`owned`" -by a single xref:nng_socket.5.adoc[`nng_socket`]. +or xref:nng_dial.3.adoc[`nng_dial()`] functions, and are always associated +with a single xref:nng_socket.5.adoc[`nng_socket`]. IMPORTANT: The `nng_dialer` structure is always passed by value (both for input parameters and return values), and should be treated opaquely. @@ -56,7 +56,7 @@ challenging communications problems. Dialer objects may be destroyed by the xref:nng_dialer_close.3.adoc[`nng_dialer_close()`] function. -They are also closed when their "`owning`" socket is closed. +They are also closed when their associated socket is closed. [[NNG_DIALER_INITIALIZER]] === Initialization diff --git a/docs/man/nng_dialer_create.3.adoc b/docs/man/nng_dialer_create.3.adoc index 497af2ab..d4df92f4 100644 --- a/docs/man/nng_dialer_create.3.adoc +++ b/docs/man/nng_dialer_create.3.adoc @@ -39,7 +39,7 @@ Dialers will also periodically retry a connection automatically if an attempt to connect asynchronously fails. -TIP: While it is convenient to think of dialers as "`clients`", the relationship +TIP: While it is convenient to think of dialers as clients, the relationship between the listener or dialer is orthogonal to any server or client status that might be associated with a given protocol. For example, a xref:nng_req.7.adoc[_req_] diff --git a/docs/man/nng_http_handler_collect_body.3http.adoc b/docs/man/nng_http_handler_collect_body.3http.adoc index e969af8b..4507c418 100644 --- a/docs/man/nng_http_handler_collect_body.3http.adoc +++ b/docs/man/nng_http_handler_collect_body.3http.adoc @@ -36,7 +36,7 @@ The collection is enabled if _want_ is true. Furthermore, the data that the client may sent is limited by the value of _maxsz_. If the client attempts to send more data than _maxsz_, then the -request will be terminated with a 400 "`Bad Request`" status. +request will be terminated with a 400 `Bad Request` status. TIP: Limiting the size of incoming request data can provide protection against denial of service attacks, as a buffer of the client-supplied diff --git a/docs/man/nng_http_res_alloc.3http.adoc b/docs/man/nng_http_res_alloc.3http.adoc index ba2c9b5f..f546d151 100644 --- a/docs/man/nng_http_res_alloc.3http.adoc +++ b/docs/man/nng_http_res_alloc.3http.adoc @@ -28,8 +28,8 @@ int nng_http_res_alloc(nng_http_res **resp); The `nng_http_res_alloc()` function allocates a new HTTP response structure and stores a pointer to it in __resp__. The response will be initialized -with status code 200 (`NNG_HTTP_STATUS_OK`), and a reason phrase of `"OK`", -and HTTP protocol version `"HTTP/1.1`". +with status code 200 (`NNG_HTTP_STATUS_OK`), and a reason phrase of `OK`, +and HTTP protocol version `HTTP/1.1`. TIP: When an error response is needed, consider using xref:nng_http_res_alloc_error.3http.adoc[`nng_http_res_alloc_error()`] instead. diff --git a/docs/man/nng_http_res_get_reason.3http.adoc b/docs/man/nng_http_res_get_reason.3http.adoc index 3ac05bcb..a4167a0a 100644 --- a/docs/man/nng_http_res_get_reason.3http.adoc +++ b/docs/man/nng_http_res_get_reason.3http.adoc @@ -26,7 +26,7 @@ const char *nng_http_res_get_reason(nng_http_res *res); == DESCRIPTION The `nng_http_res_get_reason()` returns a string representing the -"`reason phrase`" associated with the response _res_. +reason associated with the response _res_. This is a human-readable explanation of the status code that would be obtained from xref:nng_http_res_get_status.3http.adoc[`nng_http_res_get_status()`]. diff --git a/docs/man/nng_http_res_get_status.3http.adoc b/docs/man/nng_http_res_get_status.3http.adoc index d8c79ed5..0ad9092a 100644 --- a/docs/man/nng_http_res_get_status.3http.adoc +++ b/docs/man/nng_http_res_get_status.3http.adoc @@ -97,7 +97,7 @@ enum { ---- TIP: When displaying status information to users (or logging such information), -consider also including the "`reason phrase`" obtained with +consider also including the reason obtained with xref:nng_http_res_get_reason.3http.adoc[`nng_http_res_get_reason()`]. == RETURN VALUES diff --git a/docs/man/nng_http_res_set_reason.3http.adoc b/docs/man/nng_http_res_set_reason.3http.adoc index 28a64497..50699de2 100644 --- a/docs/man/nng_http_res_set_reason.3http.adoc +++ b/docs/man/nng_http_res_set_reason.3http.adoc @@ -25,7 +25,7 @@ int nng_http_res_set_reason(nng_http_res *res, const char *reason); == DESCRIPTION -The `nng_http_res_set_reason()` sets the human readable "`reason phrase`" +The `nng_http_res_set_reason()` sets the human readable reason associated with the response _res_ to _reason_. If the value of _reason_ is `NULL` (the default), then a default reason diff --git a/docs/man/nng_http_res_set_status.3http.adoc b/docs/man/nng_http_res_set_status.3http.adoc index 2083c3b7..e57764d4 100644 --- a/docs/man/nng_http_res_set_status.3http.adoc +++ b/docs/man/nng_http_res_set_status.3http.adoc @@ -102,7 +102,7 @@ enum { Please see the relevant HTTP RFCs for the semantics and correct use of these status codes. -TIP: It is a good idea to also set the "`reason phrase`" with +TIP: It is a good idea to also set the reason message with xref:nng_http_res_set_reason.3http.adoc[`nng_http_set_reason()`]. This will help any humans who may have to diagnose a failure. diff --git a/docs/man/nng_listen.3.adoc b/docs/man/nng_listen.3.adoc index 4b120ecb..0e26ec69 100644 --- a/docs/man/nng_listen.3.adoc +++ b/docs/man/nng_listen.3.adoc @@ -38,7 +38,7 @@ pipes, which may be open concurrently. The _flags_ argument is ignored, but reserved for future use. -TIP: While it is convenient to think of listeners as "`servers`", the +TIP: While it is convenient to think of listeners as servers, the relationship between the listener or dialer is orthogonal to any server or client status that might be associated with a given protocol. For example, a xref:nng_req.7.adoc[_req_] diff --git a/docs/man/nng_listener.5.adoc b/docs/man/nng_listener.5.adoc index 70dd86c0..66eb736d 100644 --- a/docs/man/nng_listener.5.adoc +++ b/docs/man/nng_listener.5.adoc @@ -25,15 +25,15 @@ typedef struct nng_listener_s nng_listener; == DESCRIPTION (((listener))) -An `nng_listener` is a handle to a "`listener`" object, which is responsible for +An `nng_listener` is a handle to a listener object, which is responsible for creating xref:nng_pipe.5.adoc[`nng_pipe`] objects by accepting incoming connections. A given listener object may create many pipes at the same time, much like an HTTP server can have many connections to multiple clients simultaneously. Listener objects are created by the xref:nng_listener_create.3.adoc[`nng_listener_create()`] -or xref:nng_listen.3.adoc[`nng_listen()`] functions, and are always "`owned`" -by a single xref:nng_socket.5.adoc[`nng_socket`]. +or xref:nng_listen.3.adoc[`nng_listen()`] functions, and are always associated +with a single xref:nng_socket.5.adoc[`nng_socket`]. IMPORTANT: The `nng_listener` structure is always passed by value (both for input parameters and return values), and should be treated opaquely. @@ -53,7 +53,7 @@ challenging communications problems. Listener objects may be destroyed by the xref:nng_listener_close.3.adoc[`nng_listener_close()`] function. -They are also closed when their "`owning`" socket is closed. +They are also closed when their associated socket is closed. [[NNG_LISTENER_INITIALIZER]] === Initialization diff --git a/docs/man/nng_listener_create.3.adoc b/docs/man/nng_listener_create.3.adoc index 0d766cc3..edf19af7 100644 --- a/docs/man/nng_listener_create.3.adoc +++ b/docs/man/nng_listener_create.3.adoc @@ -35,7 +35,7 @@ to the socket _s_. Unlike dialers, listeners generally can create many pipes, which may be open concurrently. -TIP: While it is convenient to think of listeners as "`servers`", the +TIP: While it is convenient to think of listeners as servers, the relationship between the listener or dialer is orthogonal to any server or client status that might be associated with a given protocol. For example, a xref:nng_req.7.adoc[_req_] socket might have associated dialers, diff --git a/docs/man/nng_msg_insert.3.adoc b/docs/man/nng_msg_insert.3.adoc index ff69b8a4..25f98fce 100644 --- a/docs/man/nng_msg_insert.3.adoc +++ b/docs/man/nng_msg_insert.3.adoc @@ -1,6 +1,6 @@ = nng_msg_insert(3) // -// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> +// Copyright 2020 Staysail Systems, Inc. <info@staysail.tech> // Copyright 2018 Capitar IT Group BV <info@capitar.com> // // This document is supplied under the terms of the MIT License, a @@ -20,9 +20,9 @@ nng_msg_insert - prepend to message body #include <nng/nng.h> int nng_msg_insert(nng_msg *msg, const void *val, size_t size); -int nng_msg_insert(nng_msg *msg, uint16_t val16); -int nng_msg_insert(nng_msg *msg, uint32_t val32); -int nng_msg_insert(nng_msg *msg, uint64_t val64); +int nng_msg_insert_u16(nng_msg *msg, uint16_t val16); +int nng_msg_insert_u32(nng_msg *msg, uint32_t val32); +int nng_msg_insert_u64(nng_msg *msg, uint64_t val64); ---- == DESCRIPTION @@ -33,9 +33,9 @@ The first function prepends _size_ bytes, copying them from _val_. The remaining functions prepend the specified value (such as _val32_) in network-byte order (big-endian). -TIP: These functions make use of pre-allocated "`headroom`" in the message if -available, so it can often avoid performing any reallocation. -Applications should use this instead of reallocating and copying message +TIP: These functions make use of space pre-allocated in front of the +message body if available, so they can often avoid performing any reallocation. +Applications should use these instead of reallocating and copying message content themselves, in order to benefit from this capability. == RETURN VALUES diff --git a/docs/man/nng_mtx_alloc.3supp.adoc b/docs/man/nng_mtx_alloc.3supp.adoc index 696c3e56..45bbfac2 100644 --- a/docs/man/nng_mtx_alloc.3supp.adoc +++ b/docs/man/nng_mtx_alloc.3supp.adoc @@ -34,7 +34,7 @@ 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 "`own`" the semaphore. +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. diff --git a/docs/man/nng_mtx_lock.3supp.adoc b/docs/man/nng_mtx_lock.3supp.adoc index 33504da1..91fd2ab5 100644 --- a/docs/man/nng_mtx_lock.3supp.adoc +++ b/docs/man/nng_mtx_lock.3supp.adoc @@ -40,8 +40,9 @@ It is a programming error for the owner of a mutex to attempt to reacquire it. **** -_nng_ offers neither a "`trylock`" operation, nor recursive mutexes. -This is by design, as _nng_ itself does not use such things, +_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. diff --git a/docs/man/nng_options.5.adoc b/docs/man/nng_options.5.adoc index 915096ec..aea8c6ff 100644 --- a/docs/man/nng_options.5.adoc +++ b/docs/man/nng_options.5.adoc @@ -98,15 +98,15 @@ choose a random ephemeral port instead. (((raw mode))) (((cooked mode))) (`bool`) -This read-only option indicates whether the socket is in "`raw`" mode. -If `true`, the socket is in "`raw`" mode, and if `false` the socket is -in "`cooked`" mode. +This read-only option indicates whether the socket is in raw mode. +If `true`, the socket is in raw mode, and if `false` the socket is +in normal mode. + Raw mode sockets generally do not have any protocol-specific semantics applied to them; instead the application is expected to perform such semantics itself. -(For example, in "`cooked`" mode a xref:nng_rep.7.adoc[_rep_] socket would +(For example, in normal mode a xref:nng_rep.7.adoc[_rep_] socket would automatically copy message headers from a received message to the corresponding -reply, whereas in "`raw`" mode this is not done.) +reply, whereas in raw mode this is not done.) See xref:nng.7.adoc#raw_mode[Raw Mode] for more details. [[NNG_OPT_RECONNMINT]] @@ -284,7 +284,7 @@ in the library itself. ((`NNG_OPT_MAXTTL`)):: (`int`) (((time-to-live))) -This is the maximum number of "`hops`" a message may traverse across +This is the maximum number of times a message may traverse across a xref:nng_device.3.adoc[`nng_device()`] forwarders. The intention here is to prevent ((forwarding loops)) in device chains. When this is supported, it can have a value between 1 and 255, inclusive. diff --git a/docs/man/nng_pair.7.adoc b/docs/man/nng_pair.7.adoc index 62075753..9a035823 100644 --- a/docs/man/nng_pair.7.adoc +++ b/docs/man/nng_pair.7.adoc @@ -40,7 +40,7 @@ The xref:nng_pair_open.3.adoc[`nng_pair_open()`] functions create a _pair_ socke Normally, this pattern will block when attempting to send a message if no peer is able to receive the message. -NOTE: Even though this mode may appear to be "`reliable`", because back-pressure +NOTE: Even though this mode may appear to be reliable, because back-pressure prevents discarding messages most of the time, there are topologies involving _devices_ (see xref:nng_device.3.adoc[`nng_device()`]) or raw mode sockets (see xref:nng_options.5.adoc#NNG_OPT_RAW[`NNG_OPT_RAW`]) where diff --git a/docs/man/nng_pipe.5.adoc b/docs/man/nng_pipe.5.adoc index c951ecb2..920fb2c0 100644 --- a/docs/man/nng_pipe.5.adoc +++ b/docs/man/nng_pipe.5.adoc @@ -1,6 +1,6 @@ = nng_pipe(5) // -// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> +// Copyright 2020 Staysail Systems, Inc. <info@staysail.tech> // Copyright 2018 Capitar IT Group BV <info@capitar.com> // // This document is supplied under the terms of the MIT License, a @@ -25,7 +25,7 @@ typedef struct nng_pipe_s nng_pipe; == DESCRIPTION (((pipe)))(((connection))) -An `nng_pipe` is a handle to a "`pipe`", which can be thought of as a single +An `nng_pipe` is a handle to a pipe object, which can be thought of as a single connection. (In most cases this is actually the case -- the pipe is an abstraction for a single TCP or IPC connection.) @@ -43,12 +43,11 @@ source of a message is needed, or when more control is required over message delivery. Pipe objects are created by dialers (xref:nng_dialer.5.adoc[`nng_dialer`] objects) -and listeners (xref:nng_listener.5.adoc[`nng_listener`] objects), which can be -thought of as "`owning`" the pipe. +and listeners (xref:nng_listener.5.adoc[`nng_listener`] objects). Pipe objects may be destroyed by the xref:nng_pipe_close.3.adoc[`nng_pipe_close()`] function. -They are also closed when their "`owning`" dialer or listener is closed, +They are also closed when the dialer or listener that created them is closed, or when the remote peer closes the underlying connection. [[NNG_PIPE_INITIALIZER]] diff --git a/docs/man/nng_pipe_get.3.adoc b/docs/man/nng_pipe_get.3.adoc index cc7a7efb..51a8debf 100644 --- a/docs/man/nng_pipe_get.3.adoc +++ b/docs/man/nng_pipe_get.3.adoc @@ -49,7 +49,7 @@ 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. +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()`]. diff --git a/docs/man/nng_pipe_getopt.3.adoc b/docs/man/nng_pipe_getopt.3.adoc index c1b7dca6..648abbcc 100644 --- a/docs/man/nng_pipe_getopt.3.adoc +++ b/docs/man/nng_pipe_getopt.3.adoc @@ -51,7 +51,7 @@ 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. +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()`]. diff --git a/docs/man/nng_pipe_socket.3.adoc b/docs/man/nng_pipe_socket.3.adoc index e5da1d55..755ed776 100644 --- a/docs/man/nng_pipe_socket.3.adoc +++ b/docs/man/nng_pipe_socket.3.adoc @@ -25,14 +25,14 @@ nng_socket nng_pipe_socket(nng_pipe p); == DESCRIPTION The `nng_pipe_socket()` function returns the xref:nng_socket.5.adoc[`nng_socket`] -that owns the pipe _p_. +associated with the pipe _p_. NOTE: The returned socket may be closed or in the process of closing, in which case it will not be usable with other functions. == RETURN VALUES -This function returns the socket that "`owns`" the pipe. +This function returns the socket associated with the pipe. == ERRORS diff --git a/docs/man/nng_recv.3.adoc b/docs/man/nng_recv.3.adoc index b430fe9d..ef1f2756 100644 --- a/docs/man/nng_recv.3.adoc +++ b/docs/man/nng_recv.3.adoc @@ -34,7 +34,7 @@ The _flags_ is a bit mask that may contain any of the following values: by the socket _s_, or any configured timer expires. `NNG_FLAG_ALLOC`:: - If this flag is present, then a "`((zero-copy))`" mode is used. + If this flag is present, then a ((zero-copy)) mode is used. In this case the caller must set the value of _data_ to the location of another pointer (of type `void *`), and the _sizep_ pointer must be set to a location to receive the size of the message body. diff --git a/docs/man/nng_rep.7.adoc b/docs/man/nng_rep.7.adoc index 07cd8dfd..1c22f3e3 100644 --- a/docs/man/nng_rep.7.adoc +++ b/docs/man/nng_rep.7.adoc @@ -30,7 +30,7 @@ The request is resent if no reply arrives, until a reply is received or the request times out. TIP: This protocol is useful in setting up RPC-like services. -It is also "`reliable`", in that a the requester will keep retrying until +It is also reliable, in that a the requester will keep retrying until a reply is received. The _rep_ protocol is the replier side, and the diff --git a/docs/man/nng_req.7.adoc b/docs/man/nng_req.7.adoc index ada83c65..28765083 100644 --- a/docs/man/nng_req.7.adoc +++ b/docs/man/nng_req.7.adoc @@ -40,7 +40,7 @@ some reason.) (((load-balancing))) The requester generally only has one outstanding request at a time unless -in "`raw`" mode (via +in raw mode (via xref:nng_options.5.adoc#NNG_OPT_RAW[`NNG_OPT_RAW`]), and it will generally attempt to spread work requests to different peer repliers. @@ -109,7 +109,7 @@ The following protocol-specific option is available. (((backtrace))) This protocol uses a _backtrace_ in the header. -This form uses a "`stack`" of 32-bit big-endian identifiers. +This form uses a stack of 32-bit big-endian identifiers. There *must* be at least one identifier, the __request ID__, which will be the last element in the array, and *must* have the most significant bit set. @@ -125,7 +125,7 @@ peer from which it received the message. (This peer ID, except for the most significant bit, has meaning only to the forwarding node itself.) -It may help to think of prepending a peer ID as "`pushing`" a peer ID onto the +It may help to think of prepending a peer ID as pushing a peer ID onto the front of the stack of headers for the message. (It will use the peer ID it popped from the front to determine the next intermediate destination @@ -134,7 +134,7 @@ for the reply.) When a reply message is created, it is created using the same headers that the request contained. -A forwarding node can "`pop`" the peer ID it originally pushed on the +A forwarding node can pop the peer ID it originally pushed on the message, stripping it from the front of the message as it does so. When the reply finally arrives back at the initiating requester, it diff --git a/docs/man/nng_send_aio.3.adoc b/docs/man/nng_send_aio.3.adoc index 6ae66b17..e8fc2005 100644 --- a/docs/man/nng_send_aio.3.adoc +++ b/docs/man/nng_send_aio.3.adoc @@ -29,14 +29,14 @@ xref:nng_socket.5.adoc[socket] _s_ asynchronously. The message to send must have previously been set on the _aio_ using the xref:nng_aio_set_msg.3.adoc[`nng_aio_set_msg()`] function. -The function assumes "`ownership`" of the message. +The function assumes ownership of the message. If the message was successfully queued for delivery to the socket, then the _aio_ will be completed, and xref:nng_aio_result.3.adoc[`nng_aio_result()`] will return zero. In this case the socket will dispose of the message when it is finished with it. -NOTE: The operation will be "`completed`", and the callback associated +NOTE: The operation will be completed, and the callback associated with the _aio_ executed, as soon as the socket accepts the message for sending. This does _not_ indicate that the message was actually delivered, as it diff --git a/docs/man/nng_sendmsg.3.adoc b/docs/man/nng_sendmsg.3.adoc index 1fe46d42..5b7a73ee 100644 --- a/docs/man/nng_sendmsg.3.adoc +++ b/docs/man/nng_sendmsg.3.adoc @@ -27,7 +27,7 @@ int nng_sendmsg(nng_socket s, nng_msg *msg, int flags); The `nng_sendmsg()` sends message _msg_ using the socket _s_. If the function returns zero, indicating it has accepted the message for -delivery, then the _msg_ is "`owned`" by the socket _s_, and the caller +delivery, then the _msg_ is owned by the socket _s_, and the caller must not make any further use of it. The socket will free the message when it is finished. diff --git a/docs/man/nng_sleep_aio.3.adoc b/docs/man/nng_sleep_aio.3.adoc index 323e6039..2a3cf4f2 100644 --- a/docs/man/nng_sleep_aio.3.adoc +++ b/docs/man/nng_sleep_aio.3.adoc @@ -1,6 +1,6 @@ = nng_sleep_aio(3) // -// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> +// Copyright 2020 Staysail Systems, Inc. <info@staysail.tech> // Copyright 2018 Capitar IT Group BV <info@capitar.com> // // This document is supplied under the terms of the MIT License, a @@ -24,7 +24,7 @@ void nng_sleep_aio(nng_duration msec, nng_aio *aio); == DESCRIPTION -The `nng_sleep_aio()` function performs an asynchronous "`sleep`", +The `nng_sleep_aio()` function provides an asynchronous delay mechanism, causing the callback for _aio_ to be executed after _msec_ milliseconds. If the sleep finishes completely, the result will always be zero. diff --git a/docs/man/nng_sockaddr.5.adoc b/docs/man/nng_sockaddr.5.adoc index 827f6ac8..a3c9d8a3 100644 --- a/docs/man/nng_sockaddr.5.adoc +++ b/docs/man/nng_sockaddr.5.adoc @@ -57,7 +57,7 @@ This structure is actually a union, with different members for different types of addresses. Every member structure has as its first element a `uint16_t` field -containing the "`((address family))`". +containing the ((address family)). This overlaps the `s_family` member of the union, and indicates which specific member should be used. diff --git a/docs/man/nng_sockaddr_inproc.5.adoc b/docs/man/nng_sockaddr_inproc.5.adoc index 529e8758..69d1319a 100644 --- a/docs/man/nng_sockaddr_inproc.5.adoc +++ b/docs/man/nng_sockaddr_inproc.5.adoc @@ -42,8 +42,7 @@ The following structure members are present: This field will always have the value ((`NNG_AF_INPROC`)). `sa_name`:: - This field holds an arbitrary C string, which is the "`name`" of - the address. + This field holds an arbitrary C string, which is the name of the address. The string must be `NUL` terminated, but no other restrictions exist. TIP: In order to ensure maximum compatibility, applications should avoid diff --git a/docs/man/nng_sockaddr_ipc.5.adoc b/docs/man/nng_sockaddr_ipc.5.adoc index 52a57cec..e3a7878e 100644 --- a/docs/man/nng_sockaddr_ipc.5.adoc +++ b/docs/man/nng_sockaddr_ipc.5.adoc @@ -49,7 +49,7 @@ The following structure members are present: For Windows systems, this is the path name of the Named Pipe, without the leading `\\.pipe\` portion, which will be automatically added. -NOTE: At this time, there is no support for Linux "`abstract sockets`". +NOTE: At this time, there is no support for Linux abstract sockets. TIP: In order to ensure maximum compatibility, applications should avoid hard coding the size of the `sa_path` member explicitly, but use the diff --git a/docs/man/nng_sockaddr_zt.5.adoc b/docs/man/nng_sockaddr_zt.5.adoc index 61c77644..70bb78af 100644 --- a/docs/man/nng_sockaddr_zt.5.adoc +++ b/docs/man/nng_sockaddr_zt.5.adoc @@ -61,7 +61,7 @@ The following structure members are present: caller's own node number be used. `sa_port`:: - This field holds the "`port number`" used by the + This field holds the port number used by the xref:nng_zerotier.7.adoc[_zt_] transport to distinguish different sockets. This value in native byte order.(((port number, ZeroTier))) diff --git a/docs/man/nng_socket.5.adoc b/docs/man/nng_socket.5.adoc index ab17f8f2..5c565720 100644 --- a/docs/man/nng_socket.5.adoc +++ b/docs/man/nng_socket.5.adoc @@ -24,14 +24,14 @@ typedef struct nng_socket_s nng_socket; == DESCRIPTION -An `nng_socket`(((socket))) is a handle to an underlying "`socket`" object. +An `nng_socket`(((socket))) is a handle to an underlying socket object. All communication between the application and remote Scalability Protocol peers is done through sockets. A given socket can have multiple dialers (xref:nng_dialer.5.adoc[`nng_dialer`]) and/or listeners (xref:nng_listener.5.adoc[`nng_listener`]), and multiple pipes (xref:nng_pipe.5.adoc[`nng_pipe`]), and may be connected to multiple transports at the same time. -However, a given socket will have exactly one "`protocol`" associated with it, +However, a given socket will have exactly one protocol associated with it, and is responsible for any state machines or other protocol-specific logic. IMPORTANT: The `nng_socket` structure is always passed by value (both diff --git a/docs/man/nng_stream.5.adoc b/docs/man/nng_stream.5.adoc index 7d426a92..9144deb5 100644 --- a/docs/man/nng_stream.5.adoc +++ b/docs/man/nng_stream.5.adoc @@ -41,7 +41,7 @@ xref:nng_stream_dialer_dial.3str.adoc[`nng_stream_dialer_dial()`] or by accepting in incoming connection with xref:nng_stream_listener_accept.3str.adoc[`nng_stream_listener_accept()`]. -Byte streams are "`reliable`" in that data +Byte streams are reliable in that data will not be delivered out of order, or with portions missing. Data can be sent using diff --git a/docs/man/nng_stream_dialer.5.adoc b/docs/man/nng_stream_dialer.5.adoc index 5c1d2e0b..eef23a3d 100644 --- a/docs/man/nng_stream_dialer.5.adoc +++ b/docs/man/nng_stream_dialer.5.adoc @@ -26,7 +26,7 @@ typedef struct nng_stream_dialer nng_stream_dialer; == DESCRIPTION (((byte stream, dialer))) -An `nng_stream_dialer` is a handle to a "`dialer`" for byte streams, +An `nng_stream_dialer` is a handle to a dialer for byte streams, and is responsible for creating xref:nng_stream.5.adoc[`nng_stream`] objects (corresponding to connected byte streams) by connecting to remote peers. diff --git a/docs/man/nng_stream_listener.5.adoc b/docs/man/nng_stream_listener.5.adoc index f7b85e55..b774a1b9 100644 --- a/docs/man/nng_stream_listener.5.adoc +++ b/docs/man/nng_stream_listener.5.adoc @@ -26,7 +26,7 @@ typedef struct nng_stream_listener nng_stream_listener; == DESCRIPTION (((IPC, listener))) -An `nng_stream_listener` is a handle to a byte stream "`listener`", +An `nng_stream_listener` is a handle to a byte stream listener, which is responsible for accepting incoming connections and creating corresponding xref:nng_stream.5.adoc[`nng_stream`] from them. diff --git a/docs/man/nng_surveyor.7.adoc b/docs/man/nng_surveyor.7.adoc index c82a6a92..6b38c0eb 100644 --- a/docs/man/nng_surveyor.7.adoc +++ b/docs/man/nng_surveyor.7.adoc @@ -105,7 +105,7 @@ The following protocol-specific options is available. === Protocol Headers (((backtrace))) -This form uses a "`stack`" of 32-bit big-endian identifiers. +This form uses a stack of 32-bit big-endian identifiers. There *must* be at least one identifier, the __survey ID__, which will be the last element in the array, and *must* have the most significant bit set. @@ -121,7 +121,7 @@ peer from which it received the message. (This peer ID, except for the most significant bit, has meaning only to the forwarding node itself.) -It may help to think of prepending a peer ID as "`pushing`" a peer ID onto the +It may help to think of prepending a peer ID as pushing a peer ID onto the front of the stack of headers for the message. (It will use the peer ID it popped from the front to determine the next intermediate destination @@ -130,7 +130,7 @@ for the response.) When a response message is created, it is created using the same headers that the survey contained. -A forwarding node can "`pop`" the peer ID it originally pushed on the +A forwarding node can pop the peer ID it originally pushed on the message, stripping it from the front of the message as it does so. When the response finally arrives back at the initiating surveyor, it diff --git a/docs/man/nng_thread_create.3supp.adoc b/docs/man/nng_thread_create.3supp.adoc index 0822a963..129bddea 100644 --- a/docs/man/nng_thread_create.3supp.adoc +++ b/docs/man/nng_thread_create.3supp.adoc @@ -35,19 +35,19 @@ 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 so-called "`green threads`" or coroutines. +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 "`block`". +_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`" -threads capable of performing blocking I/O operations using normal blocking +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 diff --git a/docs/man/nng_tls_config_alloc.3tls.adoc b/docs/man/nng_tls_config_alloc.3tls.adoc index 7af51586..43fbe2ce 100644 --- a/docs/man/nng_tls_config_alloc.3tls.adoc +++ b/docs/man/nng_tls_config_alloc.3tls.adoc @@ -54,7 +54,7 @@ xref:nng_tls_config_hold.3tls.adoc[`nng_tls_config_hold()`] and may be decremented with xref:nng_tls_config_free.3tls.adoc[`nng_tls_config_free()`]. -Also note that a TLS configuration object becomes "`read-only`" after it +Also note that a TLS configuration object becomes read-only after it is first used with a service. After this points, attempts to apply further changes to the configuration will result in `NNG_EBUSY`. diff --git a/docs/man/nng_url.5.adoc b/docs/man/nng_url.5.adoc index 9fed7e0a..2e01b9de 100644 --- a/docs/man/nng_url.5.adoc +++ b/docs/man/nng_url.5.adoc @@ -47,7 +47,7 @@ The fields are as follows: [horizontal] `u_rawurl`:: The unparsed URL string. This will never be `NULL`. -`u_scheme`:: The URL scheme, such as "`http`" or "`inproc`". Always lower case. This will never be `NULL`. +`u_scheme`:: The URL scheme, such as "http" or "inproc". Always lower case. This will never be `NULL`. `u_userinfo`:: This username and password if supplied in the URL string. Will be `NULL` when not present. `u_host`:: The full host part of the URL, including the port if present (separated by a colon.) `u_hostname`:: The name of the host, and may be the empty string in some cases. diff --git a/docs/man/nng_zerotier.7.adoc b/docs/man/nng_zerotier.7.adoc index 31988079..3ec5d9e1 100644 --- a/docs/man/nng_zerotier.7.adoc +++ b/docs/man/nng_zerotier.7.adoc @@ -1,6 +1,6 @@ = nng_zerotier(7) // -// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> +// Copyright 2020 Staysail Systems, Inc. <info@staysail.tech> // Copyright 2018 Capitar IT Group BV <info@capitar.com> // // This document is supplied under the terms of the MIT License, a @@ -138,7 +138,7 @@ The network is most likely not available. The following transport options are available: ((`NNG_OPT_ZT_HOME`)):: - (string) This option represents the "`home directory`", where the transport + (string) This option represents the home directory, where the transport can store (and reuse) persistent state, such as key materials, node identity, and federation membership. This option must be set before the ZeroTier transport is first used. @@ -189,12 +189,12 @@ in this fashion. ((`NNG_OPT_ZT_PING_TIME`)):: (xref:nng_duration.5.adoc[`nng_duration`]) If no traffic has been received from the ZeroTier peer after this - period of time, then a "`ping`" message is sent to check if the peer + period of time, then a ping message is sent to check if the peer is still alive. [[NNG_OPT_ZT_PING_TRIES]] ((`NNG_OPT_ZT_PING_TRIES`)):: - (`int`) If this number of consecutive "`ping`" requests are sent to the + (`int`) If this number of consecutive ping requests are sent to the peer with no response (and no other intervening traffic), then the peer is assumed to be dead and the connection is closed. @@ -209,15 +209,14 @@ in this fashion. [[NNG_OPT_ZT_ORBIT]] ((`NNG_OPT_ZT_ORBIT`))(((orbit, ZeroTier)))(((federation,ZeroTier))):: (`uint64_t[2]`) Write-only array of two `uint64_t` values, - indicating the ID of a ZeroTier "`moon`", and the node ID of the root server + indicating the ID of a ZeroTier <em>moon</em>, and the node ID of the root server for that moon. (The ID may be zero if the moon ID is the same as its root server ID, which is conventional.) [[NNG_OPT_ZT_DEORBIT]] ((`NNG_OPT_ZT_DEORBIT`)):: - (`uint64_t`) Write-only option indicating the moon - ID to "`deorbit`". If the node is not already orbiting the moon, then - this has no effect. + (`uint64_t`) Write-only option indicating the moon ID to deorbit. + If the node is not already orbiting the moon, then this has no effect. == SEE ALSO |