diff options
Diffstat (limited to 'doc/man3/ASYNC_WAIT_CTX_new.pod')
| -rw-r--r-- | doc/man3/ASYNC_WAIT_CTX_new.pod | 144 |
1 files changed, 144 insertions, 0 deletions
diff --git a/doc/man3/ASYNC_WAIT_CTX_new.pod b/doc/man3/ASYNC_WAIT_CTX_new.pod new file mode 100644 index 000000000000..204280210e04 --- /dev/null +++ b/doc/man3/ASYNC_WAIT_CTX_new.pod @@ -0,0 +1,144 @@ +=pod + +=head1 NAME + +ASYNC_WAIT_CTX_new, ASYNC_WAIT_CTX_free, ASYNC_WAIT_CTX_set_wait_fd, +ASYNC_WAIT_CTX_get_fd, ASYNC_WAIT_CTX_get_all_fds, +ASYNC_WAIT_CTX_get_changed_fds, ASYNC_WAIT_CTX_clear_fd - functions to manage +waiting for asynchronous jobs to complete + +=head1 SYNOPSIS + + #include <openssl/async.h> + + ASYNC_WAIT_CTX *ASYNC_WAIT_CTX_new(void); + void ASYNC_WAIT_CTX_free(ASYNC_WAIT_CTX *ctx); + int ASYNC_WAIT_CTX_set_wait_fd(ASYNC_WAIT_CTX *ctx, const void *key, + OSSL_ASYNC_FD fd, + void *custom_data, + void (*cleanup)(ASYNC_WAIT_CTX *, const void *, + OSSL_ASYNC_FD, void *)); + int ASYNC_WAIT_CTX_get_fd(ASYNC_WAIT_CTX *ctx, const void *key, + OSSL_ASYNC_FD *fd, void **custom_data); + int ASYNC_WAIT_CTX_get_all_fds(ASYNC_WAIT_CTX *ctx, OSSL_ASYNC_FD *fd, + size_t *numfds); + int ASYNC_WAIT_CTX_get_changed_fds(ASYNC_WAIT_CTX *ctx, OSSL_ASYNC_FD *addfd, + size_t *numaddfds, OSSL_ASYNC_FD *delfd, + size_t *numdelfds); + int ASYNC_WAIT_CTX_clear_fd(ASYNC_WAIT_CTX *ctx, const void *key); + + +=head1 DESCRIPTION + +For an overview of how asynchronous operations are implemented in OpenSSL see +L<ASYNC_start_job(3)>. An ASYNC_WAIT_CTX object represents an asynchronous +"session", i.e. a related set of crypto operations. For example in SSL terms +this would have a one-to-one correspondence with an SSL connection. + +Application code must create an ASYNC_WAIT_CTX using the ASYNC_WAIT_CTX_new() +function prior to calling ASYNC_start_job() (see L<ASYNC_start_job(3)>). When +the job is started it is associated with the ASYNC_WAIT_CTX for the duration of +that job. An ASYNC_WAIT_CTX should only be used for one ASYNC_JOB at any one +time, but can be reused after an ASYNC_JOB has finished for a subsequent +ASYNC_JOB. When the session is complete (e.g. the SSL connection is closed), +application code cleans up with ASYNC_WAIT_CTX_free(). + +ASYNC_WAIT_CTXs can have "wait" file descriptors associated with them. Calling +ASYNC_WAIT_CTX_get_all_fds() and passing in a pointer to an ASYNC_WAIT_CTX in +the B<ctx> parameter will return the wait file descriptors associated with that +job in B<*fd>. The number of file descriptors returned will be stored in +B<*numfds>. It is the caller's responsibility to ensure that sufficient memory +has been allocated in B<*fd> to receive all the file descriptors. Calling +ASYNC_WAIT_CTX_get_all_fds() with a NULL B<fd> value will return no file +descriptors but will still populate B<*numfds>. Therefore application code is +typically expected to call this function twice: once to get the number of fds, +and then again when sufficient memory has been allocated. If only one +asynchronous engine is being used then normally this call will only ever return +one fd. If multiple asynchronous engines are being used then more could be +returned. + +The function ASYNC_WAIT_CTX_get_changed_fds() can be used to detect if any fds +have changed since the last call time ASYNC_start_job() returned an ASYNC_PAUSE +result (or since the ASYNC_WAIT_CTX was created if no ASYNC_PAUSE result has +been received). The B<numaddfds> and B<numdelfds> parameters will be populated +with the number of fds added or deleted respectively. B<*addfd> and B<*delfd> +will be populated with the list of added and deleted fds respectively. Similarly +to ASYNC_WAIT_CTX_get_all_fds() either of these can be NULL, but if they are not +NULL then the caller is responsible for ensuring sufficient memory is allocated. + +Implementors of async aware code (e.g. engines) are encouraged to return a +stable fd for the lifetime of the ASYNC_WAIT_CTX in order to reduce the "churn" +of regularly changing fds - although no guarantees of this are provided to +applications. + +Applications can wait for the file descriptor to be ready for "read" using a +system function call such as select or poll (being ready for "read" indicates +that the job should be resumed). If no file descriptor is made available then an +application will have to periodically "poll" the job by attempting to restart it +to see if it is ready to continue. + +Async aware code (e.g. engines) can get the current ASYNC_WAIT_CTX from the job +via L<ASYNC_get_wait_ctx(3)> and provide a file descriptor to use for waiting +on by calling ASYNC_WAIT_CTX_set_wait_fd(). Typically this would be done by an +engine immediately prior to calling ASYNC_pause_job() and not by end user code. +An existing association with a file descriptor can be obtained using +ASYNC_WAIT_CTX_get_fd() and cleared using ASYNC_WAIT_CTX_clear_fd(). Both of +these functions requires a B<key> value which is unique to the async aware +code. This could be any unique value but a good candidate might be the +B<ENGINE *> for the engine. The B<custom_data> parameter can be any value, and +will be returned in a subsequent call to ASYNC_WAIT_CTX_get_fd(). The +ASYNC_WAIT_CTX_set_wait_fd() function also expects a pointer to a "cleanup" +routine. This can be NULL but if provided will automatically get called when +the ASYNC_WAIT_CTX is freed, and gives the engine the opportunity to close the +fd or any other resources. Note: The "cleanup" routine does not get called if +the fd is cleared directly via a call to ASYNC_WAIT_CTX_clear_fd(). + +An example of typical usage might be an async capable engine. User code would +initiate cryptographic operations. The engine would initiate those operations +asynchronously and then call ASYNC_WAIT_CTX_set_wait_fd() followed by +ASYNC_pause_job() to return control to the user code. The user code can then +perform other tasks or wait for the job to be ready by calling "select" or other +similar function on the wait file descriptor. The engine can signal to the user +code that the job should be resumed by making the wait file descriptor +"readable". Once resumed the engine should clear the wake signal on the wait +file descriptor. + +=head1 RETURN VALUES + +ASYNC_WAIT_CTX_new() returns a pointer to the newly allocated ASYNC_WAIT_CTX or +NULL on error. + +ASYNC_WAIT_CTX_set_wait_fd, ASYNC_WAIT_CTX_get_fd, ASYNC_WAIT_CTX_get_all_fds, +ASYNC_WAIT_CTX_get_changed_fds and ASYNC_WAIT_CTX_clear_fd all return 1 on +success or 0 on error. + +=head1 NOTES + +On Windows platforms the openssl/async.h header is dependent on some +of the types customarily made available by including windows.h. The +application developer is likely to require control over when the latter +is included, commonly as one of the first included headers. Therefore +it is defined as an application developer's responsibility to include +windows.h prior to async.h. + +=head1 SEE ALSO + +L<crypto(7)>, L<ASYNC_start_job(3)> + +=head1 HISTORY + +ASYNC_WAIT_CTX_new, ASYNC_WAIT_CTX_free, ASYNC_WAIT_CTX_set_wait_fd, +ASYNC_WAIT_CTX_get_fd, ASYNC_WAIT_CTX_get_all_fds, +ASYNC_WAIT_CTX_get_changed_fds, ASYNC_WAIT_CTX_clear_fd were first added to +OpenSSL 1.1.0. + +=head1 COPYRIGHT + +Copyright 2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut |