From b08d7a398d68c9ebe4781e5c4cb5cc8b945f9653 Mon Sep 17 00:00:00 2001 From: Garrett D'Amore Date: Tue, 10 Apr 2018 16:21:52 -0700 Subject: man page updates for tip --- man/tip/index.html | 119 ++++++ man/tip/libnng.3.html | 131 ++++++ man/tip/nng.7.html | 108 +++-- man/tip/nng_aio_stop.3.html | 25 +- man/tip/nng_alloc.3.html | 17 +- man/tip/nng_bus.7.html | 6 +- man/tip/nng_bus_open.3.html | 11 +- man/tip/nng_clock.3supp.html | 608 ++++++++++++++++++++++++++ man/tip/nng_ctx.5.html | 731 ++++++++++++++++++++++++++++++++ man/tip/nng_ctx_close.3.html | 599 ++++++++++++++++++++++++++ man/tip/nng_ctx_getopt.3.html | 728 ++++++++++++++++++++++++++++++++ man/tip/nng_ctx_open.3.html | 629 +++++++++++++++++++++++++++ man/tip/nng_ctx_recv.3.html | 644 ++++++++++++++++++++++++++++ man/tip/nng_ctx_send.3.html | 672 +++++++++++++++++++++++++++++ man/tip/nng_ctx_setopt.3.html | 704 +++++++++++++++++++++++++++++++ man/tip/nng_cv_alloc.3supp.html | 594 ++++++++++++++++++++++++++ man/tip/nng_cv_free.3supp.html | 571 +++++++++++++++++++++++++ man/tip/nng_cv_until.3supp.html | 635 ++++++++++++++++++++++++++++ man/tip/nng_cv_wait.3supp.html | 631 +++++++++++++++++++++++++++ man/tip/nng_cv_wake.3supp.html | 611 +++++++++++++++++++++++++++ man/tip/nng_cv_wake1.3supp.html | 612 +++++++++++++++++++++++++++ man/tip/nng_device.3.html | 20 +- man/tip/nng_dialer_getopt.3.html | 60 ++- man/tip/nng_dialer_setopt.3.html | 17 +- man/tip/nng_free.3.html | 8 +- man/tip/nng_getopt.3.html | 46 +- man/tip/nng_listener_getopt.3.html | 70 +-- man/tip/nng_listener_setopt.3.html | 18 +- man/tip/nng_msleep.3supp.html | 588 ++++++++++++++++++++++++++ man/tip/nng_mtx_alloc.3supp.html | 594 ++++++++++++++++++++++++++ man/tip/nng_mtx_free.3supp.html | 572 +++++++++++++++++++++++++ man/tip/nng_mtx_lock.3supp.html | 617 +++++++++++++++++++++++++++ man/tip/nng_mtx_unlock.3supp.html | 587 ++++++++++++++++++++++++++ man/tip/nng_options.5.html | 5 +- man/tip/nng_opts_parse.3supp.html | 772 ++++++++++++++++++++++++++++++++++ man/tip/nng_pair.7.html | 16 +- man/tip/nng_pair_open.3.html | 14 +- man/tip/nng_pipe_getopt.3.html | 39 +- man/tip/nng_pub.7.html | 6 +- man/tip/nng_pub_open.3.html | 11 +- man/tip/nng_pull.7.html | 6 +- man/tip/nng_pull_open.3.html | 11 +- man/tip/nng_push.7.html | 4 +- man/tip/nng_push_open.3.html | 11 +- man/tip/nng_random.3supp.html | 574 +++++++++++++++++++++++++ man/tip/nng_rep.7.html | 40 +- man/tip/nng_rep_open.3.html | 7 +- man/tip/nng_req.7.html | 42 +- man/tip/nng_req_open.3.html | 15 +- man/tip/nng_respondent.7.html | 6 +- man/tip/nng_respondent_open.3.html | 12 +- man/tip/nng_setopt.3.html | 13 - man/tip/nng_strdup.3.html | 597 ++++++++++++++++++++++++++ man/tip/nng_strfree.3.html | 607 ++++++++++++++++++++++++++ man/tip/nng_sub.7.html | 6 +- man/tip/nng_sub_open.3.html | 11 +- man/tip/nng_surveyor.7.html | 9 +- man/tip/nng_surveyor_open.3.html | 11 +- man/tip/nng_thread_create.3supp.html | 663 +++++++++++++++++++++++++++++ man/tip/nng_thread_destroy.3supp.html | 586 ++++++++++++++++++++++++++ 60 files changed, 16445 insertions(+), 232 deletions(-) create mode 100644 man/tip/nng_clock.3supp.html create mode 100644 man/tip/nng_ctx.5.html create mode 100644 man/tip/nng_ctx_close.3.html create mode 100644 man/tip/nng_ctx_getopt.3.html create mode 100644 man/tip/nng_ctx_open.3.html create mode 100644 man/tip/nng_ctx_recv.3.html create mode 100644 man/tip/nng_ctx_send.3.html create mode 100644 man/tip/nng_ctx_setopt.3.html create mode 100644 man/tip/nng_cv_alloc.3supp.html create mode 100644 man/tip/nng_cv_free.3supp.html create mode 100644 man/tip/nng_cv_until.3supp.html create mode 100644 man/tip/nng_cv_wait.3supp.html create mode 100644 man/tip/nng_cv_wake.3supp.html create mode 100644 man/tip/nng_cv_wake1.3supp.html create mode 100644 man/tip/nng_msleep.3supp.html create mode 100644 man/tip/nng_mtx_alloc.3supp.html create mode 100644 man/tip/nng_mtx_free.3supp.html create mode 100644 man/tip/nng_mtx_lock.3supp.html create mode 100644 man/tip/nng_mtx_unlock.3supp.html create mode 100644 man/tip/nng_opts_parse.3supp.html create mode 100644 man/tip/nng_random.3supp.html create mode 100644 man/tip/nng_strdup.3.html create mode 100644 man/tip/nng_strfree.3.html create mode 100644 man/tip/nng_thread_create.3supp.html create mode 100644 man/tip/nng_thread_destroy.3supp.html (limited to 'man') diff --git a/man/tip/index.html b/man/tip/index.html index 83262e62..afa001b9 100644 --- a/man/tip/index.html +++ b/man/tip/index.html @@ -440,6 +440,7 @@ body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-b
  • Section 3: Library Functions
  • Section 3compat: Compatible Library Functions
  • Section 3http: Supplemental HTTP Functions
    • +
  • Section 3supp: Supplemental Functions
  • Section 3tls: Supplemental TLS Functions
  • Section 5: Macros and Types
  • Section 7: Protocols and Transports
    • @@ -573,6 +574,30 @@ callable by applications.

    close socket

    +

    nng_ctx_close(3)

    +

    close context

    + + +

    nng_ctx_getopt(3)

    +

    get context option

    + + +

    nng_ctx_open(3)

    +

    create context

    + + +

    nng_ctx_recv(3)

    +

    receive message using context asynchronously

    + + +

    nng_ctx_send(3)

    +

    send message using context asynchronously

    + + +

    nng_ctx_setopt(3)

    +

    set context option

    + +

    nng_device(3)

    send message

    @@ -789,10 +814,18 @@ callable by applications.

    sleep asynchronously

    +

    nng_strdup(3)

    +

    duplicate string

    + +

    nng_strerror(3)

    return an error description

    +

    nng_strfree(3)

    +

    free memory

    + +

    nng_sub_open(3)

    create sub socket

    @@ -1114,6 +1147,88 @@ that are available.

    +

    Section 3supp: Supplemental Functions

    +
    +
    +

    This section documents supplemental functions that are available. +These functions are not intrinsic to building applications with +this library, but their presence may facilitate writing portable applications.

    +
    + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

    nng_clock(3supp)

    get time

    nng_cv_alloc(3supp)

    allocate condition variable

    nng_cv_free(3supp)

    free condition variable

    nng_cv_until(3supp)

    wait for condition or timeout

    nng_cv_wait(3supp)

    wait for condition

    nng_cv_wake(3supp)

    wake all waiters

    nng_cv_wake1(3supp)

    wake one waiter

    nng_msleep(3supp)

    sleep milliseconds

    nng_mtx_alloc(3supp)

    allocate mutex

    nng_mtx_free(3supp)

    free mutex

    nng_mtx_lock(3supp)

    lock mutex

    nng_mtx_unlock(3supp)

    lock mutex

    nng_opts_parse(3supp)

    parse command line options

    nng_random(3supp)

    get random number

    nng_thread_create(3supp)

    create thread

    nng_thread_destroy(3supp)

    reap thread

    +
    +
    +

    Section 3tls: Supplemental TLS Functions

    @@ -1178,6 +1293,10 @@ that are available.

    asynchronous I/O handle

    +

    nng_ctx(5)

    +

    protocol context

    + +

    nng_dialer(5)

    dialer

    diff --git a/man/tip/libnng.3.html b/man/tip/libnng.3.html index 645e7d70..3758d308 100644 --- a/man/tip/libnng.3.html +++ b/man/tip/libnng.3.html @@ -517,7 +517,9 @@ body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-b
  • Asynchronous Operations
  • Protocols
  • Transports
    • +
  • Protocol Contexts
  • URL Object
    • +
  • Supplemental API
  • HTTP Support
  • TLS Configuration Objects
    • @@ -569,10 +571,18 @@ intended to solve common communication problems in distributed applications.

    free memory

    +

    nng_strdup()

    +

    duplicate string

    + +

    nng_strerror()

    return an error description

    +

    nng_strfree()

    +

    free string

    + +

    nng_version()

    report library version

    @@ -1050,6 +1060,47 @@ Only a single asynchronous operation may be associated with an
    +

    Protocol Contexts

    +
    +

    The following functions are useful to separate the protocol processing +from a socket object, into a separate context. +This can allow multiple contexts to be created on a single socket for +concurrent applications.

    +
    + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + +

    nng_ctx_close()

    close context

    nng_ctx_getopt()

    get context option

    nng_ctx_open()

    create context

    nng_ctx_recv()

    receive message using context asynchronously

    nng_ctx_send()

    send message using context asynchronously

    nng_ctx_setopt()

    set context option

    +
    +

    URL Object

    Common functionality is supplied for parsing and handling @@ -1077,6 +1128,86 @@ universal resource locators (URLS).

    +

    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.

    +
    + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

    nng_clock()

    get time

    nng_cv_alloc()

    allocate condition variable

    nng_cv_free()

    free condition variable

    nng_cv_until()

    wait for condition or timeout

    nng_cv_wait()

    wait for condition

    nng_cv_wake()

    wake all waiters

    nng_cv_wake()

    wake one waiter

    nng_msleep()

    sleep for milliseconds

    nng_mtx_alloc()

    allocate mutex

    nng_mtx_free()

    free mutex

    nng_mtx_lock()

    lock mutex

    nng_mtx_unlock()

    unlock mutex

    nng_opts_parse()

    parse command line options

    nng_random()

    get random number

    nng_thread_create()

    create thread

    nng_thread_destroy()

    reap thread

    +
    +

    HTTP Support

    The library may be configured with support for HTTP, and this will diff --git a/man/tip/nng.7.html b/man/tip/nng.7.html index f412f39f..c3685bac 100644 --- a/man/tip/nng.7.html +++ b/man/tip/nng.7.html @@ -646,53 +646,94 @@ other languages please check the website.

    Conceptual Overview

    -

    nng presents a socket view of networking. The sockets are constructed -using protocol-specific functions, as a given socket implements precisely -one nng protocol.

    +

    nng presents a socket view of networking. +The sockets are constructed using protocol-specific functions, as a given +socket implements precisely one nng protocol.

    Each socket can be used to send and receive messages (if the protocol) -supports it, and implements the appropriate protocol semantics. For -example, nng_sub(7) sockets automatically filter incoming +supports it, and implements the appropriate protocol semantics. +For example, sub sockets automatically filter incoming messages to discard those for topics that have not been subscribed.

    nng sockets are message oriented, so that messages are either delivered -wholly, or not at all. Partial delivery is not possible. Furthermore, -nng does not provide any other delivery or ordering guarantees; -messages may be dropped or reordered. (Some protocols, such as -nng_req(7) may offer stronger guarantees by -performing their own retry and validation schemes.)

    +wholly, or not at all. Partial delivery is not possible. +Furthermore, nng does not provide any other delivery or ordering guarantees; +messages may be dropped or reordered +(Some protocols, such as 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 -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.

    +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.

    -

    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 -for listeners this is where the listener will bind and watch for new -connections.

    +

    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 +for listeners this is where the listener will accept new connections.

    -

    Endpoints do not themselves transport data. They are instead responsible -for the creation of pipes, which can be thought of as message-oriented, -connected, streams. Pipes frequently correspond to a single underlying -byte stream — for example both IPC and TCP transports implement their -pipes using a 1:1 relationship with a connected socket.

    +

    Endpoints do not themselves transport data. +They are instead responsible for the creation of pipes, which can be +thought of as message-oriented connected streams. +Pipes frequently correspond to a single underlying byte stream. +For example both IPC and TCP transports implement their +pipes using a 1:1 relationship with a connected operating system socket.

    -

    Endpoints create pipes as needed. Listeners will create them when a new -client connection request arrives, and dialers will generally create one, -then wait for it to disconnect before reconnecting.

    +

    Endpoints create pipes as needed. +Listeners will create them when a new client connection request arrives, +and dialers will generally create one, then wait for it to disconnect before +reconnecting.

    Most applications should not have to worry about endpoints or pipes at all; the socket abstraction should provide all the functionality needed other than in a few specific circumstances.

    +
    +

    +=== Raw Mode

    +
    +
    +

    +Most applications will use nng sockets in “cooked” mode. +This mode provides the full semantics of the protocol. +For example, req sockets will automatically +match a reply to a request, and resend requests periodically if no reply +was received.

    +
    +
    +

    There are situations, such as with 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.

    +
    +
    +

    Raw mode sockets are generally constructed with a different function, +such as nng_req0_open_raw(). +Using these sockets, the application can simply send and receive messages, +and is responsible for supplying any additional socket semantics. +Typically this means that the application will need to inspect message +headers on incoming messages, and supply them on outgoing messages.

    +
    +
    + + + + + +
    + + +The nng_device() function only works with raw mode +sockets, but as it only forwards the messages, no additional application +processing is needed. +
    +

    URLs

    @@ -745,6 +786,23 @@ slash (/) separators are removed from the path.

    them is believed to improve both the usability and security of nng applications, without violating RFC 3986 itself.

    +
    + + + + + +
    + + +Port numbers may be service names in some instances, but it is recommended +that numeric port numbers be used when known. +If service names are used, it is recommended that they follow the naming +conventions for C identifiers, and not be longer than 32 characters in length. +This will maximize compatibility across systems and minimize opportunities for +confusion when they are parsed on different systems. +
    +
    diff --git a/man/tip/nng_aio_stop.3.html b/man/tip/nng_aio_stop.3.html index bed7b404..126f1ce3 100644 --- a/man/tip/nng_aio_stop.3.html +++ b/man/tip/nng_aio_stop.3.html @@ -541,9 +541,28 @@ associated with aio by aborting with NNG_ECANCELED, and th for it to complete or to be completely aborted.

    -

    This is logically the equivalent of nng_aio_cancel() -followed by nng_aio_wait(), except that the asynchronous -I/O handle may not be used for any further operations.

    +

    If an operation is in progress when this function is called, that operation +is canceled and the callback function is not allowed to run.

    +
    +
    +

    If the callback function is already running when this function is called, +then it is allowed to complete before returning to the caller.

    +
    +
    +

    No new operations will be started on this aio.

    +
    +
    + + + + + +
    + + +Calling this function means that the operation may be aborted without +completing its callback function. +
    diff --git a/man/tip/nng_alloc.3.html b/man/tip/nng_alloc.3.html index d73217df..5f8e7a7e 100644 --- a/man/tip/nng_alloc.3.html +++ b/man/tip/nng_alloc.3.html @@ -546,11 +546,11 @@ case it can be directly passed to nng_send()NNG_FLAG_ALLOC. Alternatively, it can be freed when no longer needed using nng_free().

    -
    +
    - + Do not use the system free() function to release this memory. @@ -566,20 +566,17 @@ to a crash or other undesirable and unpredictable behavior.

    RETURN VALUES

    -

    This function returns 0 on success, and non-zero otherwise.

    +

    This function returns a pointer to the allocated memory on success, +and NULL otherwise.

    ERRORS

    -
    -
    -
    NNG_ENOMEM
    -
    -

    Insufficient free memory exists.

    -
    -
    +
    +

    No errors are returned, but a NULL return value should be +treated the same as NNG_ENOMEM.

    diff --git a/man/tip/nng_bus.7.html b/man/tip/nng_bus.7.html index 54adf490..4c4342d3 100644 --- a/man/tip/nng_bus.7.html +++ b/man/tip/nng_bus.7.html @@ -530,9 +530,7 @@ body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-b
    -
    #include <nng/protocol/bus0/bus.h>
-
-int nng_bus0_open(nng_socket *s);
    +
    #include <nng/protocol/bus0/bus.h>
    @@ -590,7 +588,7 @@ the more likely that message loss is to occur.

    Socket Operations

    -

    The nng_bus0_open() call creates a bus socket. +

    The nng_bus0_open() functions create a bus socket. This socket may be used to send and receive messages. Sending messages will attempt to deliver to each directly connected peer.

    diff --git a/man/tip/nng_bus_open.3.html b/man/tip/nng_bus_open.3.html index 09b02fe8..e8aee826 100644 --- a/man/tip/nng_bus_open.3.html +++ b/man/tip/nng_bus_open.3.html @@ -528,7 +528,9 @@ body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-b 
    #include <nng/nng.h>
 #include <nng/protocol/bus0/bus.h>
 
-int nng_bus0_open(nng_socket *s);
    +int nng_bus0_open(nng_socket *s); + +int nng_bus0_open_raw(nng_socket *s);
    @@ -540,13 +542,18 @@ body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-b

    The nng_bus0_open() function creates a bus version 0 socket and returns it at the location pointed to by s.

    +
    +

    The nng_bus0_open_raw() function creates a bus version 0 +socket in +raw mode, and returns it at the location pointed to by s.

    +

    RETURN VALUES

    -

    This function returns 0 on success, and non-zero otherwise.

    +

    These functions return 0 on success, and non-zero otherwise.

    diff --git a/man/tip/nng_clock.3supp.html b/man/tip/nng_clock.3supp.html new file mode 100644 index 00000000..1cd2fde3 --- /dev/null +++ b/man/tip/nng_clock.3supp.html @@ -0,0 +1,608 @@ +--- +version: tip +layout: refman +--- + + + + + + + +nng_clock(3supp) + + + + + + + +
    +
    +

    SYNOPSIS

    +
    +
    +
    +
    #include <nng/nng.h>
+#include <nng/supplemental/util/platform.h>
+
+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.

    +
    +
    + + + + + +
    + + +The reference time will be the same for a given program, +but different programs may have different references. +
    +
    +
    + + + + + +
    + + +This function is intended mostly to help with setting appropriate +timeouts using nng_cv_until(3supp). +
    +
    +
    +
    +
    +

    RETURN VALUES

    +
    +
    +

    Milliseconds since reference time.

    +
    +
    +
    +
    +

    ERRORS

    +
    +
    +

    None.

    +
    +
    +
    +
    +

    SEE ALSO

    +
    +
    +

    nng_sleep_aio(3), +nng_strerror(3), +nng_cv_until(3supp), +nng_msleep(3supp), +nng_duration(5), +nng(7)

    +
    +
    +
    +
    + + diff --git a/man/tip/nng_ctx.5.html b/man/tip/nng_ctx.5.html new file mode 100644 index 00000000..a218059e --- /dev/null +++ b/man/tip/nng_ctx.5.html @@ -0,0 +1,731 @@ +--- +version: tip +layout: refman +--- + + + + + + + +nng_ctx(5) + + + + + + + +
    +
    +

    SYNOPSIS

    +
    +
    +
    +
    #include <nng/nng.h>
+
+typedef uint32_t nng_ctx
    +
    +
    +
    +
    +
    +

    DESCRIPTION

    +
    +
    +

    An nng_ctx 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 +dialers, +listeners, +and pipes, +while still benefiting from separate state tracking.

    +
    +
    +

    For example, a req context will contain the request ID +of any sent request, a timer to retry the request on failure, and so forth. +A separate context on the same socket can have similar data, but corresponding +to a completely different request.

    +
    +
    +

    All contexts share the same socket, and so some options, as well as the +underlying transport details, will be common to all contexts on that socket.

    +
    +
    + + + + + +
    + + +Not every protocol supports separate contexts. +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 +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 +global behavior.

    +
    +
    +

    +Historically, applications wanting to use a stateful protocol concurrently +would have to resort to raw mode sockets, which bypasses +much of the various protocol handling, leaving it to up to the application +to do so. +Contexts make it possible to still benefit from advanced protocol handling, +including timeouts, retries, and matching requests to responses, while doing so +concurrently.

    +
    +
    + + + + + +
    + + +Raw mode sockets do not support contexts, since +there is generally no state tracked for them, and thus contexts make no sense. +
    +
    +
    + + + + + +
    + + +Contexts are an excellent mechanism to use when building concurrent +applications, and should be used in lieu of +raw mode sockets when possible. +
    +
    +
    + + + + + +
    + + +Use of file descriptor polling (with descriptors +obtained using the +NNG_OPT_RECVFD or +NNG_OPT_SENDFD options) while contexts +are in use on the same socket is not supported, and may lead to unpredictable +behavior. +These asynchronous methods should not be mixed on the same socket. +
    +
    +
    +
    +
    +

    EXAMPLE

    +
    +
    +

    The following program fragment demonstrates the use of contexts to implement +a concurrent rep service that simply echos messages back +to the sender.

    +
    +
    +
    +
    
+struct echo_context {
+    nng_ctx *ctx;
+    nng_aio *aio;
+    enum { INIT, RECV, SEND } state;
+};
+
+void
+echo(void *arg)
+{
+    struct echo_context *ec = arg;
+
+    switch (ec->state) {
+    case INIT:
+        ec->state = RECV;
+        nng_ctx_recv(ec->ctx, ec->aio);
+        return;
+    case RECV:
+        if (nng_aio_result(ec->aio) != 0) {
+            // ... handle error
+        }
+        // We reuse the message on the ec->aio
+        ec->state = SEND;
+        nng_ctx_send(ec->ctx, ec->aio);
+        return;
+    case SEND:
+        if (nng_aio_result(ec->aio) != 0) {
+            // ... handle error
+        }
+        ec->state = RECV;
+        nng_ctx_recv(ec->ctx, ec->aio);
+        return;
+    }
+}
    +
    +
    +
    +

    Given the above fragment, the following example shows setting up the +service. It assumes that the socket has already been +created and any transports set up as well with functions such as +nng_dial() +or nng_listen().

    +
    +
    +
    +
    #define CONCURRENCY 1024
+
+echo_context ecs[CONCURRENCY];
+
+void
+start_echo_service(nng_socket rep_socket)
+{
+    for (int i = 0; i < CONCURRENCY; i++) {
+        // error checks elided for clarity
+        nng_ctx_open(ec[i].ctx, rep_socket)
+        nng_aio_alloc(ec[i].aio, echo, &e[i]);
+        ec[i].state = INIT;
+        echo(&ec[i]); // start it running
+    }
+}
    +
    +
    +
    +
    +
    +

    SEE ALSO

    +
    +
    +

    libnng(3), +nng_ctx_close(3), +nng_ctx_open(3), +nng_ctx_getopt(3), +nng_ctx_recv(3), +nng_ctx_send(3), +nng_ctx_setopt(3), +nng_dialer(5), +nng_listener(5), +nng_socket(5), +nng_options(5), +nng(7)

    +
    +
    +
    +
    + + diff --git a/man/tip/nng_ctx_close.3.html b/man/tip/nng_ctx_close.3.html new file mode 100644 index 00000000..6f486e0a --- /dev/null +++ b/man/tip/nng_ctx_close.3.html @@ -0,0 +1,599 @@ +--- +version: tip +layout: refman +--- + + + + + + + +nng_ctx_close(3) + + + + + + + +
    +
    +

    SYNOPSIS

    +
    +
    +
    +
    #include <nng/nng.h>
+
+int nng_ctx_close(nng_ctx ctx);
    +
    +
    +
    +
    +
    +

    DESCRIPTION

    +
    +
    +

    The nng_ctx_close() function closes the context ctx. +Messages that have been submitted for sending may be flushed or delivered, +depending upon the transport and the setting of the +NNG_OPT_LINGER option.

    +
    +
    +

    Further attempts to use the context after this call returns will result +in NNG_ECLOSED. +Threads waiting for operations on the context when this +call is executed may also return with an NNG_ECLOSED result.

    +
    +
    + + + + + +
    + + +Closing the socket associated with ctx +(using nng_close()) also closes this context. +
    +
    +
    +
    +
    +

    RETURN VALUES

    +
    +
    +

    This function returns 0 on success, and non-zero otherwise.

    +
    +
    +
    +
    +

    ERRORS

    +
    +
    +
    +
    NNG_ECLOSED
    +
    +

    The context ctx is already closed or was never opened.

    +
    +
    +
    +
    +
    +
    +

    SEE ALSO

    +
    +
    +

    nng_ctx_open(3), +nng_strerror(3), +nng_ctx(5), +nng(7)

    +
    +
    +
    +
    + + diff --git a/man/tip/nng_ctx_getopt.3.html b/man/tip/nng_ctx_getopt.3.html new file mode 100644 index 00000000..3ad0bad2 --- /dev/null +++ b/man/tip/nng_ctx_getopt.3.html @@ -0,0 +1,728 @@ +--- +version: tip +layout: refman +--- + + + + + + + +nng_ctx_getopt(3) + + + + + + + +
    +
    +

    SYNOPSIS

    +
    +
    +
    +
    #include <nng/nng.h>
+
+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

    +
    +
    +

    +The nng_ctx_getopt() functions are used to retrieve option values for +the context ctx. +The actual options that may be retrieved in this way vary. +A number of them are documented in nng_options(5).

    +
    +
    + + + + + +
    + + +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.

    +
    +
    + + + + + +
    + + +Generally, it will be easier to use one of the typed forms instead. +
    +
    +
    +

    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 referened 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 verifyng 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.

    +
    +
    +
    +

    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 durations +(such as timeouts), stored in durp as a number of milliseconds. +(The special value NNG_DUR_INFINITE means an infinite amount of time, and +the special value NNG_DUR_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 nng_strdup() +and consequently must be freed by the caller using +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

    +
    +
    +
    +
    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

    +
    +
    +

    nng_ctx_setopt(3), +nng_strdup(3), +nng_strerror(3), +nng_strfree(3), +nng_duration(5), +nng_ctx(5), +nng_options(5), +nng(7)

    +
    +
    +
    +
    + + diff --git a/man/tip/nng_ctx_open.3.html b/man/tip/nng_ctx_open.3.html new file mode 100644 index 00000000..20b582cd --- /dev/null +++ b/man/tip/nng_ctx_open.3.html @@ -0,0 +1,629 @@ +--- +version: tip +layout: refman +--- + + + + + + + +nng_ctx_open(3) + + + + + + + +
    +
    +

    SYNOPSIS

    +
    +
    +
    +
    #include <nng/nng.h>
+
+int nng_ctx_open(nng_ctx *ctxp, nng_socket s);
    +
    +
    +
    +
    +
    +

    DESCRIPTION

    +
    +
    +

    The nng_ctx0_open() function creates a separate context to be used with +the socket s, +and returns it at the location pointed by ctxp.

    +
    +
    + + + + + +
    + + +Not every protocol supports creation of separate contexts. +
    +
    +
    +

    Contexts allow the independent and concurrent use of stateful operations +using the same socket. +For example, two different contexts created on a rep +socket can each receive requests, and send replies to them, without any +regard to or interference with each other.

    +
    +
    +

    +TIP: Using contexts is an excellent way to write simpler concurrent +applications, while retaining the benefits of the protocol-specific +advanced processing, avoiding the need to bypass that with +raw mode sockets.

    +
    +
    + + + + + +
    + + +Use of contexts with raw mode sockets is +nonsensical, and not supported. +
    +
    +
    +
    +
    +

    RETURN VALUES

    +
    +
    +

    This function returns 0 on success, and non-zero otherwise.

    +
    +
    +
    +
    +

    ERRORS

    +
    +
    +
    +
    NNG_ENOMEM
    +
    +

    Insufficient memory is available.

    +
    +
    NNG_ENOTSUP
    +
    +

    The protocol does not support separate contexts, or the socket was opened in raw mode.

    +
    +
    +
    +
    +
    +
    +

    SEE ALSO

    +
    +
    +

    nng_ctx_close(3), +nng_ctx_getopt(3), +nng_ctx_recv(3), +nng_ctx_send(3), +nng_ctx_setopt(3), +nng_strerror(3), +nng_ctx(5), +nng_socket(5), +nng_rep(7), +nng_req(7), +nng(7)

    +
    +
    +
    +
    + + diff --git a/man/tip/nng_ctx_recv.3.html b/man/tip/nng_ctx_recv.3.html new file mode 100644 index 00000000..76ac07a1 --- /dev/null +++ b/man/tip/nng_ctx_recv.3.html @@ -0,0 +1,644 @@ +--- +version: tip +layout: refman +--- + + + + + + + +nng_ctx_recv(3) + + + + + + + +
    +
    +

    SYNOPSIS

    +
    +
    +
    +
    #include <nng/nng.h>
+
+void nng_ctx_recv(nng_ctx ctx, nng_aio *aio);
    +
    +
    +
    +
    +
    +

    DESCRIPTION

    +
    +
    +

    The nng_ctx_recv() receives a message using the +context s asynchronously.

    +
    +
    +

    When a message is successfully received by the context, it is +stored in the aio by an internal call equivalent to +nng_aio_set_msg(), then the completion +callback on the aio is executed. +In this case, nng_aio_result() will +return zero. +The callback function is responsible for retrieving the message +and disposing of it appropriately.

    +
    +
    + + + + + +
    + + +Failing to accept and dispose of messages in this +case can lead to memory leaks. +
    +
    +
    +

    If for some reason the asynchronous receive cannot be completed +successfully (including by being canceled or timing out), then +the callback will still be executed, +but nng_aio_result() will be non-zero.

    +
    +
    + + + + + +
    + + +The semantics of what receiving a message means varies from protocol to +protocol, so examination of the protocol documentation is encouraged. +
    +
    +
    +
    +
    +

    RETURN VALUES

    +
    +
    +

    None. (The operation completes asynchronously.)

    +
    +
    +
    +
    +

    ERRORS

    +
    +
    +
    +
    NNG_ECANCELED
    +
    +

    The operation was aborted.

    +
    +
    NNG_ECLOSED
    +
    +

    The context ctx is not open.

    +
    +
    NNG_ENOMEM
    +
    +

    Insufficient memory is available.

    +
    +
    NNG_ENOTSUP
    +
    +

    The protocol for context ctx does not support receiving.

    +
    +
    NNG_ESTATE
    +
    +

    The context ctx cannot receive data in this state.

    +
    +
    NNG_ETIMEDOUT
    +
    +

    The receive timeout expired.

    +
    +
    +
    +
    +
    +
    +

    SEE ALSO

    +
    +
    +

    nng_aio_get_msg(3), +nng_aio_set_msg(3), +nng_msg_alloc(3), +nng_strerror(3), +nng_aio(5), +nng_ctx(5), +nng_msg(5), +nng(7)

    +
    +
    +
    +
    + + diff --git a/man/tip/nng_ctx_send.3.html b/man/tip/nng_ctx_send.3.html new file mode 100644 index 00000000..28a1fe76 --- /dev/null +++ b/man/tip/nng_ctx_send.3.html @@ -0,0 +1,672 @@ +--- +version: tip +layout: refman +--- + + + + + + + +nng_ctx_send(3) + + + + + + + +
    +
    +

    SYNOPSIS

    +
    +
    +
    +
    #include <nng/nng.h>
+
+void nng_ctx_send(nng_ctx ctx, nng_aio *aio);
    +
    +
    +
    +
    +
    +

    DESCRIPTION

    +
    +
    +

    The nng_ctx_send() sends a message using the +context ctx asynchronously.

    +
    +
    +

    The message to send must have previously been set on the aio +using the nng_aio_set_msg() function. +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 nng_aio_result() +will return zero. +In this case the socket will dispose of the message when it is finished with it.

    +
    +
    + + + + + +
    + + +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 +may still be buffered in the sending socket, buffered in the receiving +socket, or in flight over physical media. +
    +
    +
    +

    If the operation fails for any reason (including cancellation or timeout), +then the aio callback will be executed and nng_aio_result() +will return a non-zero error status. +In this case, the callback has a responsibity to retrieve the message from +the aio with nng_aio_get_msg() and dispose of +it appropriately. +(This may include retrying the send operation on the same or a different +socket, or deallocating the message with nng_msg_free().)

    +
    +
    + + + + + +
    + + +The semantics of what sending a message means varies from protocol to +protocol, so examination of the protocol documentation is encouraged. +
    +
    +
    + + + + + +
    + + +Context send operations are asynchronous. +If a synchronous operation is needed, one can be constructed by using a +NULL callback on the aio and then waiting for the operation using +nng_aio_wait(). +
    +
    +
    +
    +
    +

    RETURN VALUES

    +
    +
    +

    None. (The operation completes asynchronously.)

    +
    +
    +
    +
    +

    ERRORS

    +
    +
    +
    +
    NNG_ECANCELED
    +
    +

    The operation was aborted.

    +
    +
    NNG_ECLOSED
    +
    +

    The context ctx is not open.

    +
    +
    NNG_EMSGSIZE
    +
    +

    The message is too large.

    +
    +
    NNG_ENOMEM
    +
    +

    Insufficient memory is available.

    +
    +
    NNG_ENOTSUP
    +
    +

    The protocol for context ctx does not support sending.

    +
    +
    NNG_ESTATE
    +
    +

    The context ctx cannot send data in this state.

    +
    +
    NNG_ETIMEDOUT
    +
    +

    The send timeout expired.

    +
    +
    +
    +
    +
    +
    +

    SEE ALSO

    +
    +
    +

    nng_aio_get_msg(3), +nng_aio_set_msg(3), +nng_msg_alloc(3), +nng_strerror(3), +nng_aio(5), +nng_ctx(5), +nng_msg(5), +nng(7)

    +
    +
    +
    +
    + + diff --git a/man/tip/nng_ctx_setopt.3.html b/man/tip/nng_ctx_setopt.3.html new file mode 100644 index 00000000..b713953b --- /dev/null +++ b/man/tip/nng_ctx_setopt.3.html @@ -0,0 +1,704 @@ +--- +version: tip +layout: refman +--- + + + + + + + +nng_ctx_setopt(3) + + + + + + + +
    +
    +

    SYNOPSIS

    +
    +
    +
    +
    #include <nng/nng.h>
+
+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

    +
    +
    +

    +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.

    +
    +
    + + + + + +
    + + +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.

    +
    +
    + + + + + +
    + + +Generally, it will be easier to use one of the typed versions +of this function. +
    +
    +
    +

    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.

    +
    +
    +
    +

    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 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

    +
    +
    +
    +
    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

    +
    +
    +

    nng_ctx_getopt(3), +nng_setopt(3), +nng_strerror(3), +nng_ctx(5), +nng_options(5), +nng_socket(5), +nng(7)

    +
    +
    +
    +
    + + diff --git a/man/tip/nng_cv_alloc.3supp.html b/man/tip/nng_cv_alloc.3supp.html new file mode 100644 index 00000000..ea886b18 --- /dev/null +++ b/man/tip/nng_cv_alloc.3supp.html @@ -0,0 +1,594 @@ +--- +version: tip +layout: refman +--- + + + + + + + +nng_cv_alloc(3supp) + + + + + + + +
    +
    +

    SYNOPSIS

    +
    +
    +
    +
    #include <nng/nng.h>
+#include <nng/supplemental/util/platform.h>
+
+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 +nng_cv_wait() or +nng_cv_until(). +The mutex must also be owned when signaling the condition using the +nng_cv_wake() or +nng_cv_wake1() functions.

    +
    +
    +
    +
    +

    RETURN VALUES

    +
    +
    +

    This function returns 0 on success, and non-zero otherwise.

    +
    +
    +
    +
    +

    ERRORS

    +
    +
    +
    +
    NNG_ENOMEM
    +
    +

    Insufficient free memory exists.

    +
    +
    +
    +
    +
    +
    +

    SEE ALSO

    +
    +
    +

    nng_cv_free(3supp), +nng_cv_until(3supp), +nng_cv_wait(3supp), +nng_cv_wake(3supp), +nng_cv_wake1(3supp), +nng_mtx_alloc(3supp), +nng_strerror(3), +nng(7)

    +
    +
    +
    +
    + + diff --git a/man/tip/nng_cv_free.3supp.html b/man/tip/nng_cv_free.3supp.html new file mode 100644 index 00000000..a67b52e1 --- /dev/null +++ b/man/tip/nng_cv_free.3supp.html @@ -0,0 +1,571 @@ +--- +version: tip +layout: refman +--- + + + + + + + +nng_cv_free(3supp) + + + + + + + +
    +
    +

    SYNOPSIS

    +
    +
    +
    +
    #include <nng/nng.h>
+#include <nng/supplemental/util/platform.h>
+
+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

    +
    +
    +

    nng_cv_alloc(3supp), +nng(7)

    +
    +
    +
    +
    + + diff --git a/man/tip/nng_cv_until.3supp.html b/man/tip/nng_cv_until.3supp.html new file mode 100644 index 00000000..66596a74 --- /dev/null +++ b/man/tip/nng_cv_until.3supp.html @@ -0,0 +1,635 @@ +--- +version: tip +layout: refman +--- + + + + + + + +nng_cv_until(3supp) + + + + + + + +
    +
    +

    SYNOPSIS

    +
    +
    +
    +
    #include <nng/nng.h>
+#include <nng/supplemental/util/platform.h>
+
+int nng_cv_wait(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 nng_cv_wake() or +nng_cv_wake1(), or the system clock (as tracked +by 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.)

    +
    +
    + + + + + +
    + + +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
    +
    +
    
+    nng_mtx_lock(m);  // assume cv was allocated using m
+    while (!condition_true) {
+        if (nng_cv_wait(cv) == NNG_ETIMEDOUT) {
+            printf("Time out reached!\n");
+            break;
+        }
+    }
+    // condition_true is true
+    nng_mtx_unlock(m);
    +
    +
    +
    +
    Example 2: Signaling the condition
    +
    +
        nng_mtx_lock(m);
+    condition_true = true;
+    cv_wake(cv);
+    nng_mtx_unlock(m);
    +
    +
    +
    +
    +
    +

    RETURN VALUES

    +
    +
    +

    None.

    +
    +
    +
    +
    +

    ERRORS

    +
    +
    +

    None.

    +
    +
    +
    +
    +

    SEE ALSO

    +
    +
    +

    nng_cv_alloc(3supp), +nng_cv_wait(3supp), +nng_cv_wake(3supp), +nng_cv_wake1(3supp), +nng_mtx_alloc(3supp), +nng_mtx_lock(3supp), +nng_mtx_unlock(3supp), +nng(7)

    +
    +
    +
    +
    + + diff --git a/man/tip/nng_cv_wait.3supp.html b/man/tip/nng_cv_wait.3supp.html new file mode 100644 index 00000000..2d6c293b --- /dev/null +++ b/man/tip/nng_cv_wait.3supp.html @@ -0,0 +1,631 @@ +--- +version: tip +layout: refman +--- + + + + + + + +nng_cv_wait(3supp) + + + + + + + +
    +
    +

    SYNOPSIS

    +
    +
    +
    +
    #include <nng/nng.h>
+#include <nng/supplemental/util/platform.h>
+
+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 nng_cv_wake() or +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.)

    +
    +
    + + + + + +
    + + +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
    +
    +
    
+    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
    +
    +
        nng_mtx_lock(m);
+    condition_true = true;
+    cv_wake(cv);
+    nng_mtx_unlock(m);
    +
    +
    +
    +
    +
    +

    RETURN VALUES

    +
    +
    +

    None.

    +
    +
    +
    +
    +

    ERRORS

    +
    +
    +

    None.

    +
    +
    +
    +
    +

    SEE ALSO

    +
    +
    +

    nng_cv_alloc(3supp), +nng_cv_until(3supp), +nng_cv_wake(3supp), +nng_cv_wake1(3supp), +nng_mtx_alloc(3supp), +nng_mtx_lock(3supp), +nng_mtx_unlock(3supp), +nng(7)

    +
    +
    +
    +
    + + diff --git a/man/tip/nng_cv_wake.3supp.html b/man/tip/nng_cv_wake.3supp.html new file mode 100644 index 00000000..a66971c7 --- /dev/null +++ b/man/tip/nng_cv_wake.3supp.html @@ -0,0 +1,611 @@ +--- +version: tip +layout: refman +--- + + + + + + + +nng_cv_wake(3supp) + + + + + + + +
    +
    +

    SYNOPSIS

    +
    +
    +
    +
    #include <nng/nng.h>
+#include <nng/supplemental/util/platform.h>
+
+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 nng_cv_wait() or +nng_cv_until() functions.

    +
    +
    +

    The caller must have have ownership of the mutex that was used when +cv was allocated.

    +
    +
    + + + + + +
    + + +The caller should already have set the condition that the waiters +will check, while holding the mutex. +
    +
    +
    + + + + + +
    + + +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. +See nng_cv_wake1() for a solution to this problem. +
    +
    +
    +
    +
    +

    RETURN VALUES

    +
    +
    +

    None.

    +
    +
    +
    +
    +

    ERRORS

    +
    +
    +

    None.

    +
    +
    +
    +
    +

    SEE ALSO

    +
    +
    +

    nng_cv_alloc(3supp), +nng_cv_until(3supp), +nng_cv_wait(3supp), +nng_cv_wake1(3supp), +nng_mtx_alloc(3supp), +nng_mtx_lock(3supp), +nng_mtx_unlock(3supp), +nng(7)

    +
    +
    +
    +
    + + diff --git a/man/tip/nng_cv_wake1.3supp.html b/man/tip/nng_cv_wake1.3supp.html new file mode 100644 index 00000000..eb66f300 --- /dev/null +++ b/man/tip/nng_cv_wake1.3supp.html @@ -0,0 +1,612 @@ +--- +version: tip +layout: refman +--- + + + + + + + +nng_cv_wake1(3supp) + + + + + + + +
    +
    +

    SYNOPSIS

    +
    +
    +
    +
    #include <nng/nng.h>
+#include <nng/supplemental/util/platform.h>
+
+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 nng_cv_wait() or +nng_cv_until() functions.

    +
    +
    +

    The caller must have have ownership of the mutex that was used when +cv was allocated.

    +
    +
    + + + + + +
    + + +The caller should already have set the condition that the waiters +will check, while holding the mutex. +
    +
    +
    + + + + + +
    + + +While this function avoids the “thundering herd” problem, 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 nng_cv_wake(). +
    +
    +
    +
    +
    +

    RETURN VALUES

    +
    +
    +

    None.

    +
    +
    +
    +
    +

    ERRORS

    +
    +
    +

    None.

    +
    +
    +
    +
    +

    SEE ALSO

    +
    +
    +

    nng_cv_alloc(3supp), +nng_cv_until(3supp), +nng_cv_wait(3supp), +nng_cv_wake(3supp), +nng_mtx_alloc(3supp), +nng_mtx_lock(3supp), +nng_mtx_unlock(3supp), +nng(7)

    +
    +
    +
    +
    + + diff --git a/man/tip/nng_device.3.html b/man/tip/nng_device.3.html index 401aeefa..eb1b6c88 100644 --- a/man/tip/nng_device.3.html +++ b/man/tip/nng_device.3.html @@ -551,6 +551,12 @@ complex network topologies to provide for improved horizontal scalability, reliability, and isolation.

    +

    Only raw mode sockets may be used with this +function. +These can be created using _raw forms of the various socket constructors, +such as nng_req0_open_raw().

    +
    +

    The nng_device() function does not return until one of the sockets is closed.

    @@ -585,11 +591,15 @@ be a bus socket.

    Operation

    -

    This nng_device() function puts each socket into raw mode -(see NNG_OPT_RAW), and then moves messages -between them. -When a protocol has a backtrace style header, routing information is -added as the message crosses the forwarder, allowing replies to be +

    The nng_device() function moves messages between the provided sockets.

    +
    +
    +

    When a protocol has a backtrace style header, routing information +is present in the header of received messages, and is copied to the +header of the output bound message. +The underlying raw mode protocols supply the necessary header +adjustments to add or remove routing headers as needed. +This allows replies to be returned to requestors, and responses to be routed back to surveyors.

    diff --git a/man/tip/nng_dialer_getopt.3.html b/man/tip/nng_dialer_getopt.3.html index dcf3ccd0..c9b9cf5c 100644 --- a/man/tip/nng_dialer_getopt.3.html +++ b/man/tip/nng_dialer_getopt.3.html @@ -541,7 +541,11 @@ body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-b int nng_dialer_getopt_ptr(nng_dialer d, const char *opt, void **ptr); -int nng_dialer_setopt_size(nng_dialer d, const char *opt, size_t *zp); +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);
    @@ -568,6 +572,10 @@ are documented with the transports and protocols themselves.

    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.

    +
    @@ -581,23 +589,6 @@ function.
    -
    - - - - - -
    - - -No validation that the option is actually of the associated type is -performed, so the caller must take care to use the correct typed form. -
    -
    -
    -

    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()

    @@ -625,7 +616,7 @@ the object.

    nng_dialer_getopt_bool()

    This function is for options which take a boolean (bool). -The value will be stored at ivalp.

    +The value will be stored at bvalp.

    @@ -661,6 +652,22 @@ typically for buffer sizes, message maximum sizes, and similar options.

    +

    nng_dialer_getopt_sockaddr()

    +
    +

    This function is used to retrieve an 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 nng_strdup() +and consequently must be freed by the caller using +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 @@ -685,10 +692,22 @@ numbers, and similar.

    +
    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.

    @@ -707,10 +726,13 @@ numbers, and similar.

    nng_dialer_create(3) nng_dialer_setopt(3) +nng_strdup(3), nng_strerror(3), +nng_strfree(3), nng_dialer(5), nng_duration(5), nng_options(5), +nng_sockaddr(5), nng(7)

    diff --git a/man/tip/nng_dialer_setopt.3.html b/man/tip/nng_dialer_setopt.3.html index 894313db..148ccd62 100644 --- a/man/tip/nng_dialer_setopt.3.html +++ b/man/tip/nng_dialer_setopt.3.html @@ -599,19 +599,6 @@ Generally, it will be easier to use one of the typed forms instead.
    -
    - - - - - -
    - - -No validation that the option is actually of the associated -type is performed, so the caller must take care to use the correct typed form. -
    -

    nng_dialer_setopt()

    @@ -695,6 +682,10 @@ and similar.

    +
    NNG_EBADTYPE
    +
    +

    Incorrect type for option.

    +
    NNG_ECLOSED

    Parameter d does not refer to an open dialer.

    diff --git a/man/tip/nng_free.3.html b/man/tip/nng_free.3.html index c56fc914..6bfc9d67 100644 --- a/man/tip/nng_free.3.html +++ b/man/tip/nng_free.3.html @@ -540,11 +540,11 @@ body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-b that was previously allocated by nng_alloc() or nng_recv() with the NNG_FLAG_ALLOC flag.

    -
    +
    - + It is very important that size match the allocation size @@ -553,11 +553,11 @@ used to allocate the memory.
    -
    +
    - + Do not attempt to use this function to deallocate memory diff --git a/man/tip/nng_getopt.3.html b/man/tip/nng_getopt.3.html index 889881bc..ffaa72fe 100644 --- a/man/tip/nng_getopt.3.html +++ b/man/tip/nng_getopt.3.html @@ -543,6 +543,8 @@ body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-b 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); @@ -568,6 +570,10 @@ documented with the transports and protocols themselves.

    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.

    +
    @@ -580,23 +586,6 @@ Generally, it will be easier to use one of the typed forms instead.
    -
    - - - - - -
    - - -No validation that the option is actually of the associated -type is performed, so the caller must take care to use the correct typed form. -
    -
    -
    -

    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()

    @@ -660,6 +649,15 @@ 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 nng_strdup() +and consequently must be freed by the caller using +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 @@ -684,10 +682,22 @@ numbers, and similar.

    +
    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.

    @@ -708,7 +718,9 @@ numbers, and similar.

    nng_listener_getopt(3), nng_pipe_getopt(3), nng_setopt(3), +nng_strdup(3), nng_strerror(3), +nng_strfree(3), nng_duration(5), nng_options(5), nng_socket(5), diff --git a/man/tip/nng_listener_getopt.3.html b/man/tip/nng_listener_getopt.3.html index 585a9be2..96d44885 100644 --- a/man/tip/nng_listener_getopt.3.html +++ b/man/tip/nng_listener_getopt.3.html @@ -531,8 +531,7 @@ body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-b 
    #include <nng/nng.h>
 
-int nng_listener_getopt(nng_listener l, const char *opt, void *val,
-    size_t *valszp);
+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);
 
@@ -542,7 +541,11 @@ body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-b
 
 int nng_listener_getopt_ptr(nng_listener l, const char *opt, void **ptr);
 
-int nng_listener_setopt_size(nng_listener l, const char *opt, size_t *zp);
+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);
    @@ -569,6 +572,10 @@ are documented with the transports and protocols themselves.

    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.

    +
    @@ -582,23 +589,6 @@ function.
    -
    - - - - - -
    - - -No validation that the option is actually of the associated type is -performed, so the caller must take care to use the correct typed form. -
    -
    -
    -

    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()

    @@ -626,7 +616,7 @@ the object.

    nng_listener_getopt_bool()

    This function is for options which take a boolean (bool). -The value will be stored at ivalp.

    +The value will be stored at bvalp.

    @@ -640,9 +630,7 @@ The value will be stored at ivalp.

    nng_listener_getopt_ms()

    This function is used to retrieve time durations -(such as timeouts), stored in durp as a number of milliseconds. -(The special value NNG_DUR_INFINITE means an infinite amount of time, and -the special value NNG_DUR_DEFAULT means a context-specific default.)

    +(such as timeouts), stored in durp as a number of milliseconds.

    @@ -662,6 +650,22 @@ typically for buffer sizes, message maximum sizes, and similar options.

    +

    nng_listener_getopt_sockaddr()

    +
    +

    This function is used to retrieve an 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 nng_strdup() +and consequently must be freed by the caller using +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 @@ -686,10 +690,22 @@ numbers, and similar.

    +
    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.

    @@ -710,7 +726,13 @@ numbers, and similar.

    nng_listener_create(3) nng_listener_setopt(3) nng_getopt(3), +nng_strdup(3), nng_strerror(3), +nng_strfree(3), +nng_duration(5), +nng_listener(5), +nng_options(5), +nng_sockaddr(5), nng(7)

    diff --git a/man/tip/nng_listener_setopt.3.html b/man/tip/nng_listener_setopt.3.html index 6d6b9e55..5605d4d1 100644 --- a/man/tip/nng_listener_setopt.3.html +++ b/man/tip/nng_listener_setopt.3.html @@ -597,19 +597,6 @@ Generally, it will be easier to use one of the typed forms instead.
    -
    - - - - - -
    - - -No validation that the option is actually of the associated -type is performed, so the caller must take care to use the correct typed form. -
    -

    nng_listener_setopt()

    @@ -693,6 +680,10 @@ and similar.

    +
    NNG_EBADTYPE
    +
    +

    Incorrect type for option.

    +
    NNG_ECLOSED

    Parameter l does not refer to an open listener.

    @@ -726,6 +717,7 @@ and similar.

    nng_listener_getopt(3) nng_setopt(3), nng_strerror(3), +nng_duration(5), nng_listener(5), nng_options(5), nng(7)

    diff --git a/man/tip/nng_msleep.3supp.html b/man/tip/nng_msleep.3supp.html new file mode 100644 index 00000000..8658c615 --- /dev/null +++ b/man/tip/nng_msleep.3supp.html @@ -0,0 +1,588 @@ +--- +version: tip +layout: refman +--- + + + + + + + +nng_msleep(3supp) + + + + + + + +
    +
    +

    SYNOPSIS

    +
    +
    +
    +
    #include <nng/nng.h>
+#include <nng/supplemental/util/platform.h>
+
+void nng_msleep(nng_duration msec);
    +
    +
    +
    +
    +
    +

    DESCRIPTION

    +
    +
    +

    The nng_msleep() blocks the caller for at least msec milliseconds.

    +
    +
    + + + + + +
    + + +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

    +
    +
    +

    nng_sleep_aio(3), +nng_strerror(3), +nng_clock(3supp), +nng_duration(5), +nng(7)

    +
    +
    +
    +
    + + diff --git a/man/tip/nng_mtx_alloc.3supp.html b/man/tip/nng_mtx_alloc.3supp.html new file mode 100644 index 00000000..915fdcbf --- /dev/null +++ b/man/tip/nng_mtx_alloc.3supp.html @@ -0,0 +1,594 @@ +--- +version: tip +layout: refman +--- + + + + + + + +nng_mtx_alloc(3supp) + + + + + + + +
    +
    +

    SYNOPSIS

    +
    +
    +
    +
    #include <nng/nng.h>
+#include <nng/supplemental/util/platform.h>
+
+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 “own” 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

    +
    +
    +
    +
    NNG_ENOMEM
    +
    +

    Insufficient free memory exists.

    +
    +
    +
    +
    +
    +
    +

    SEE ALSO

    +
    +
    +

    nng_cv_alloc(3supp), +nng_mtx_free(3supp), +nng_mtx_lock(3supp), +nng_mtx_unlock(3supp), +nng_strerror(3), +nng(7)

    +
    +
    +
    +
    + + diff --git a/man/tip/nng_mtx_free.3supp.html b/man/tip/nng_mtx_free.3supp.html new file mode 100644 index 00000000..1e6cda92 --- /dev/null +++ b/man/tip/nng_mtx_free.3supp.html @@ -0,0 +1,572 @@ +--- +version: tip +layout: refman +--- + + + + + + + +nng_mtx_free(3supp) + + + + + + + +
    +
    +

    SYNOPSIS

    +
    +
    +
    +
    #include <nng/nng.h>
+#include <nng/supplemental/util/platform.h>
+
+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

    +
    +
    +

    nng_mtx_alloc(3supp), +nng(7)

    +
    +
    +
    +
    + + diff --git a/man/tip/nng_mtx_lock.3supp.html b/man/tip/nng_mtx_lock.3supp.html new file mode 100644 index 00000000..befe5201 --- /dev/null +++ b/man/tip/nng_mtx_lock.3supp.html @@ -0,0 +1,617 @@ +--- +version: tip +layout: refman +--- + + + + + + + +nng_mtx_lock(3supp) + + + + + + + +
    +
    +

    SYNOPSIS

    +
    +
    +
    +
    #include <nng/nng.h>
+#include <nng/supplemental/util/platform.h>
+
+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 nng_mtx_unlock().

    +
    +
    +

    If multiple threads are waiting for the lock, the order of acquisition +is not specified.

    +
    +
    + + + + + +
    + + +A mutex can only be unlocked by the thread that locked it. +
    +
    +
    + + + + + +
    + + +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 “trylock” operation, 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

    +
    +
    +

    nng_cv_alloc(3supp), +nng_mtx_alloc(3supp), +nng_mtx_unlock(3supp), +nng(7)

    +
    +
    +
    +
    + + diff --git a/man/tip/nng_mtx_unlock.3supp.html b/man/tip/nng_mtx_unlock.3supp.html new file mode 100644 index 00000000..374e80e7 --- /dev/null +++ b/man/tip/nng_mtx_unlock.3supp.html @@ -0,0 +1,587 @@ +--- +version: tip +layout: refman +--- + + + + + + + +nng_mtx_unlock(3supp) + + + + + + + +
    +
    +

    SYNOPSIS

    +
    +
    +
    +
    #include <nng/nng.h>
+#include <nng/supplemental/util/platform.h>
+
+void nng_mtx_unlock(nng_mtx *mtx);
    +
    +
    +
    +
    +
    +

    DESCRIPTION

    +
    +
    +

    The nng_mtx_unlock() reqlinquishes ownership of the mutex mtx that +was previously acquired via nng_mtx_lock().

    +
    +
    + + + + + +
    + + +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

    +
    +
    +

    nng_mtx_alloc(3supp), +nng_mtx_lock(3supp), +nng(7)

    +
    +
    +
    +
    + + diff --git a/man/tip/nng_options.5.html b/man/tip/nng_options.5.html index e972ec41..bde2e88a 100644 --- a/man/tip/nng_options.5.html +++ b/man/tip/nng_options.5.html @@ -639,14 +639,15 @@ listeners but not dialers.

    (bool) -This option determines whether the socket is in “raw” 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 “cooked” 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 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 Raw Mode for more details.

    diff --git a/man/tip/nng_opts_parse.3supp.html b/man/tip/nng_opts_parse.3supp.html new file mode 100644 index 00000000..e1ad7861 --- /dev/null +++ b/man/tip/nng_opts_parse.3supp.html @@ -0,0 +1,772 @@ +--- +version: tip +layout: refman +--- + + + + + + + +nng_opts_parse(3supp) + + + + + + + +
    +
    +

    SYNOPSIS

    +
    +
    +
    +
    #include <nng/nng.h>
+#include <nng/supplemental/util/options.h>
+
+typedef struct nng_optspec {
+    const char *o_name;  // Long style name (may be NULL for short only)
+    int         o_short; // Short option (no clustering!)
+    int         o_val;   // Value stored on a good parse (>0)
+    bool        o_arg;   // Option takes an argument if true
+} nng_optspec;
+
+int nng_opts_parse(int argc, const char **argv, const nng_optspec *spec, int *val, const char **arg, int *idx);
    +
    +
    +
    +
    +
    +

    DESCRIPTION

    +
    +
    +

    The nng_opts_parse() is function is a supplemental funtion intened 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 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 Option Specification.) +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.

    +
    +
    + + + + + +
    + + +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.

    +
    +
    +

    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

    +
    +

    The calling program must first create an array of nng_optspec structures +describing the options to be supported. +This structure has the following members:

    +
    +
    +
    +
    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
    +
    +

    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
    +
    +

    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. +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 +this option is parsed from the command line.

    +
    +
    o_arg
    +
    +

    This value should be set to true if the option should take an argument.

    +
    +
    +
    +
    +
    +

    Long Options

    +
    +

    Long options are parsed from the argv array, and are indicated when +the element being scanned starts with two dashes. +For example, the "verbose" option would be specified as --verbose on +the command line. +If a long option takes an argument, it can either immediately follow +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 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.

    +
    +
    + + + + + +
    + + +Option clustering, where multiple options can be crammed together in +a single argv element, is not supported by this function (yet). +
    +
    +
    +
    +

    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

    +
    +
    +

    The following program fragment demonstrates this function.

    +
    +
    +
    +
        enum { OPT_LOGFILE, OPT_VERBOSE };
+    char *logfile; // options to be set
+    bool verbose;
+
+    static nng_optspec specs[] = {
+        {
+            .o_name = "logfile",
+            .o_short = 'D',
+            .o_val = OPT_LOGFILE,
+            .o_arg = true,
+        }, {
+            .o_name = "verbose",
+            .o_short = 'V',
+            .o_val = OPT_VERBOSE,
+            .o_arg = false,
+        }, {
+            .o_val = 0; // Terminate array
+        }
+    };
+
+    for (int idx = 1;;) {
+        int rv, opt;
+        char *arg;
+        rv = nng_opts_parse(argc, argv, specs, &opt, &arg, &idx);
+        if (rv != 0) {
+            break;
+        }
+        switch (opt) {
+        case OPT_LOGFILE:
+            logfile = arg;
+            break;
+        case OPT_VERBOSE:
+            verbose = true;
+            break;
+        }
+    }
+    if (rv != -1) {
+        printf("Options error: %s\n", nng_strerror(rv));
+        exit(1);
+    }
    +
    +
    +
    +
    +
    +

    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

    +
    +
    +
    +
    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

    +
    +
    +

    nng_strerror(3), +nng(7)

    +
    +
    +
    +
    + + diff --git a/man/tip/nng_pair.7.html b/man/tip/nng_pair.7.html index e08bfa95..98e77823 100644 --- a/man/tip/nng_pair.7.html +++ b/man/tip/nng_pair.7.html @@ -532,17 +532,13 @@ body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-b
    Version 0
    -
    #include <nng/protocol/pair0/pair.h>
-
-int nng_pair0_open(nng_socket *s);
    +
    #include <nng/protocol/pair0/pair.h>
    Version 1
    -
    #include <nng/protocol/pair1/pair.h>
-
-int nng_pair1_open(nng_socket *s);
    +
    #include <nng/protocol/pair1/pair.h>
    @@ -563,9 +559,11 @@ some additional sophistication in the application.

    Socket Operations

    -

    The nng_pair_open() call creates a pair socket. Normally, this -pattern will block when attempting to send a message, if no peer is -able to receive the message.

    +

    The nng_pair_open() functions create pair socket.

    +
    +
    +

    Normally, this pattern will block when attempting to send a message if +no peer is able to receive the message.

    diff --git a/man/tip/nng_pair_open.3.html b/man/tip/nng_pair_open.3.html index cc2fcd66..0eb51508 100644 --- a/man/tip/nng_pair_open.3.html +++ b/man/tip/nng_pair_open.3.html @@ -528,7 +528,9 @@ body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-b 
    #include <nng/protocol/pair0/pair.h>
 
-int nng_pair0_open(nng_socket *s);
    +int nng_pair0_open(nng_socket *s); + +int nng_pair0_open_raw(nng_socket *s);
    @@ -536,7 +538,9 @@ body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-b 
    #include <nng/protocol/pair1/pair.h>
 
-int nng_pair1_open(nng_socket *s);
    +int nng_pair1_open(nng_socket *s); + +int nng_pair1_open_raw(nng_socket *s);
    @@ -549,6 +553,12 @@ body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-b create a pair version 0 or version 1 socket and return it at the location pointed to by s.

    +
    +

    The nng_pair0_open_raw() and nng_pair1_open_raw() functions +create a pair version 0 or version 1 +socket in +raw mode and return it at the location pointed to by s.

    +
    diff --git a/man/tip/nng_pipe_getopt.3.html b/man/tip/nng_pipe_getopt.3.html index ee0857d5..5f7220e1 100644 --- a/man/tip/nng_pipe_getopt.3.html +++ b/man/tip/nng_pipe_getopt.3.html @@ -541,6 +541,10 @@ body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-b int nng_dialer_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); @@ -618,8 +622,6 @@ the object.

    Generally, it will be easier to use one of the typed forms instead. -Note however that no validation that the option is actually of the associated -type is performed, so the caller must take care to use the correct typed form.
    @@ -665,6 +667,22 @@ typically for buffer sizes, message maximum sizes, and similar options.

    +

    nng_pipe_getopt_sockaddr()

    +
    +

    This function is used to retrieve an 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 nng_strdup() +and consequently must be freed by the caller using +nng_strfree() when it is no longer needed.

    +
    +
    +

    nng_pipe_getopt_uint64()

    This function is used to retriev a 64-bit unsigned value into the value @@ -689,6 +707,10 @@ related to identifiers, network numbers, and similar.

    +
    NNG_EBADTYPE
    +
    +

    Incorrect type for option.

    +
    NNG_ECLOSED

    Parameter p does not refer to an open pipe.

    @@ -697,6 +719,14 @@ related to identifiers, network numbers, and similar.

    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.

    @@ -713,8 +743,13 @@ related to identifiers, network numbers, and similar.

    nng_getopt(3), nng_listener_setopt(3) nng_msg_get_pipe(3) +nng_strdup(3), nng_strerror(3), +nng_strfree(3), +nng_duration(5), nng_options(5), +nng_pipe(5), +nng_sockaddr(5), nng(7)

    diff --git a/man/tip/nng_pub.7.html b/man/tip/nng_pub.7.html index 0eb2fbef..87f43112 100644 --- a/man/tip/nng_pub.7.html +++ b/man/tip/nng_pub.7.html @@ -530,9 +530,7 @@ body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-b
    -
    #include <nng/protocol/pubsub0/pub.h>
-
-int nng_pub0_open(nng_socket *s);
    +
    #include <nng/protocol/pubsub0/pub.h>
    @@ -576,7 +574,7 @@ Applications should construct their messages accordingly.

    Socket Operations

    -

    The nng_pub0_open() call creates a publisher socket. +

    The nng_pub0_open() functions create a publisher socket. This socket may be used to send messages, but is unable to receive them. Attempts to receive messages will result in NNG_ENOTSUP.

    diff --git a/man/tip/nng_pub_open.3.html b/man/tip/nng_pub_open.3.html index e902e7e6..29d40cf0 100644 --- a/man/tip/nng_pub_open.3.html +++ b/man/tip/nng_pub_open.3.html @@ -528,7 +528,9 @@ body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-b 
    #include <nng/nng.h>
 #include <nng/protocol/pubsub0/pub.h>
 
-int nng_pub0_open(nng_socket *s);
    +int nng_pub0_open(nng_socket *s); + +int nng_pub0_open_raw(nng_socket *s);
    @@ -540,13 +542,18 @@ body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-b

    The nng_pub0_open() function creates a pub version 0 socket and returns it at the location pointed to by s.

    +
    +

    The nng_pub0_open_raw() function creates a pub version 0 +socket in +raw mode and returns it at the location pointed to by s.

    +

    RETURN VALUES

    -

    This function returns 0 on success, and non-zero otherwise.

    +

    These functions return 0 on success, and non-zero otherwise.

    diff --git a/man/tip/nng_pull.7.html b/man/tip/nng_pull.7.html index acc5b926..94a6b989 100644 --- a/man/tip/nng_pull.7.html +++ b/man/tip/nng_pull.7.html @@ -530,9 +530,7 @@ body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-b
    -
    #include <nng/protocol/pipeline0/pull.h>
-
-int nng_pull0_open(nng_socket *s);
    +
    #include <nng/protocol/pipeline0/pull.h>
    @@ -556,7 +554,7 @@ This property makes this pattern useful in load-balancing scenarios.

    Socket Operations

    -

    The nng_pull0_open() call creates a puller socket. +

    The nng_pull0_open() functions create a puller socket. This socket may be used to receive messages, but is unable to send them. Attempts to send messages will result in NNG_ENOTSUP.

    diff --git a/man/tip/nng_pull_open.3.html b/man/tip/nng_pull_open.3.html index 4046888e..50f2b7bf 100644 --- a/man/tip/nng_pull_open.3.html +++ b/man/tip/nng_pull_open.3.html @@ -528,7 +528,9 @@ body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-b 
    #include <nng/nng.h>
 #include <nng/protocol/pipeline0/pull.h>
 
-int nng_pull0_open(nng_socket *s);
    +int nng_pull0_open(nng_socket *s); + +int nng_pull0_open_raw(nng_socket *s);
    @@ -540,13 +542,18 @@ body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-b

    The nng_pull0_open() function creates a pull version 0 socket and returns it at the location pointed to by s.

    +
    +

    The nng_pull0_open_raw() function creates a pull version 0 +socket in +raw mode and returns it at the location pointed to by s.

    +

    RETURN VALUES

    -

    This function returns 0 on success, and non-zero otherwise.

    +

    These functions return 0 on success, and non-zero otherwise.

    diff --git a/man/tip/nng_push.7.html b/man/tip/nng_push.7.html index bb508a87..ee520b56 100644 --- a/man/tip/nng_push.7.html +++ b/man/tip/nng_push.7.html @@ -530,9 +530,7 @@ body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-b
    -
    #include <nng/protocol/pipeline0/push.h>
-
-int nng_push0_open(nng_socket *s);
    +
    #include <nng/protocol/pipeline0/push.h>
    diff --git a/man/tip/nng_push_open.3.html b/man/tip/nng_push_open.3.html index 720a9662..a4089068 100644 --- a/man/tip/nng_push_open.3.html +++ b/man/tip/nng_push_open.3.html @@ -528,7 +528,9 @@ body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-b 
    #include <nng/nng.h>
 #include <nng/protocol/pipeline0/push.h>
 
-int nng_push0_open(nng_socket *s);
    +int nng_push0_open(nng_socket *s); + +int nng_push0_open_raw(nng_socket *s);
    @@ -540,13 +542,18 @@ body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-b

    The nng_push0_open() function creates a push version 0 socket and returns it at the location pointed to by s.

    +
    +

    The nng_push0_open_raw() function creates a push version 0 +socket in +raw mode and returns it at the location pointed to by s.

    +

    RETURN VALUES

    -

    This function returns 0 on success, and non-zero otherwise.

    +

    These functions return 0 on success, and non-zero otherwise.

    diff --git a/man/tip/nng_random.3supp.html b/man/tip/nng_random.3supp.html new file mode 100644 index 00000000..8397d80f --- /dev/null +++ b/man/tip/nng_random.3supp.html @@ -0,0 +1,574 @@ +--- +version: tip +layout: refman +--- + + + + + + + +nng_random(3supp) + + + + + + + +
    +
    +

    SYNOPSIS

    +
    +
    +
    +
    #include <nng/nng.h>
+#include <nng/supplemental/util/platform.h>
+
+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

    +
    +
    +

    Random number.

    +
    +
    +
    +
    +

    ERRORS

    +
    +
    +

    None.

    +
    +
    +
    +
    +

    SEE ALSO

    +
    +
    +

    nng(7)

    +
    +
    +
    +
    + + diff --git a/man/tip/nng_rep.7.html b/man/tip/nng_rep.7.html index 35f66d97..95cafefa 100644 --- a/man/tip/nng_rep.7.html +++ b/man/tip/nng_rep.7.html @@ -511,6 +511,7 @@ body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-b
  • DESCRIPTION
    • @@ -528,9 +529,7 @@ body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-b
    -
    #include <nng/protocol/reqrep0/rep.h>
-
-int nng_rep0_open(nng_socket *s);
    +
    #include <nng/protocol/reqrep0/rep.h>
    @@ -567,20 +566,37 @@ a reply is received.

    Socket Operations

    -

    The nng_rep0_open() call creates a replier socket. +

    The nng_rep0_open() functions create a replier socket. This socket may be used to receive messages (requests), and then to send -replies. -Generally a reply can only be sent after receiving a request. -(Attempts to receive a message will result in NNG_ESTATE if there -is no outstanding request.)

    +replies.

    -

    Attempts to send on a socket with no outstanding requests will result -in NNG_ESTATE.

    +

    Generally a reply can only be sent after receiving a request.

    -

    Raw mode sockets (set with NNG_OPT_RAW) -ignore all these restrictions.

    +

    Send operations will result in NNG_ESTATE if no corresponding request +was previously received.

    +
    +
    +

    Likewise, only one receive operation may be pending at a time. +Any additional concurrent receive operations will result in NNG_ESTATE.

    +
    +
    +

    Raw mode sockets ignore all these restrictions.

    +
    +
    +
    +

    Context Operations

    +
    +

    This protocol supports the creation of contexts for concurrent +use cases using nng_ctx_open().

    +
    +
    +

    Each context may have at most one outstanding request, and operates +independently from the others. +The restrictions for order of operations with sockets apply equally +well for contexts, except that each context will be treated as if it were +a separate socket.

    diff --git a/man/tip/nng_rep_open.3.html b/man/tip/nng_rep_open.3.html index ba51bcf3..84c36b63 100644 --- a/man/tip/nng_rep_open.3.html +++ b/man/tip/nng_rep_open.3.html @@ -540,13 +540,18 @@ body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-b

    The nng_rep0_open() function creates a rep version 0 socket and returns it at the location pointed to by s.

    +
    +

    The nng_rep0_open_raw() function creates a rep version 0 +socket +in raw mode and returns it at the location pointed to by s.

    +

    RETURN VALUES

    -

    This function returns 0 on success, and non-zero otherwise.

    +

    These functions return 0 on success, and non-zero otherwise.

    diff --git a/man/tip/nng_req.7.html b/man/tip/nng_req.7.html index a7a8f9a1..dee53ce8 100644 --- a/man/tip/nng_req.7.html +++ b/man/tip/nng_req.7.html @@ -511,6 +511,7 @@ body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-b
  • DESCRIPTION