From c635d5615add1db2eea17c9ae0b67e6671462cbd Mon Sep 17 00:00:00 2001 From: gdamore Date: Sat, 11 Oct 2025 13:20:16 +0000 Subject: deploy: b98e03b26bfc593326bd7c1d56fd69626f6a93cb --- ref/print.html | 116 +++++++++++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 108 insertions(+), 8 deletions(-) (limited to 'ref/print.html') diff --git a/ref/print.html b/ref/print.html index 92648422..042e72c4 100644 --- a/ref/print.html +++ b/ref/print.html @@ -2815,7 +2815,7 @@ then nng_aio_resultThe 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.

@@ -2944,17 +2944,29 @@ start an attempt to complete any partial transfer, check the amount of data tran calling nng_aio_count.

Inputs and Outputs

-
void nng_aio_set_input(nng_aio *aio, unsigned int index, void *param);
+
void *nng_aio_get_input(nng_aio *aio, unsigned int index);
 void *nng_aio_get_output(nng_aio *aio, unsigned int index);
+void nng_aio_set_input(nng_aio *aio, unsigned int index, void *param);
+void nng_aio_set_output(nng_aio *aio, unsigned int index, void *result);
 

 
Asynchronous operations can take additional input parameters, and
 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
-for the operation associated with aio.

+
The nng_aio_set_output function sets the output result at index
+to result for the operation associated with aio.

+
The nng_aio_get_output function returns the output result previously set by nng_aio_set_output.

+
The nng_aio_get_input function returns the input parameter previously set by nng_aio_set_input.

 
The type and semantics of input parameters and output results are determined by specific
 operations. The documentation for the operation should provide details.

+

+

+  
+  tip
+

+
Most applications will not need to use nng_aio_get_input or nng_aio_set_output, as those
+are used by I/O Providers.

+

 
The valid values of index range from zero (0) to three (3), as no operation
 currently defined can accept more than four parameters or return more than four additional
 results.

@@ -2996,6 +3008,91 @@ 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,
 and if necessary resubmit the operation with a suitably updated vector of nng_iov using this function.

+
I/O Providers

+
This section documents functions that are used by I/O providers, and will not be relevant
+for the majority of applications that simply utilize operations provided for by the library.

+
However, these functions will be useful if an application wants to implement its own asynchronous operations using nng_aio.

+
Starting an Operation

+
typedef void (*nng_aio_cancelfn)(nng_aio *aio, void *arg, nng_err err);
+
+void nng_aio_reset(nng_aio *aio);
+bool nng_aio_start(nng_aio *aio, nng_aio_cancelfn fn, void *arg);
+

+
The nng_aio_reset function resets various fields in the aio.
+It can be called before starting an operation.

+
The nng_aio_start function starts the operation associated with aio.
+It implies the same reset as nng_aio_reset. Thus, nng_aio_reset is typically
+only useful when used with operations that complete synchronously.
+The nng_aio_start function also registers the cancellation function fn and
+associated argument arg with the operation. This allows the operation to be canceled.

+

+

+  
+  important
+

+
This function must not be called on an aio that is already has an operation in progress.

+

+
If fn is NULL, then the operation cannot be canceled.

+
If nng_aio_start returns false, then the aio has been permanently stopped
+and the operation cannot proceed. In this case the caller should cease all
+work with aio, and must not call nng_aio_finish or any other function,
+as the aio is no longer valid for use.

+
If nng_aio_start returns true, then the operation may proceed.

+

+

+  
+  important
+

+
Failure to check the return value from nng_aio_start can lead to deadlocks
+or infinite loops.

+

+
If the aio is subsequently canceled, the cancellation routine fn will be called
+with aio and arg and an error value in err.
+The err indicates the reason that the operation is being canceled.

+
If the operation cannot be canceled, fn should just return without making any change.

+
If fn successfully canceled the operation, it should
+ensure that nng_aio_finish is called with the error code specified by err.

+

+

+  
+  important
+

+
It is mandatory that I/O providers call nng_aio_finish
+exactly once when they are finished with the operation.

+

+

+

+  
+  tip
+

+
Ensure that cancellation and completion of the routine are thread safe.
+This usually involves the use of locks or other synchronization primitives.

+

+
Finishing an Operation

+
void nng_aio_finish(nng_aio *aio, nng_err err);
+

+
The nng_aio_finish function completes the operation associated with aio.
+The result of the the status err.

+
This function causes the callback associated with the aio to called.
+The aio may not be referenced again by the caller.

+

+

+  
+  tip
+

+
Set any results using nng_aio_set_output before calling this function.

+

+
The return value subsequently obtained from nng_aio_result for aio will be err.

+

+

+  
+  important
+

+
It is mandatory that operation providers call this function
+exactly once when they are finished with the operation.
+After calling this function they must not perform any further accesses
+to the aio.

+

 
See Also

 
Synchronization,
 Threads,
@@ -5018,11 +5115,11 @@ the response body may be set using either nng_http_handler_collect_body function has been called for the handler.

 
 
The HTTP status should be set for the transaction using nng_http_set_status.

-
Finally, the handler should finish the operation by calling the nng_aio_finish function
+
Finally, the handler should finish the operation by calling the nng_aio_finish function
 after having set the status to NNG_OK.
 If any other status is set on the aio, then a generic 500 response will be created and
 sent, if possible, and the connection will be closed.

-
The aio may be scheduled for deferred completion using the nng_aio_start.

+
The aio may be scheduled for deferred completion using the nng_aio_start.

 
Serving Directories and Files

 
nng_err nng_http_handler_alloc_directory(nng_http_handler **hp, const char *path, const char *dirname);
 nng_err nng_http_handler_alloc_file(nng_http_handler **hp, const char *path, const char *filename);
@@ -8196,9 +8293,9 @@ as any further operations on the object will fail immediately with NNG_EST
 
AIO Provider API changes

 
The API used for providers for asynchronous I/O operations has changed slightly.

 
    
-
  • The nng_aio_begin function is removed. However a new nng_aio_reset function should be called
+
  • The nng_aio_begin function is removed. However a new nng_aio_reset function should be called
 instead, before performing any other operations on an aio object. (This simply clears certain fields.)
    • 
-
  • The nng_aio_defer function is replaced, with a very nng_aio_start function. However, this function
+
  • The nng_aio_defer function is replaced, with a very nng_aio_start function. However, this function
 has slightly different semantics. It will automatically call the callback if the operation cannot be
 scheduled.
    • 
 
  • Be aware of the new NNG_ESTOPPED error code, for operations on a handle that is being torn down by
@@ -8699,13 +8796,16 @@ named pipes, 1
    
 nng_aio_busy, 1
    
 nng_aio_cancel, 1
    
 nng_aio_count, 1
    
+nng_aio_finish, 1
    
 nng_aio_free, 1
    
 nng_aio_get_msg, 1
    
 nng_aio_reap, 1
    
+nng_aio_reset, 1
    
 nng_aio_result, 1
    
 nng_aio_set_expire, 1
    
 nng_aio_set_iov, 1, 2
    
 nng_aio_set_msg, 1
    
+nng_aio_start, 1
    
 nng_aio_stop, 1
    
 nng_aio_wait, 1
    
 nng_alloc, 1
    
-- 
cgit v1.2.3-70-g09d2