From edd3b6bc34f211bd3d58642d0c69ce1b5bb9dc3b Mon Sep 17 00:00:00 2001 From: gdamore Date: Thu, 9 Oct 2025 01:22:20 +0000 Subject: deploy: 9c834956456924df7c885ab8b79573721acaff5c --- ref/api/sock.html | 124 +++++++++++++++++++++++++++--------------------------- 1 file changed, 62 insertions(+), 62 deletions(-) (limited to 'ref/api/sock.html') diff --git a/ref/api/sock.html b/ref/api/sock.html index 81698cce..e0b4bef9 100644 --- a/ref/api/sock.html +++ b/ref/api/sock.html @@ -278,7 +278,7 @@ names of the socket’s protocol, and of the protocol peers of the socket use. The value stored in name is a fixed string located in program text, and must not be freed or altered. It is guaranteed to remain valid while this library is present.

The nng_socket_raw function determines whether the socket is in -raw mode or not, storing true in raw if it is, or false if it is not.

+raw mode or not, storing true in raw if it is, or false if it is not.

Opening a Socket

int nng_bus0_open(nng_socket *s);
 int nng_pub0_open(nng_socket *s);
@@ -295,18 +295,18 @@ The constructors for sockets are protocol specific so please refer to protocol d
 for more specific information.

 
The following functions open a socket in normal mode:

 
    
-
  • nng_bus0_open - BUS version 0
    • 
-
  • nng_pair0_open - PAIR version 0
    • 
-
  • nng_pair1_open - PAIR version 1
    • 
-
  • nng_pair1_open_poly - PAIR version 1, polyamorous mode
    • 
-
  • nng_pub0_open - PUB version 0
    • 
-
  • nng_pull0_open - PULL version 0
    • 
-
  • nng_push0_open - PUSH version 0
    • 
-
  • nng_rep0_open - REP version 0
    • 
-
  • nng_req0_open - REQ version 0
    • 
-
  • nng_respondent0_open - RESPONDENT version 0
    • 
-
  • nng_sub0_open - SUB version 0
    • 
-
  • nng_surveyor0_open - SURVEYOR version 0
    • 
+
  • nng_bus0_open - BUS version 0
    • 
+
  • nng_pair0_open - PAIR version 0
    • 
+
  • nng_pair1_open - PAIR version 1
    • 
+
  • nng_pair1_open_poly - PAIR version 1, polyamorous mode
    • 
+
  • nng_pub0_open - PUB version 0
    • 
+
  • nng_pull0_open - PULL version 0
    • 
+
  • nng_push0_open - PUSH version 0
    • 
+
  • nng_rep0_open - REP version 0
    • 
+
  • nng_req0_open - REQ version 0
    • 
+
  • nng_respondent0_open - RESPONDENT version 0
    • 
+
  • nng_sub0_open - SUB version 0
    • 
+
  • nng_surveyor0_open - SURVEYOR version 0
    • 
 

 
Raw Mode Sockets

 
int nng_bus0_open_raw(nng_socket *s);
@@ -334,36 +334,36 @@ the protocol specific processing must be performed by the application.

   tip
 

 
Most applications do not need to use raw sockets.
-The notable exception is when using nng_device, which requires raw sockets.
-To obtain asynchronous behavior, consider using contexts instead.

+The notable exception is when using nng_device, which requires raw sockets.
+To obtain asynchronous behavior, consider using contexts instead.

 
-
The following functions open a socket in raw mode:

+
The following functions open a socket in raw mode:

 
    
-
  • nng_bus0_open_raw - BUS version 0, raw mode
    • 
-
  • nng_pair0_open_raw - PAIR version 0, raw mode
    • 
-
  • nng_pair1_open_raw - PAIR version 1, raw mode
    • 
-
  • nng_pub0_open_raw - PUB version 0, raw mode
    • 
-
  • nng_pull0_open_raw - PULL version 0, raw mode
    • 
-
  • nng_push0_open_raw - PUSH version 0, raw mode
    • 
-
  • nng_rep0_open_raw - REP version 0, raw mode
    • 
-
  • nng_req0_open_raw - REP version 0, raw mode
    • 
-
  • nng_respondent0_open_raw - RESPONDENT version 0, raw mode
    • 
-
  • nng_sub0_open_raw - SUB version 0, raw mode
    • 
-
  • nng_surveyor0_open_raw - SURVEYOR version 0, raw mode
    • 
+
  • nng_bus0_open_raw - BUS version 0, raw mode
    • 
+
  • nng_pair0_open_raw - PAIR version 0, raw mode
    • 
+
  • nng_pair1_open_raw - PAIR version 1, raw mode
    • 
+
  • nng_pub0_open_raw - PUB version 0, raw mode
    • 
+
  • nng_pull0_open_raw - PULL version 0, raw mode
    • 
+
  • nng_push0_open_raw - PUSH version 0, raw mode
    • 
+
  • nng_rep0_open_raw - REP version 0, raw mode
    • 
+
  • nng_req0_open_raw - REP version 0, raw mode
    • 
+
  • nng_respondent0_open_raw - RESPONDENT version 0, raw mode
    • 
+
  • nng_sub0_open_raw - SUB version 0, raw mode
    • 
+
  • nng_surveyor0_open_raw - SURVEYOR version 0, raw mode
    • 
 

 
Closing a Socket

 
int nng_socket_close(nng_socket s);
 

 
The nng_socket_close function closes a socket, releasing all resources
 associated with it. Any operations that are in progress will be terminated with
-a result of NNG_ECLOSED.

+a result of NNG_ECLOSED.

 

 

   
   note
 

-
Closing a socket also invalidates any dialers, listeners,
-pipes, or contexts associated with it.

+
Closing a socket also invalidates any dialers, listeners,
+pipes, or contexts associated with it.

 

 

 

@@ -396,8 +396,8 @@ messages over the socket s. The differences in their behaviors are as f
 
The semantics of what sending a message means varies from protocol to
 protocol, so examination of the protocol documentation is encouraged.
 Additionally, some protocols may not support sending at all or may require other pre-conditions first.
-(For example, REP sockets cannot normally send data until they have first received a request,
-while SUB sockets can only receive data and never send it.)

+(For example, REP sockets cannot normally send data until they have first received a request,
+while SUB sockets can only receive data and never send it.)

 

 
nng_send

 
The nng_send function is the simplest to use, but is the least efficient.
@@ -406,7 +406,7 @@ made up of zero or more of the following values:

 
    
 
  • NNG_FLAG_NONBLOCK: 
 If the socket cannot accept more data at this time, it does not block, but returns immediately
-with a status of NNG_EAGAIN. If this flag is absent, the function will wait until data can be sent.
    • 
+with a status of NNG_EAGAIN. If this flag is absent, the function will wait until data can be sent.
 

 

 

@@ -417,28 +417,28 @@ with a status of NNG_EAGAINNNG_FLAG_NONBLOCK,
-such as with PUB sockets, which are best-effort delivery only.

+such as with PUB sockets, which are best-effort delivery only.

 

 
nng_sendmsg

 
The nng_sendmsg function sends the msg over the socket s.

 
If this function returns zero, then the socket will dispose of msg when the transmission is complete.
 If the function returns a non-zero status, then the call retains the responsibility for disposing of msg.

-
The flags can contain the value NNG_FLAG_NONBLOCK, indicating that the function should not wait if the socket
-cannot accept more data for sending. In such a case, it will return NNG_EAGAIN.

+
The flags can contain the value NNG_FLAG_NONBLOCK, indicating that the function should not wait if the socket
+cannot accept more data for sending. In such a case, it will return NNG_EAGAIN.

 

 

   
   tip
 

-
This function is preferred over nng_send, as it gives access to the message structure and eliminates both
+
This function is preferred over nng_send, as it gives access to the message structure and eliminates both
 a data copy and allocation.

 

 
nng_socket_send

-
The nng_socket_send function sends a message asynchronously, using the nng_aio aio, over the socket s.
-The message to send must have been set on aio using the nng_aio_set_msg function.

+
The nng_socket_send function sends a message asynchronously, using the nng_aio aio, over the socket s.
+The message to send must have been set on aio using the nng_aio_set_msg function.

 
If the operation completes successfully, then the socket will have disposed of the message.
 However, if it fails, then callback of aio should arrange for a final disposition of the message.
-(The message can be retrieved from aio with nng_aio_get_msg.)

+(The message can be retrieved from aio with nng_aio_get_msg.)

 
Note that callback associated with aio may be called before the message is finally delivered to the recipient.
 For example, the message may be sitting in queue, or located in TCP buffers, or even in flight.

 

@@ -448,7 +448,7 @@ For example, the message may be sitting in queue, or located in TCP buffers, or
 

 
This is the preferred function to use for sending data on a socket. While it does require a few extra
 steps on the part of the application, the lowest latencies and highest performance will be achieved by using
-this function instead of nng_send or nng_sendmsg.

+this function instead of nng_send or nng_sendmsg.

 

 
Receiving Messages

 
int nng_recv(nng_socket s, void *data, size_t *sizep, int flags);
@@ -465,8 +465,8 @@ messages over the socket s. The differences in their behaviors are as f
 
The semantics of what receiving a message means varies from protocol to
 protocol, so examination of the protocol documentation is encouraged.
 Additionally, some protocols may not support receiving at all or may require other pre-conditions first.
-(For example, REQ sockets cannot normally receive data until they have first sent a request,
-while PUB sockets can only send data and never receive it.)

+(For example, REQ sockets cannot normally receive data until they have first sent a request,
+while PUB sockets can only send data and never receive it.)

 
 
nng_recv

 
The nng_recv function is the simplest to use, but is the least efficient.
@@ -476,23 +476,23 @@ It receives the content in data, as a message size (in bytes) of up to
 
    
 
  • NNG_FLAG_NONBLOCK:
 If the socket has no messages pending for reception at this time, it does not block, but returns immediately
-with a status of NNG_EAGAIN. If this flag is absent, the function will wait until data can be received.
    • 
+with a status of NNG_EAGAIN. If this flag is absent, the function will wait until data can be received.
 

 
nng_recvmsg

-
The nng_recvmsg function receives a message and stores a pointer to the nng_msg for that message in msgp.

-
The flags can contain the value NNG_FLAG_NONBLOCK, indicating that the function should not wait if the socket
-has no messages available to receive. In such a case, it will return NNG_EAGAIN.

+
The nng_recvmsg function receives a message and stores a pointer to the nng_msg for that message in msgp.

+
The flags can contain the value NNG_FLAG_NONBLOCK, indicating that the function should not wait if the socket
+has no messages available to receive. In such a case, it will return NNG_EAGAIN.

 

 

   
   tip
 

-
This function is preferred over nng_recv, as it gives access to the message structure and eliminates both
+
This function is preferred over nng_recv, as it gives access to the message structure and eliminates both
 a data copy and allocation.

 

 
nng_socket_recv

-
The nng_socket_send function receives a message asynchronously, using the nng_aio aio, over the socket s.
-On success, the received message can be retrieved from the aio using the nng_aio_get_msg function.

+
The nng_socket_send function receives a message asynchronously, using the nng_aio aio, over the socket s.
+On success, the received message can be retrieved from the aio using the nng_aio_get_msg function.

 

 

   
@@ -508,7 +508,7 @@ Failure to do so will leak the memory.

 

 
This is the preferred function to use for receiving data on a socket. While it does require a few extra
 steps on the part of the application, the lowest latencies and highest performance will be achieved by using
-this function instead of nng_recv or nng_recvmsg.

+this function instead of nng_recv or nng_recvmsg.

 

 
Socket Options

 
int nng_socket_get_bool(nng_socket s, const char *opt, bool *valp);
@@ -533,16 +533,16 @@ are available, whether they can be read or written, and the appropriate type to
   note
 

 
Socket options are are used to tune the behavior of the higher level protocol. To change the options
-for an underlying transport, the option should be set on the dialer or listener instead of the socket.

+for an underlying transport, the option should be set on the dialer or listener instead of the socket.

 
 
Common Options

 
The following options are available for many protocols, and always use the same types and semantics described below.

 

-
-
-
+
+
+
-
+
@@ -554,8 +554,8 @@ for an underlying transport, the option should be set on the 
   note
 

-
The NNG_OPT_RECONNMAXT, NNG_OPT_RECONNMINT, and NNG_OPT_RECVMAXSZ options are just the initial defaults that dialers
-(and for NNG_OPT_RECVMAXSZ also listeners)
+
The NNG_OPT_RECONNMAXT, NNG_OPT_RECONNMINT, and NNG_OPT_RECVMAXSZ options are just the initial defaults that dialers
+(and for NNG_OPT_RECVMAXSZ also listeners)
 will use. After the dialer or listener is created, changes to the socket’s value will have no affect on that dialer or listener.
Polling Socket Events

@@ -581,7 +581,7 @@ were available in previous versions of NNG.

   note
 

-
These functions are not compatible with contexts.

+
These functions are not compatible with contexts.

 

@@ -598,7 +598,7 @@ messages on the socket.

   tip
 

 
Using these functions will force the socket to perform extra system calls, and thus
-have a negative impact on performance and latency. It is preferable to use asynchronous I/O
+have a negative impact on performance and latency. It is preferable to use asynchronous I/O
 when possible.

 
Examples

@@ -606,7 +606,7 @@ when possible.
nng_socket s = NNG_SOCKET_INITIALIZER;
 
Example 2: Publishing a Timestamp

-
This example demonstrates the use of nng_aio, nng_socket_send, and nng_sleep_aio to
+
This example demonstrates the use of nng_aio, nng_socket_send, and nng_sleep_aio to
 build a service that publishes a timestamp at one second intervals. Error handling is elided for the
 sake of clarity.
#include <stdlib.h>
@@ -657,7 +657,7 @@ int main(int argc, char **argv) {
 }
 
Example 3: Watching a Periodic Timestamp

-
This example demonstrates the use of nng_aio, nng_socket_recv, to build a client to
+
This example demonstrates the use of nng_aio, nng_socket_recv, to build a client to
 watch for messages received from the service created in Example 2.
 Error handling is elided for the sake of clarity.
#include <stdlib.h>
-- 
cgit v1.2.3-70-g09d2


OptionTypeDescription
NNG_OPT_MAXTTLintMaximum number of traversals across an nng_device device, to prevent forwarding loops. May be 1-255, inclusive. Normally defaults to 8.
NNG_OPT_RECONNMAXTnng_durationMaximum time dialers will delay before trying after failing to connect.
NNG_OPT_RECONNMINTnng_durationMinimum time dialers will delay before trying after failing to connect.
NNG_OPT_MAXTTLintMaximum number of traversals across an nng_device device, to prevent forwarding loops. May be 1-255, inclusive. Normally defaults to 8.
NNG_OPT_RECONNMAXTnng_durationMaximum time dialers will delay before trying after failing to connect.
NNG_OPT_RECONNMINTnng_durationMinimum time dialers will delay before trying after failing to connect.

 
NNG_OPT_RECVBUFintMaximum number of messages (0-8192) to buffer locally when receiving.
NNG_OPT_RECVMAXSZsize_tMaximum message size acceptable for receiving. Zero means unlimited. Intended to prevent remote abuse. Can be tuned independently on dialers and listeners.
NNG_OPT_RECVMAXSZsize_tMaximum message size acceptable for receiving. Zero means unlimited. Intended to prevent remote abuse. Can be tuned independently on dialers and listeners.

 
NNG_OPT_RECVTIMEOnng_durationDefault timeout (ms) for receiving messages.

 
NNG_OPT_SENDBUFintMaximum number of messages (0-8192) to buffer when sending messages.

 
NNG_OPT_SENDTIMEOnng_durationDefault timeout (ms) for sending messages.