From 3db63c95b3b5cc8853fa6a3a19afe34a8ba20dd2 Mon Sep 17 00:00:00 2001 From: gdamore Date: Thu, 9 Oct 2025 00:01:13 +0000 Subject: deploy: d006acfdd44af4210e39f571fa32314bcd36bb40 --- ref/api/stream.html | 67 ++++++++++++++++++++++++++++------------------------- 1 file changed, 36 insertions(+), 31 deletions(-) (limited to 'ref/api/stream.html') diff --git a/ref/api/stream.html b/ref/api/stream.html index d0403665..25ca66bc 100644 --- a/ref/api/stream.html +++ b/ref/api/stream.html @@ -267,26 +267,26 @@ using these Streams APIs.

note

The nng_stream object is used for raw byte stream connections, and -should not be confused with a pipe object created on a socket using -the nng_listen, nng_dial or related functions.

+should not be confused with a pipe object created on a socket using +the nng_listen, nng_dial or related functions.

Sending and Receiving Data

void nng_stream_send(nng_stream *s, nng_aio *aio);
 void nng_stream_recv(nng_stream *s, nng_aio *aio);

The nng_stream_send function starts sending data asynchronously over the stream s. -The data is sent from the scatter/gather vector located in the nng_aio aio, -which must have been previously set using nng_aio_set_iov.

+The data is sent from the scatter/gather vector located in the nng_aio aio, +which must have been previously set using nng_aio_set_iov.

The nng_stream_recv function starts receiving data [asynchronously over the stream s -into the scatter/gather vector located in the nng_aio aio, -which must have been previously set using nng_aio_set_iov.

+into the scatter/gather vector located in the nng_aio aio, +which must have been previously set using nng_aio_set_iov.

These functions return immediately, with no return value. Completion of the operation is signaled via the aio, and the final -result may be obtained via nng_aio_result.

+result may be obtained via nng_aio_result.

The I/O operation may complete as soon as at least one byte has been transferred, or an error has occurred. Therefore, the number of bytes transferred may be less than requested. -The actual number of bytes transferred can be determined with nng_aio_count.

+The actual number of bytes transferred can be determined with nng_aio_count.

Closing a Stream

void nng_stream_close(nng_stream *s);
 void nng_stream_stop(nng_stream *s);
@@ -294,8 +294,8 @@ void nng_stream_free(nng_stream *s);

The nng_stream_close function closes a stream, but does not destroy it. This function returns immediately. Operations that are pending against the stream, such -as nng_stream_send or nng_stream_recv operations will be canceled asynchronously, if possible. -Those operations will result in NNG_ECLOSED.

+as nng_stream_send or nng_stream_recv operations will be canceled asynchronously, if possible. +Those operations will result in NNG_ECLOSED.

The nng_stream_stop function not only closes the stream, but waits for any operations pending against it to complete, and for any underlying asynchronous registered I/O to be fully deregistered. As some systems use separate threads for asynchronous I/O, stopping the stream is necessary before those @@ -310,7 +310,7 @@ stream itself.

Because nng_stream_stop and nng_stream_free both may block waiting for outstanding I/O to complete or be aborted, these functions are unsafe to call from functions that may not block, such as the -completion function registered with an nng_aio when it is created.

+completion function registered with an nng_aio when it is created.

Getting Stream Options

nng_err nng_stream_get_bool(nng_stream *s, const char *opt, bool *valp);
@@ -338,7 +338,7 @@ typedef struct nng_stream_listener nng_stream_listener;

The nng_stream_listener object and nng_stream_listener objects can be thought of as factories that -create nng_stream streams.

+create nng_stream streams.

The nng_stream_listener object a handle to a listener, which creates streams by accepting incoming connection requests. In a BSD socket implementation, this is the entity responsible for doing bind, listen and accept. Normally a listener may be used to accept multiple, possibly many, concurrent connections.

@@ -352,10 +352,10 @@ nng_err nng_stream_listener_alloc(nng_stream_listener **lstenerp, const char *ur nng_err nng_stream_listener_alloc_url(nng_stream_listener **listenerp, const nng_url *url);

The nng_stream_dialer_alloc and nng_stream_dialer_alloc_url functions create a stream dialer, associated the -URL specified by url represented as a string, or as an nng_url object, respectively. The dialer is returned in the location +URL specified by url represented as a string, or as an nng_url object, respectively. The dialer is returned in the location dialerp references.

The nng_stream_listener_alloc and nng_stream_listener_alloc_url functions create a stream listener, associated the -URL specified by url represented as a string, or as an nng_url object, respectively. The listener is returned in the location +URL specified by url represented as a string, or as an nng_url object, respectively. The listener is returned in the location listenerp references.

Example 1: Creating a TCP Listener

This shows creating a TCP listener that listens on INADDR_ANY, port 444.

@@ -390,15 +390,15 @@ callbacks are running that could reference an object after it is deallocated.

Making Outgoing Connections 
void nng_stream_dialer_dial(nng_stream_dialer *dialer, nng_aio *aio);
-

The nng_stream_dialer_dial initiates an outgoing connection asynchronously, using the nng_aio aio. -If it successfully establishes a connection, it creates an nng_stream, which can be obtained as the first -output result on aio using the nng_aio_get_output function with index zero.

+

The nng_stream_dialer_dial initiates an outgoing connection asynchronously, using the nng_aio aio. +If it successfully establishes a connection, it creates an nng_stream, which can be obtained as the first +output result on aio using the nng_aio_get_output function with index zero.

tip

-

An nng_stream_dialer can be used multiple times to make multiple concurrent connection requests, but +

An nng_stream_dialer can be used multiple times to make multiple concurrent connection requests, but they all must reference the same URL.

Example 3: Connecting to Google

@@ -426,12 +426,12 @@ void nng_stream_listener_accept(nng_stream_listener *listener, nng_aio *aio);

Accepting incoming connections is performed in two steps. The first step, nng_stream_listener_listen is to setup for listening. For a TCP implementation of this, for example, this would perform the bind and the listen steps. This will bind -to the address represented by the URL that was specific when the listener was created with nng_stream_listener_alloc.

-

In the second step, nng_stream_listener_accept accepts an incoming connection on listener asynchronously, using the nng_aio aio. -If an incoming connection is accepted, it will be represented as an nng_stream, which can be obtained from the aio as the first -output result using the nng_aio_get_output function with index zero.

+to the address represented by the URL that was specific when the listener was created with nng_stream_listener_alloc.

+

In the second step, nng_stream_listener_accept accepts an incoming connection on listener asynchronously, using the nng_aio aio. +If an incoming connection is accepted, it will be represented as an nng_stream, which can be obtained from the aio as the first +output result using the nng_aio_get_output function with index zero.

Example 3: Accepting an Inbound Stream

-

For clarity this example uses a synchronous approach using nng_aio_wait, but a typical server application +

For clarity this example uses a synchronous approach using nng_aio_wait, but a typical server application would most likely use a callback to accept the incoming stream, and start another instance of nng_stream_listener_accept.

nng_aio *aio;
 nng_listener *listener;
@@ -518,10 +518,10 @@ need not retain the value referenced once the function returns.

 
In the case of nng_stream_dialer_set_addr and nng_stream_listener_set_addr, the contents of addr are copied if necessary, so that the caller
 need not retain the value referenced once the function returns.

 
Example 4: Socket Activation

-
Some nng_stream_listener objects, depending on the underlying transport and platform, can support a technique known as “socket activation”,
+
Some nng_stream_listener objects, depending on the underlying transport and platform, can support a technique known as “socket activation”,
 where the file descriptor used for listening and accepting is supplied externally, such as by a system service manager.
 In this case, the application supplies the file descriptor or SOCKET object using the NNG_OPT_LISTEN_FD option,
-instead of calling nng_stream_listener_listen.

+instead of calling nng_stream_listener_listen.

 

 

   
@@ -548,25 +548,30 @@ nng_err nng_stream_dialer_set_tls(nng_stream_listener *dialer, nng_tls_config *t
 nng_err nng_stream_listener_get_tls(nng_stream_listener *listener, nng_tls_config **tlsp);
 nng_err nng_stream_listener_set_tls(nng_stream_listener *listener, nng_tls_config *tls);
-

Both nng_stream_dialer and nng_stream_listener objects may support configuration of TLS parameters. +

Both nng_stream_dialer and nng_stream_listener objects may support configuration of TLS parameters. The nng_stream_dialer_set_tls and nng_stream_listener_set_tls functions support setting the -configuration of a nng_tls_config object supplied by tls on dialer or listener. -This must be performed before the listener starts listening with nng_stream_listener_listen, or the dialer starts an outgoing connection -as a result of nng_stream_dialer_dial.

+configuration of a nng_tls_config object supplied by tls on dialer or listener. +This must be performed before the listener starts listening with nng_stream_listener_listen, or the dialer starts an outgoing connection +as a result of nng_stream_dialer_dial.

The configuration object that was previously established (which may be a default if one was not explicitly configured) can be obtained with the nng_stream_dialer_get_tls and nng_stream_listener_get_tls. -They will return a pointer to the nng_tls_config object in question at the location referenced by tlsp.

+They will return a pointer to the nng_tls_config object in question at the location referenced by tlsp.

note

TLS configuration cannot be changed once it has started being used by a listener or dialer. This applies to -both configuring a different TLS configuration object, as well as mutating the existing nng_tls_config object.

+both configuring a different TLS configuration object, as well as mutating the existing nng_tls_config object.

+ + -- cgit v1.2.3-70-g09d2