From bf310e1e3907d93398a7c4e4612da575628651db Mon Sep 17 00:00:00 2001 From: Garrett D'Amore Date: Tue, 24 Apr 2018 20:04:33 -0700 Subject: man page updates for tip --- man/tip/index.html | 4 + man/tip/nn_getsockopt.3compat.html | 22 +- man/tip/nn_poll.3compat.html | 716 +++++++++++++++++++++++++++++++++++++ man/tip/nn_setsockopt.3compat.html | 19 + man/tip/nng_compat.3compat.html | 8 + man/tip/nng_options.5.html | 28 -- man/tip/nng_respondent.7.html | 17 + man/tip/nng_surveyor.7.html | 32 ++ 8 files changed, 815 insertions(+), 31 deletions(-) create mode 100644 man/tip/nn_poll.3compat.html (limited to 'man') diff --git a/man/tip/index.html b/man/tip/index.html index b5d8d84a..6f345b71 100644 --- a/man/tip/index.html +++ b/man/tip/index.html @@ -928,6 +928,10 @@ from the older libnanomsg library.

get socket option (compatible API)

+

nn_poll(3compat)

+

poll sockets (compatible API)

+ +

nn_reallocmsg(3compat)

reallocate message (compatible API)

diff --git a/man/tip/nn_getsockopt.3compat.html b/man/tip/nn_getsockopt.3compat.html index 7ee28091..9099a5ed 100644 --- a/man/tip/nn_getsockopt.3compat.html +++ b/man/tip/nn_getsockopt.3compat.html @@ -785,7 +785,9 @@ to the value that the socket was created with.

This option returns a file descriptor suitable for use in with poll() or select() (or other system-specific polling functions). This descriptor will be readable when a message is available for receiving -at the socket.

+at the socket. +This option is of type int on all systems except Windows, where it is of +type SOCKET.

@@ -804,12 +806,14 @@ and is not the same as any underlying descriptor used for network sockets.
-
NN_RCVFD
+
NN_SNDFD

This option returns a file descriptor suitable for use in with poll() or select() (or other system-specific polling functions). This descriptor will be readable when the socket is able to accept a message -for sending.

+for sending. +This option is of type int on all systems except Windows, where it is of +type SOCKET.

@@ -827,6 +831,10 @@ Furthermore, the file descriptor should only be polled for readability. +
+

The following option is available for NN_REQ sockets +using the NN_REQ level:

+
NN_REQ_RESEND_IVL
@@ -836,6 +844,14 @@ If an NN_REQ socket does not receive a reply to a request within th period of time, the socket will automatically resend the request. The default value is 60000 (one minute).

+
+
+
+

The following option is available for NN_SURVEYOR sockets +using the NN_SURVEYOR level:

+
+
+
NN_SURVEYOR_DEADLINE

Survey deadline in milliseconds for NN_SURVEYOR sockets. diff --git a/man/tip/nn_poll.3compat.html b/man/tip/nn_poll.3compat.html new file mode 100644 index 00000000..ca493675 --- /dev/null +++ b/man/tip/nn_poll.3compat.html @@ -0,0 +1,716 @@ +--- +version: tip +layout: refman +--- + + + + + + + +nn_poll(3compat) + + + + + + +

+
+
+

SYNOPSIS

+
+
+
+
#include <nanomsg/nn.h>
+
+#define NN_POLLIN  1
+#define NN_POLLOUT 2
+
+struct nn_pollfd {
+    int      fd;
+    uint16_t events;
+    uint16_t revents;
+};
+
+int nn_poll(struct nn_pollfd *pfds, int npfd, int timeout);
+
+
+
+
+
+

DESCRIPTION

+
+
+

The nn_poll() function polls a group of sockets for readiness to send or receive.

+
+
+ + + + + +
+ + +This function is provided for API +compatibility with legacy libnanomsg. +Consider using the relevant modern API instead. +
+
+
+

The array of nfds sockets to poll for are passed into pfds. +Each member of this array is initialized with the fd field set to +the socket, and the events field set to a mask that can contain either or both +of the flags NN_POLLIN and NN_POLLOUT.

+
+
+

The flag NN_POLLIN indicates that a socket is ready for receiving without +blocking (a message is avaiable on the socket), and the flag NN_POLLOUT +indicates that a socket is ready for sending without blocking.

+
+
+

Upon success, the function returns the number of updates the revents +field of each member of the pfds array, setting it to indicate +whether the requested status is true or not.

+
+
+ + + + + +
+ + +The revents field will only have a flag set if the corresponding +flag was also set in the events field. +
+
+
+

If the timeout field is positive, then this function will wait for +up the that many milliseconds. +If none of the requested events occurs before that timeout occurs, then +the function will return -1 and set the error to ETIMEDOUT.

+
+
+

If the timeout is zero, then this function will return immediately, +after updating the current status of the sockets.

+
+
+

If the timeout is -1, then the function waits forever, or until one of the +requested events occurs.

+
+
+ + + + + +
+ + +This function is only suitable for use with sockets obtained with the +nn_socket()` function, and is not compatible +with file descriptors obtained via any other means. +This includes file descriptors obtained using the NN_SNDFD or NN_RCVFD +options with nn_getsockopt() +
+
+
+ + + + + +
+ + +This function is significantly less efficient than other polling +or asynchronous I/O mechanisms, and is provided for API compatibility only. +It’s use is discouraged. +
+
+
+ + + + + +
+ + +This function is not supported on systems other than POSIX derived +platforms and Windows. +
+
+
+
+
+

RETURN VALUES

+
+
+

This function returns the number of sockets with events on success, or -1 on error.

+
+
+
+
+

ERRORS

+
+
+ + + + + + + + + + + + + + + + + +
+ENOMEM + +

Insufficient memory available.

+
+EBADF + +

One of the sockets is not open.

+
+ETIMEDOUT + +

Operation timed out.

+
+ENOTSUP + +

This function is not supported on this platform.

+
+
+
+
+
+

SEE ALSO

+
+
+

nn_errno(3compat), +nn_recv(3compat), +nn_send(3compat), +nn_socket(3compat), +nn_compat(3compat), +nng(7)

+
+
+
+
+ + diff --git a/man/tip/nn_setsockopt.3compat.html b/man/tip/nn_setsockopt.3compat.html index 9e7fa052..326c1946 100644 --- a/man/tip/nn_setsockopt.3compat.html +++ b/man/tip/nn_setsockopt.3compat.html @@ -753,6 +753,10 @@ in configuring device forwarding.
+
+

The following option is available for NN_REQ sockets +using the NN_REQ level:

+
NN_REQ_RESEND_IVL
@@ -762,6 +766,13 @@ If an NN_REQ socket does not receive a reply to a request within th period of time, the socket will automatically resend the request. The default value is 60000 (one minute).

+
+
+
+

The following options are available for NN_SUB sockets using the NN_SUB level:

+
+
+
NN_SUB_SUBSCRIBE

Subscription topic, for NN_SUB sockets. @@ -791,6 +802,14 @@ To receive all messages, subscribe to an empty topic (sz equal to zero)

Removes a subscription topic that was earlier established.

+
+
+
+

The following option is available for NN_SURVEYOR sockets +using the NN_SURVEYOR level:

+
+
+
NN_SURVEYOR_DEADLINE

Survey deadline in milliseconds for NN_SURVEYOR sockets. diff --git a/man/tip/nng_compat.3compat.html b/man/tip/nng_compat.3compat.html index b61a8917..2a61f443 100644 --- a/man/tip/nng_compat.3compat.html +++ b/man/tip/nng_compat.3compat.html @@ -682,6 +682,14 @@ used in compilation. +nn_poll() + + +

poll sockets

+ + + + nn_device() diff --git a/man/tip/nng_options.5.html b/man/tip/nng_options.5.html index bde2e88a..7eb5bfcf 100644 --- a/man/tip/nng_options.5.html +++ b/man/tip/nng_options.5.html @@ -531,7 +531,6 @@ body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-b #define NNG_OPT_SOCKNAME "socket-name" #define NNG_OPT_RAW "raw" -#define NNG_OPT_LINGER "linger" #define NNG_OPT_RECVBUF "recv-buffer" #define NNG_OPT_SENDBUF "send-buffer" #define NNG_OPT_RECVFD "recv-fd" @@ -593,33 +592,6 @@ can have multiple dialers and endpoints associated with them. An attempt has been made to include details about such restrictions in the description of the option.

-
-
-
NNG_OPT_LINGER
-
-

-(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 -timeout has expired.

-
-
-
-
- - - - - -
- - -Not all transports support lingering, and -so closing a socket or exiting the application can still result in the loss -of undelivered messages. -
-
NNG_OPT_LOCADDR
diff --git a/man/tip/nng_respondent.7.html b/man/tip/nng_respondent.7.html index b51fb28c..373f9e10 100644 --- a/man/tip/nng_respondent.7.html +++ b/man/tip/nng_respondent.7.html @@ -511,6 +511,7 @@ body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-b
  • DESCRIPTION
    • +

    Context Operations

    +
    +

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

    +
    +
    +

    Incoming surveys will be routed to and received by only one context. +Additional surveys may be received by other contexts in parallel. +Replies made using a context will be returned to the the surveyor that +issued the survey most recently received by that context. +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.

    +
    +
    +

    Protocol Versions

    Only version 0 of this protocol is supported. diff --git a/man/tip/nng_surveyor.7.html b/man/tip/nng_surveyor.7.html index 8f07fb6c..48487ef8 100644 --- a/man/tip/nng_surveyor.7.html +++ b/man/tip/nng_surveyor.7.html @@ -511,6 +511,7 @@ body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-b

  • DESCRIPTION
    • +

    Context Operations

    +
    +

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

    +
    +
    +

    Each context can initiate its own surveys, and it will receive only +responses to its own outstanding surveys. +Other contexts on the same socket may have overlapping surveys +operating at the same time. +Each of these may have their own timeouts established with +NNG_OPT_SURVEYOR_SURVEYTIME. +Additionally, sending a survey on a context will only cancel an outstanding +survey on the same context.

    +
    +
    + + + + + +
    + + +Due to the best-effort nature of this protocol, if too may contexts +are attempting to perform surveys simultaneously, it is possible for either +individual outgoing surveys or incoming responses to be lost. +
    +
    +
    +

    Protocol Versions

    Only version 0 of this protocol is supported. -- cgit v1.2.3-70-g09d2