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/aio.html | 70 ++++++++++++++--------------- ref/api/args.html | 2 +- ref/api/ctx.html | 64 +++++++++++++-------------- ref/api/errors.html | 10 ++--- ref/api/http.html | 120 +++++++++++++++++++++++++------------------------- ref/api/id_map.html | 14 +++--- ref/api/init.html | 6 +-- ref/api/memory.html | 16 +++---- ref/api/misc.html | 2 +- ref/api/msg.html | 20 ++++----- ref/api/pipe.html | 18 ++++---- ref/api/sock.html | 124 ++++++++++++++++++++++++++-------------------------- ref/api/stats.html | 36 +++++++-------- ref/api/stream.html | 62 +++++++++++++------------- ref/api/synch.html | 30 ++++++------- ref/api/thread.html | 8 ++-- ref/api/time.html | 12 ++--- ref/api/url.html | 8 ++-- 18 files changed, 311 insertions(+), 311 deletions(-) (limited to 'ref/api') diff --git a/ref/api/aio.html b/ref/api/aio.html index e171e0d4..796c6a51 100644 --- a/ref/api/aio.html +++ b/ref/api/aio.html @@ -247,7 +247,7 @@

In order to obtain significant scalability, with low-latency, and minimal overheads, NNG supports performing operations asynchronously.

One way that applications can perform work asynchronously and concurrently -is by using threads, but threads carry significant resource overheads +is by using threads, but threads carry significant resource overheads and frequently there are limits on the number that can easily be created.

Additionally, with most network applications, the flow of execution will spend the bulk of its time waiting for traffic from a peer.

@@ -272,17 +272,17 @@ can only be used with a single operation at a time.

Instead the application registers a callback function to be executed when the operation is complete (whether successfully or not). This callback will be executed exactly once.

-

The asynchronous I/O framework also supports cancellation of +

The asynchronous I/O framework also supports cancellation of operations that are already in progress as well setting a maximum -timeout for them to complete.

-

It is also possible to initiate an asynchronous operation, and wait for it to +timeout for them to complete.

+

It is also possible to initiate an asynchronous operation, and wait for it to complete, creating a synchronous flow from an asynchronous one.

Create Handle

nng_err nng_aio_alloc(nng_aio **aiop, void (*callb)(void *), void *arg);
-

The nng_aio_alloc function creates an nng_aio object, with the +

The nng_aio_alloc function creates an nng_aio object, with the callback callb taking the argument arg, and returns it in aiop.

-

If this succeeds, the function returns zero. Otherwise it may return NNG_ENOMEM.

+

If this succeeds, the function returns zero. Otherwise it may return NNG_ENOMEM.

@@ -290,15 +290,15 @@ complete, creating a synchronous flow from an asynchronous one.

The arg should normally be a structure that contains a pointer to the aiop, or from which it can be located. This allows callb to check the handle for -success using nng_aio_result, as well access other properties of aiop.

+success using nng_aio_result, as well access other properties of aiop.

tip

-

The callb may be executed on another thread, so it may be necessary to use -synchronization methods in callb to avoid data races.

+

The callb may be executed on another thread, so it may be necessary to use +synchronization methods in callb to avoid data races.

Destroy Handle

void nng_aio_free(nng_aio *aio);
@@ -307,7 +307,7 @@ void nng_aio_reap(nng_aio *aio);
 
The nng_aio_free handle destroys the handle aio, waiting for any operations
 and associated callbacks to complete before doing so.

 
The nng_aio_reap handle destroys the handle aio asynchronously, using a reaper
-thread to do so. It does not wait for the object to be destroyed. Thus this function
+thread to do so. It does not wait for the object to be destroyed. Thus this function
 is safe to call from aio’s own callback.

 

 

@@ -330,13 +330,13 @@ If the operation is successfully canceled or aborted, then the callback
 will still be called.

 
The nng_aio_abort function aborts the operation associated with aio
 and returns immediately without waiting. If cancellation was successful,
-then nng_aio_result will return err.

+then nng_aio_result will return err.

 
The nng_aio_cancel function acts like nng_aio_abort, but uses the error code
-NNG_ECANCELED.

-
The nng_aio_stop function aborts the aio operation with NNG_ESTOPPED,
+NNG_ECANCELED.

+
The nng_aio_stop function aborts the aio operation with NNG_ESTOPPED,
 and then waits the operation and any associated callback to complete.
 This function also marks aio itself permanently stopped, so that any
-new operations scheduled by I/O providers using nng_aio_start
+new operations scheduled by I/O providers using nng_aio_start
 return false. Thus this function should be used to teardown operations.

 

 

@@ -345,7 +345,7 @@ return false. Thus this function should be used to teardown operations.

 

 
When multiple asynchronous I/O handles are in use and need to be
 deallocated, it is safest to stop all of them using nng_aio_stop,
-before deallocating any of them with nng_aio_free,
+before deallocating any of them with nng_aio_free,
 particularly if the callbacks might attempt to reschedule further operations.

 

 
Set Timeout

@@ -356,15 +356,15 @@ void nng_aio_set_expire(nng_aio *aio, nng_time expiration);
 for the asynchronous operation associated with aio.
 This causes a timer to be started when the operation is actually started.
 If the timer expires before the operation is completed, then it is
-aborted with an error of NNG_ETIMEDOUT.
-The timeout duration is specified as a relative number of milliseconds.

-
If the timeout is NNG_DURATION_INFINITE, then no timeout is used.
-If the timeout is NNG_DURATION_DEFAULT, then a “default” or socket-specific
+aborted with an error of NNG_ETIMEDOUT.
+The timeout duration is specified as a relative number of milliseconds.

+
If the timeout is NNG_DURATION_INFINITE, then no timeout is used.
+If the timeout is NNG_DURATION_DEFAULT, then a “default” or socket-specific
 timeout is used.
-(This is frequently the same as NNG_DURATION_INFINITE.)

+(This is frequently the same as NNG_DURATION_INFINITE.)

 
The nng_aio_set_expire function is similar to nng_aio_set_timeout, but sets
 an expiration time based on the system clock. The expiration
-time is a clock timestamp, such as would be returned by nng_clock.

+time is a clock timestamp, such as would be returned by nng_clock.

 
Wait for Completion

 
void nng_aio_wait(nng_aio *aio);
 

@@ -378,7 +378,7 @@ function will not be called until the callback has completed.

   important
 

 
The nng_aio_wait function should never be called from a function that itself
-is a callback of an nng_aio, either this one or any other.
+is a callback of an nng_aio, either this one or any other.
 Doing so may result in a deadlock.

 

 
Test for Completion

@@ -386,7 +386,7 @@ Doing so may result in a deadlock.

The nng_aio_busy function returns true if the aio is currently busy performing an operation or is executing a completion callback. Otherwise it return false. -This is the same test used internally by nng_aio_wait.

+This is the same test used internally by nng_aio_wait.

@@ -402,7 +402,7 @@ size_t nng_aio_count(nng_aio *aio);

The nng_aio_result function returns the result of the operation associated with the handle aio. If the operation was successful, then 0 is returned. -Otherwise a non-zero error code, such as NNG_ECANCELED or NNG_ETIMEDOUT, is returned.

+Otherwise a non-zero error code, such as NNG_ECANCELED or NNG_ETIMEDOUT, is returned.

For operations that transfer data, nng_aio_count returns the number of bytes transferred by the operation associated with the handle aio. Operations that do not transfer data, or do not keep a count, may return zero for this function.

@@ -413,13 +413,13 @@ Operations that do not transfer data, or do not keep a count, may return zero fo

The return value from these functions is undefined if the operation has not completed yet. Either call these from the handle’s completion callback, or after waiting for the -operation to complete with nng_aio_wait.

+operation to complete with nng_aio_wait.

Messages

nng_msg *nng_aio_get_msg(nng_aio *aio);
 void nng_aio_set_msg(nng_aio *aio, nng_msg *msg);
-

The nng_aio_get_msg and nng_aio_set_msg functions retrieve and store a message +

The nng_aio_get_msg and nng_aio_set_msg functions retrieve and store a message in aio. For example, if a function to receive data is called, that function can generally be expected to store a message on the associated aio, for the application to retrieve with @@ -445,7 +445,7 @@ then no message is stored on the aio.

int nng_aio_set_iov(nng_aio *aio, unsigned int niov, nng_iov *iov); -

For some operations, the unit of data transferred is not a message, but +

For some operations, the unit of data transferred is not a message, but rather a stream of bytes.

For these operations, an array of niov nng_iov structures can be passed to the nng_aio_set_iov function to provide a scatter/gather array of @@ -462,14 +462,14 @@ The values pointed to by the iov_buf members are not copie

Most functions using nng_iov do not guarantee to transfer all of the data that they are requested to. To be sure that correct amount of data is transferred, as well as to start an attempt to complete any partial transfer, check the amount of data transferred by -calling nng_aio_count.

+calling nng_aio_count.

Inputs and Outputs

void nng_aio_set_input(nng_aio *aio, unsigned int index, void *param);
 void *nng_aio_get_output(nng_aio *aio, unsigned int index);

Asynchronous operations can take additional input parameters, and -provide additional result outputs besides the result code.

+provide additional result outputs besides the result code.

The nng_aio_set_input function sets the input parameter at index to param for the operation associated with aio.

The nng_aio_get_output function returns the output result at index @@ -505,7 +505,7 @@ in use by an active asynchronous operation.

void nng_aio_set_iov(nng_aio *aio, unsigned nio, const nng_iov *iov);

-Some asynchronous operations, such as those dealing with streams, use scatter or gather +Some asynchronous operations, such as those dealing with streams, use scatter or gather vectors, where data to be transferred is either gathered from multiple separate regions of memory, or scattered into separate regions of memory. For example a message may have a header located at one location in memory, and a payload located in another.

@@ -515,13 +515,13 @@ the elements in iov. For each of these, the segment of size iov_len on the stack or another temporary location. The locations referenced by it, must remain valid for the duration of the operation, of course.

Note that many of these operations are not guaranteed to perform a full transfer of data, so even a -successful operation should check the amount of data actually transferred using nng_aio_count, +successful operation should check the amount of data actually transferred using nng_aio_count, and if necessary resubmit the operation with a suitably updated vector of nng_iov using this function.

See Also

-

Synchronization, -Threads, -Streams, -Time

+

Synchronization, +Threads, +Streams, +Time