From f4de6b5302df8befbd2b229b701d0bf9ca81a5fb Mon Sep 17 00:00:00 2001 From: Garrett D'Amore Date: Wed, 14 Mar 2018 15:19:26 -0700 Subject: Markup changes, started adding type documentation. --- docs/man/nng_options.adoc | 73 ++++++++++++++++++++++++++++------------------- 1 file changed, 44 insertions(+), 29 deletions(-) (limited to 'docs/man/nng_options.adoc') diff --git a/docs/man/nng_options.adoc b/docs/man/nng_options.adoc index 045618b3..9546e0dc 100644 --- a/docs/man/nng_options.adoc +++ b/docs/man/nng_options.adoc @@ -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 `<>` -and `<>`), -dialers (see `<>` -and `<>`), -listeners (see `<>` -and `<>`), -and pipes (see `<>`). +This page documents the various standard options that can be set or +retrieved on objects in the _nng_ library. + +Sockets (<>) use the functions +<> +and <> to set and retrieve option values. + +Dialers (<>) use the functions +<> and +<> to set and retrieve option values. + +Listeners (<>) use the functions +<> +and <> to set and retrieve option +values. + +Pipes (<>) can only retrieve option values using +the <> 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 @@ -65,7 +75,7 @@ description of the option. [[NNG_OPT_LINGER]] ((`NNG_OPT_LINGER`)):: (((lingering))) -(`<>`) +(`<>`) 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 @@ -77,7 +87,7 @@ of undelivered messages. [[NNG_OPT_LOCADDR]] ((`NNG_OPT_LOCADDR`)):: -(`<>`) +(`<>`) 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 @@ -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 <> socket would +(For example, in "`cooked`" mode an <> 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))) -(`<>`) +(`<>`) 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 @@ -111,7 +121,7 @@ The option is irrelevant for listeners. ((`NNG_OPT_RECONNMAXT`)):: (((`NNG_OPT_RECONNMAXT`))) (((reconnect time, maximum))) -(`<>`) +(`<>`) This is the maximum amount of time (milliseconds) to wait before attempting to establish a connection after a previous attempt has failed. @@ -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* @@ -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 `<>`) with polling functions, +type <>) 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 `<>`. +objects instead. See <>. [[NNG_OPT_RECVMAXSZ]] ((`NNG_OPT_RECVMAXSZ`)):: @@ -180,14 +194,14 @@ NOTE: Some transports may have further message size restrictions! ((`NNG_OPT_RECVTIMEO`)):: (((receive, timeout))) (((timeout, receive))) -(`<>`) +(`<>`) 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`)):: -(`<>`) +(`<>`) 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. @@ -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 <> will +generally multicast protocols like <> will simply discard messages when they cannot be delivered immediately. [[NNG_OPT_SENDFD]] @@ -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, @@ -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 `<>`) with polling functions, +type <>) 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 `<>`. +objects instead. See <>. [[NNG_OPT_SENDTIMEO]] ((`NNG_OPT_SENDTIMEO`)):: (((send, timeout))) (((timeout, send))) -(`<>`) +(`<>`) 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 @@ -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 -`<>`). +<>). 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))) -- cgit v1.2.3-70-g09d2