Skip to content

Commit

Permalink
Markup changes, started adding type documentation.
Browse files Browse the repository at this point in the history
  • Loading branch information
gdamore committed Mar 14, 2018
1 parent 7092fa3 commit f4de6b5
Show file tree
Hide file tree
Showing 4 changed files with 157 additions and 38 deletions.
49 changes: 49 additions & 0 deletions docs/man/nng_duration.adoc
Original file line number Diff line number Diff line change
@@ -0,0 +1,49 @@
= nng_duration(5)
//
// Copyright 2018 Staysail Systems, Inc. <[email protected]>
// Copyright 2018 Capitar IT Group BV <[email protected]>
//
// This document is supplied under the terms of the MIT License, a
// copy of which should be located in the distribution where this
// file was obtained (LICENSE.txt). A copy of the license may also be
// found online at https://opensource.org/licenses/MIT.
//

== NAME

nng_duration - relative time in milliseconds

== SYNOPSIS

[source, c]
-----------
#include <nng/nng.h>
typedef int32_t nng_duration;
#define NNG_DURATION_INFINITE (-1)
#define NNG_DURATION_DEFAULT (-2)
#define NNG_DURATION_ZERO (0)
-----------

== DESCRIPTION

An ((`nng_duration`))(((duration))) is a relative time, measured in
milliseconds.
This type is most often used in conjuction with timers and timeouts.

A couple of special values have been set aside, and carry special meanings.

[[NNG_DURATION_DEFAULT]]((`NNG_DURATION_DEFAULT`)):::
Indicates a context-specific default value should be used.

[[NNG_DURATION_INFINITE]]((`NNG_DURATION_INFINITE`)):::
Effectively an infinite duration; used most often to disable timeouts.

[[NNG_DURATION_ZERO]]((`NNG_DURATION_ZERO`)):::
Zero length duration; used to perform a single polling operation.

== SEE ALSO
[.text-left]
<<nng_options#,nng_options(5)>>,
<<nng#,nng(7)>>
73 changes: 44 additions & 29 deletions docs/man/nng_options.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -39,14 +39,24 @@ nng_options - socket, dialer, listener, and pipe options

== DESCRIPTION

This page documents the various standard options that can be used
with sockets (see `<<nng_getopt#,nng_getopt(3)>>`
and `<<nng_setopt#,nng_setopt(3)>>`),
dialers (see `<<nng_dialer_getopt#,nng_dialer_getopt(3)>>`
and `<<nng_dialer_setopt#,nng_dialer_setopt(3)>>`),
listeners (see `<<nng_listener_getopt#,nng_listener_getopt(3)>>`
and `<<nng_listener_setopt#,nng_listener_setopt(3)>>`),
and pipes (see `<<nng_pipe_getopt#,nng_pipe_getopt(3)>>`).
This page documents the various standard options that can be set or
retrieved on objects in the _nng_ library.

Sockets (<<nng_socket#,`nng_socket`>>) use the functions
<<nng_getopt#,`nng_getopt()`>>
and <<nng_setopt#,`nng_setopt()`>> to set and retrieve option values.

Dialers (<<nng_dialer#,`nng_dialer`>>) use the functions
<<nng_dialer_getopt#,`nng_dialer_getopt()`>> and
<<nng_dialer_setopt#,`nng_dialer_setopt()`>> to set and retrieve option values.

Listeners (<<nng_listener#,`nng_listener`>>) use the functions
<<nng_listener_getopt#,`nng_listener_getopt()`>>
and <<nng_listener_setopt#,`nng_listener_setopt()`>> to set and retrieve option
values.

Pipes (<<nng_pipe#,`nng_pipe`>>) can only retrieve option values using
the <<nng_pipe_getopt#,`nng_pipe_getopt()`>> function.

In addition to the options listed here, transports and protocols will generally
have some of their own options, which will be documented with the transport
Expand All @@ -65,7 +75,7 @@ description of the option.
[[NNG_OPT_LINGER]]
((`NNG_OPT_LINGER`))::
(((lingering)))
(`<<nng_types#nng_duration,nng_duration>>`)
(`<<nng_duration#,nng_duration>>`)
This is the linger time of the socket in milliseconds.
When this value is non-zero, then the system will
attempt to defer closing until it has undelivered data, or until the specified
Expand All @@ -77,7 +87,7 @@ of undelivered messages.

[[NNG_OPT_LOCADDR]]
((`NNG_OPT_LOCADDR`))::
(`<<nng_types#nng_sockaddr,nng_sockaddr>>`)
(`<<nng_sockaddr#,nng_sockaddr>>`)
This read-only option may be used on listeners, dialers and connected pipes, and
represents the local address used for communication.
Not all transports support this option, and some transports may support it
Expand All @@ -93,14 +103,14 @@ 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 an <<nng_rep#,nng_rep(7)>> socket would
(For example, in "`cooked`" mode an <<nng_rep#,nng_rep>> socket would
automatically copy message headers from a received message to the corresponding
reply, whereas in "`raw`" mode this is not done.)

[[NNG_OPT_RECONNMINT]]
((`NNG_OPT_RECONNMINT`))::
(((reconnect time, minimum)))
(`<<nng_types#nng_duration,nng_duration>>`)
(`<<nng_duration#,nng_duration>>`)
This is the minimum amount of time (milliseconds) to wait before attempting
to establish a connection after a previous attempt has failed.
This can be set on a socket, but it can also be overridden on an individual
Expand All @@ -111,7 +121,7 @@ The option is irrelevant for listeners.
((`NNG_OPT_RECONNMAXT`))::
(((`NNG_OPT_RECONNMAXT`)))
(((reconnect time, maximum)))
(`<<nng_types#nng_duration,nng_duration>>`)
(`<<nng_duration#,nng_duration>>`)
This is the maximum amount of time
(milliseconds) to wait before attempting to establish a connection after
a previous attempt has failed.
Expand Down Expand Up @@ -141,8 +151,12 @@ has accepted them for delivery.
(((receive, polling)))
(`int`)
This read-only option is used to obtain an integer file descriptor suitable
for use in `poll()`, `select()`, (or on Windows systems `WSApoll()`) and
similar functions.
for use with
http://pubs.opengroup.org/onlinepubs/7908799/xsh/poll.html[`poll()`],
http://pubs.opengroup.org/onlinepubs/7908799/xsh/select.html[`select()`],
(or on Windows systems
https://msdn.microsoft.com/en-us/library/windows/desktop/ms741669(v=vs.85).aspx[`WSAPoll()`])
and similar functions.
This descriptor will be *readable* when a message is available for receiving
on the socket.
When no message is ready for receiving, then this file descriptor will *not*
Expand All @@ -151,14 +165,14 @@ be readable.
IMPORTANT: Appplications should never attempt to read or write to the
returned file descriptor.
Furthermore, applications should not attempt to use the actual socket (of
type `<<nng_types#nng_socket,nng_socket>>`) with polling functions,
type <<nng_socket#,`nng_socket`>>) with polling functions,
since it is merely an internal
identifier and will not necessarily referency any operting system object or
handle.

TIP: While this option may help applications integrate into existing polling
loops, it is more efficient, and often easier, to use the asynchronous I/O
objects instead. See `<<nng_aio_alloc#,nng_aio_alloc(3)>>`.
objects instead. See <<nng_aio_alloc#,`nng_aio_alloc()`>>.

[[NNG_OPT_RECVMAXSZ]]
((`NNG_OPT_RECVMAXSZ`))::
Expand All @@ -180,14 +194,14 @@ NOTE: Some transports may have further message size restrictions!
((`NNG_OPT_RECVTIMEO`))::
(((receive, timeout)))
(((timeout, receive)))
(`<<nng_types#nng_duration,nng_duration>>`)
(`<<nng_duration#,nng_duration>>`)
This is the socket receive timeout in milliseconds.
When no message is available for receiving at the socket for this period of
time, receive operations will fail with a return value of `NNG_ETIMEDOUT`.

[[NNG_OPT_REMADDR]]
((`NNG_OPT_REMADDR`))::
(`<<nng_types#nng_sockaddr,nng_sockaddr>>`)
(`<<nng_sockaddr#,nng_sockaddr>>`)
This read-only option may be used on dialers and connected pipes, and
represents the address of a remote peer.
Not all transports support this option.
Expand All @@ -203,7 +217,7 @@ transport is ready to accept them for delivery.
This value must be an integer between 0 and 8192, inclusive.

NOTE: Not all protocols support buffering sent messages;
generally multicast protocols like <<nng_pub#,nng_pub(7)>> will
generally multicast protocols like <<nng_pub#,nng_pub>> will
simply discard messages when they cannot be delivered immediately.

[[NNG_OPT_SENDFD]]
Expand All @@ -213,8 +227,12 @@ simply discard messages when they cannot be delivered immediately.
(((send, polling)))
(`int`)
This read-only option is used to obtain an integer file descriptor suitable
for use in `poll()`, `select()`, (or on Windows systems `WSApoll()`) and
similar functions.
for use with
http://pubs.opengroup.org/onlinepubs/7908799/xsh/poll.html[`poll()`],
http://pubs.opengroup.org/onlinepubs/7908799/xsh/select.html[`select()`],
(or on Windows systems
https://msdn.microsoft.com/en-us/library/windows/desktop/ms741669(v=vs.85).aspx[`WSAPoll()`])
and similar functions.
This descriptor will be *readable* when the socket is able to accept a
message for sending without blocking.
When the socket is no longer able to accept such messages without blocking,
Expand All @@ -223,20 +241,20 @@ the descriptor will *not* be readable.
IMPORTANT: Appplications should never attempt to read or write to the
returned file descriptor.
Furthermore, applications should not attempt to use the actual socket (of
type `<<nng_types#nng_socket,nng_socket>>`) with polling functions,
type <<nng_socket#,`nng_socket`>>) with polling functions,
since it is merely an internal
identifier and will not necessarily referency any operting system object or
handle.

TIP: While this option may help applications integrate into existing polling
loops, it is more efficient, and often easier, to use the asynchronous I/O
objects instead. See `<<nng_aio_alloc#,nng_aio_alloc(3)>>`.
objects instead. See <<nng_aio_alloc#,`nng_aio_alloc`()>>.

[[NNG_OPT_SENDTIMEO]]
((`NNG_OPT_SENDTIMEO`))::
(((send, timeout)))
(((timeout, send)))
(`<<nng_types#nng_duration,nng_duration>>`)
(`<<nng_duration#,nng_duration>>`)
This is the socket send timeout in milliseconds.
When a message cannot be queued for delivery by the socket for this period of
time (such as if send buffers are full), the operation will fail with a
Expand All @@ -256,12 +274,9 @@ The string must fit within 64-bytes, including the terminating
(`int`)
(((time-to-live)))
This is the maximum number of "`hops`" a message may traverse (see
`<<nng_device#,nng_device(3)>>`).
<<nng_device#,`nng_device()`>>).
The intention here is to prevent ((forwarding loops)) in device chains.

// ((`NNG_OPT_REMADDR`)):: Endpoint specific, readonly
// ((`NNG_OPT_LOCADDR`)):: Endpoint specific, readonly

[[NNG_OPT_URL]]
((`NNG_OPT_URL`))::
(((URI)))
Expand Down
54 changes: 54 additions & 0 deletions docs/man/nng_socket.adoc
Original file line number Diff line number Diff line change
@@ -0,0 +1,54 @@
= nng_socket(5)
//
// Copyright 2018 Staysail Systems, Inc. <[email protected]>
// Copyright 2018 Capitar IT Group BV <[email protected]>
//
// This document is supplied under the terms of the MIT License, a
// copy of which should be located in the distribution where this
// file was obtained (LICENSE.txt). A copy of the license may also be
// found online at https://opensource.org/licenses/MIT.
//

== NAME

nng_socket - socket handle

== SYNOPSIS

[source, c]
-----------
#include <nng/nng.h>
typedef uint32_t nng_socket;
-----------

== DESCRIPTION

An ((`nng_socket`))(((socket))) is a handle to an underlying "`socket`" object.
All communication between the application and remote Scalability Protocol
peers is done through sockets.
A given socket can have multiple dialers (<<nng_dialer#,`nng_dialer`>>)
and/or (<<nng_listener#,`nng_listener`>>), and multiple
pipes (<<nng_pipe#,`nng_pipe`>>), and
may be connected to multiple transports at the same time.
However, a given socket will have exactly one "`protocol`" associated with it,
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.

Each `nng_socket` is created by a protocol-specific constructor, such as
<<nng_rep0_open#,`nng_rep0_open()`>>.
When the socket is no longer needed, it can be closed with
<<nng_close#,`nng_close()`>>.

== SEE ALSO

[.text-left]
<<libnng#,libnng(3)>>,
<<nng_close#,nng_close(3)>>,
<<nng_dialer#,nng_dialer(5)>>,
<<nng_listener#,nng_listener(5)>>,
<<nng_options#,nng_options(5)>>,
<<nng#,nng(7)>>
19 changes: 10 additions & 9 deletions docs/man/nng_version.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -24,27 +24,28 @@ const char * nng_version(void);

== DESCRIPTION

The `nng_version()` function returns a human readable version
number for the _nng_ library. This is intended for output in
programs, and so forth.
The ((`nng_version()`)) function returns a human readable ((version number))
for the _nng_ library.
This is intended for output in programs, and so forth.

Additionally, compile time version information is available
via some predefined macros:

`NNG_MAJOR_VERSION`:: Major version number.
`NNG_MINOR_VERSION`:: Minor version number.
`NNG_PATCH_VERSION`:: Patch version number.
((`NNG_MAJOR_VERSION`)):: Major version number.
((`NNG_MINOR_VERSION`)):: Minor version number.
((`NNG_PATCH_VERSION`)):: Patch version number.

The _nng_ library is developed and released using
http:///www.semver.org[Semantic Versioning 2.0], and
http://www.semver.org[Semantic Versioning 2.0], and
the version numbers reported refer to both the API and the
library itself. (The ABI -- binary interface -- between the
library itself.
(The ((ABI)) -- ((application binary interface)) -- between the
library and the application is controlled in a similar, but different
manner depending upon the link options and how the library is built.)

== RETURN VALUES

C string (NUL-terminated) containing the library version number.
C string (`NUL`-terminated) containing the library version number.

== ERRORS

Expand Down

0 comments on commit f4de6b5

Please sign in to comment.