ASYNC_WAIT_CTX_new

- NAME
- SYNOPSIS
- DESCRIPTION
- RETURN VALUES
- NOTES
- SEE ALSO
- HISTORY
- COPYRIGHT

# 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

# 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);

# DESCRIPTION

For an overview of how asynchronous operations are implemented in OpenSSL see 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 ctx parameter will return the wait file descriptors associated with that job in *fd. The number of file descriptors returned will be stored in *numfds. It is the caller's responsibility to ensure that sufficient memory has been allocated in *fd to receive all the file descriptors. Calling ASYNC_WAIT_CTX_get_all_fds() with a NULL fd value will return no file descriptors but will still populate *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 numaddfds and numdelfds parameters will be populated with the number of fds added or deleted respectively. *addfd and *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 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.

# 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.

# SEE ALSO

ASYNC_start_job(3)

# 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.

# 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 https://www.openssl.org/source/license.html.