diff options
Diffstat (limited to 'docs/man')
| -rw-r--r-- | docs/man/nng_ctx.5.adoc | 7 | ||||
| -rw-r--r-- | docs/man/nng_dialer.5.adoc | 11 | ||||
| -rw-r--r-- | docs/man/nng_listener.5.adoc | 11 | ||||
| -rw-r--r-- | docs/man/nng_pipe.5.adoc | 11 | ||||
| -rw-r--r-- | docs/man/nng_socket.5.adoc | 9 |
5 files changed, 35 insertions, 14 deletions
diff --git a/docs/man/nng_ctx.5.adoc b/docs/man/nng_ctx.5.adoc index 4fcac571..98402738 100644 --- a/docs/man/nng_ctx.5.adoc +++ b/docs/man/nng_ctx.5.adoc @@ -19,7 +19,7 @@ nng_ctx - protocol context ---- #include <nng/nng.h> -typedef uint32_t nng_ctx +typedef struct nng_ctx_s nng_ctx ---- == DESCRIPTION @@ -38,6 +38,11 @@ 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. +IMPORTANT: The `nng_ctx` structure is always passed by value (both +for input parameters and return values), and should be treated opaquely. +Passing structures this way ensures gives the compiler a chance to perform +accurate type checks in functions passing values of this type. + 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. diff --git a/docs/man/nng_dialer.5.adoc b/docs/man/nng_dialer.5.adoc index daadbd0b..45c60bc9 100644 --- a/docs/man/nng_dialer.5.adoc +++ b/docs/man/nng_dialer.5.adoc @@ -16,11 +16,11 @@ nng_dialer - dialer == SYNOPSIS [source, c] ------------ +---- #include <nng/nng.h> -typedef uint32_t nng_dialer; ------------ +typedef struct nng_dialer_s nng_dialer; +---- == DESCRIPTION @@ -38,6 +38,11 @@ Dialer objects are created by the or <<nng_dial.3#,`nng_dial()`>> functions, and are always "`owned`" by a single <<nng_socket.5#,`nng_socket`>>. +IMPORTANT: The `nng_dialer` structure is always passed by value (both +for input parameters and return values), and should be treated opaquely. +Passing structures this way ensures gives the compiler a chance to perform +accurate type checks in functions passing values of this type. + TIP: A given <<nng_socket.5#,`nng_socket`>> may have multiple dialer objects, multiple <<nng_listener.5#,listener>> objects, or even some of both. diff --git a/docs/man/nng_listener.5.adoc b/docs/man/nng_listener.5.adoc index 6c5d0bd0..558eb920 100644 --- a/docs/man/nng_listener.5.adoc +++ b/docs/man/nng_listener.5.adoc @@ -16,11 +16,11 @@ nng_listener - listener == SYNOPSIS [source, c] ------------ +---- #include <nng/nng.h> -typedef uint32_t nng_listener; ------------ +typedef struct nng_listener_s nng_listener; +---- == DESCRIPTION @@ -35,6 +35,11 @@ Listener objects are created by the or <<nng_listen.3#,`nng_listen()`>> functions, and are always "`owned`" by a single <<nng_socket.5#,`nng_socket`>>. +IMPORTANT: The `nng_listener` structure is always passed by value (both +for input parameters and return values), and should be treated opaquely. +Passing structures this way ensures gives the compiler a chance to perform +accurate type checks in functions passing values of this type. + TIP: A given <<nng_socket.5#,`nng_socket`>> may have multiple listener objects, multiple <<nng_dialer.5#,dialer>> objects, or even some of both. diff --git a/docs/man/nng_pipe.5.adoc b/docs/man/nng_pipe.5.adoc index 4befd3e8..39247fbd 100644 --- a/docs/man/nng_pipe.5.adoc +++ b/docs/man/nng_pipe.5.adoc @@ -16,11 +16,11 @@ nng_pipe - communications pipe == SYNOPSIS [source, c] ------------ +---- #include <nng/nng.h> -typedef uint32_t nng_pipe; ------------ +typedef struct nng_pipe_s nng_pipe; +---- == DESCRIPTION @@ -32,6 +32,11 @@ single TCP or IPC connection.) Pipes are associated with either the listener or dialer that created them, and therefore are also automatically associated with a single socket. +IMPORTANT: The `nng_pipe` structure is always passed by value (both +for input parameters and return values), and should be treated opaquely. +Passing structures this way ensures gives the compiler a chance to perform +accurate type checks in functions passing values of this type. + TIP: Most applications should never concern themselves with individual pipes. However it is possible to access a pipe when more information about the source of a message is needed, or when more control is required over diff --git a/docs/man/nng_socket.5.adoc b/docs/man/nng_socket.5.adoc index 0dcdfa99..4711495f 100644 --- a/docs/man/nng_socket.5.adoc +++ b/docs/man/nng_socket.5.adoc @@ -19,7 +19,7 @@ nng_socket - socket handle ---- #include <nng/nng.h> -typedef uint32_t nng_socket; +typedef struct nng_socket_s nng_socket; ---- == DESCRIPTION @@ -34,9 +34,10 @@ may be connected to multiple transports at the same time. However, a given socket will have exactly one "`protocol`" associated with it, and is responsible for any state machines or other protocol-specific logic. -NOTE: Although `nng_socket` is an integer data type, these objects are not -ordinary file descriptors, and can only be used with the functions that -explicitly indicate that it safe and appropropate to do so. +IMPORTANT: The `nng_socket` structure is always passed by value (both +for input parameters and return values), and should be treated opaquely. +Passing structures this way ensures gives the compiler a chance to perform +accurate type checks in functions passing values of this type. Each `nng_socket` is created by a protocol-specific constructor, such as <<nng_rep_open.3#,`nng_rep_open()`>>. |