doc/crypto/ASYNC_WAIT_CTX_new.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 ASYNC_WAIT_CTX_new, ASYNC_WAIT_CTX_free, ASYNC_WAIT_CTX_set_wait_fd,
   6 ASYNC_WAIT_CTX_get_fd, ASYNC_WAIT_CTX_get_all_fds,
   7 ASYNC_WAIT_CTX_get_changed_fds, ASYNC_WAIT_CTX_clear_fd - functions to manage
   8 waiting for asynchronous jobs to complete
   9
  10 =head1 SYNOPSIS
  11
  12  #include <openssl/async.h>
  13
  14  ASYNC_WAIT_CTX *ASYNC_WAIT_CTX_new(void);
  15  void ASYNC_WAIT_CTX_free(ASYNC_WAIT_CTX *ctx);
  16  int ASYNC_WAIT_CTX_set_wait_fd(ASYNC_WAIT_CTX *ctx, const void *key,
  17                                 OSSL_ASYNC_FD fd,
  18                                 void *custom_data,
  19                                 void (*cleanup)(ASYNC_WAIT_CTX *, const void *,
  20                                                OSSL_ASYNC_FD, void *));
  21  int ASYNC_WAIT_CTX_get_fd(ASYNC_WAIT_CTX *ctx, const void *key,
  22                            OSSL_ASYNC_FD *fd, void **custom_data);
  23  int ASYNC_WAIT_CTX_get_all_fds(ASYNC_WAIT_CTX *ctx, OSSL_ASYNC_FD *fd,
  24                                 size_t *numfds);
  25  int ASYNC_WAIT_CTX_get_changed_fds(ASYNC_WAIT_CTX *ctx, OSSL_ASYNC_FD *addfd,
  26                                     size_t *numaddfds, OSSL_ASYNC_FD *delfd,
  27                                     size_t *numdelfds);
  28  int ASYNC_WAIT_CTX_clear_fd(ASYNC_WAIT_CTX *ctx, const void *key);
  29
  30
  31 =head1 DESCRIPTION
  32
  33 For an overview of how asynchronous operations are implemented in OpenSSL see
  34 L<ASYNC_start_job(3)>. An ASYNC_WAIT_CTX object represents an asynchronous
  35 "session", i.e. a related set of crypto operations. For example in SSL terms
  36 this would have a one-to-one correspondence with an SSL connection.
  37
  38 Application code must create an ASYNC_WAIT_CTX using the ASYNC_WAIT_CTX_new()
  39 function prior to calling ASYNC_start_job() (see L<ASYNC_start_job(3)>). When
  40 the job is started it is associated with the ASYNC_WAIT_CTX for the duration of
  41 that job. An ASYNC_WAIT_CTX should only be used for one ASYNC_JOB at any one
  42 time, but can be reused after an ASYNC_JOB has finished for a subsequent
  43 ASYNC_JOB. When the session is complete (e.g. the SSL connection is closed),
  44 application code cleans up with ASYNC_WAIT_CTX_free().
  45
  46 ASYNC_WAIT_CTXs can have "wait" file descriptors associated with them. Calling
  47 ASYNC_WAIT_CTX_get_all_fds() and passing in a pointer to an ASYNC_WAIT_CTX in
  48 the B<ctx> parameter will return the wait file descriptors associated with that
  49 job in B<*fd>. The number of file descriptors returned will be stored in
  50 B<*numfds>. It is the caller's responsibility to ensure that sufficient memory
  51 has been allocated in B<*fd> to receive all the file descriptors. Calling
  52 ASYNC_WAIT_CTX_get_all_fds() with a NULL B<fd> value will return no file
  53 descriptors but will still populate B<*numfds>. Therefore application code is
  54 typically expected to call this function twice: once to get the number of fds,
  55 and then again when sufficient memory has been allocated. If only one
  56 asynchronous engine is being used then normally this call will only ever return
  57 one fd. If multiple asynchronous engines are being used then more could be
  58 returned.
  59
  60 The function ASYNC_WAIT_CTX_fds_have_changed() can be used to detect if any fds
  61 have changed since the last call time ASYNC_start_job() returned an ASYNC_PAUSE
  62 result (or since the ASYNC_WAIT_CTX was created if no ASYNC_PAUSE result has
  63 been received). The B<numaddfds> and B<numdelfds> parameters will be populated
  64 with the number of fds added or deleted respectively. B<*addfd> and B<*delfd>
  65 will be populated with the list of added and deleted fds respectively. Similarly
  66 to ASYNC_WAIT_CTX_get_all_fds() either of these can be NULL, but if they are not
  67 NULL then the caller is responsible for ensuring sufficient memory is allocated.
  68
  69 Implementors of async aware code (e.g. engines) are encouraged to return a
  70 stable fd for the lifetime of the ASYNC_WAIT_CTX in order to reduce the "churn"
  71 of regularly changing fds - although no guarantees of this are provided to
  72 applications.
  73
  74 Applications can wait for the file descriptor to be ready for "read" using a
  75 system function call such as select or poll (being ready for "read" indicates
  76 that the job should be resumed). If no file descriptor is made available then an
  77 application will have to periodically "poll" the job by attempting to restart it
  78 to see if it is ready to continue.
  79
  80 Async aware code (e.g. engines) can get the current ASYNC_WAIT_CTX from the job
  81 via L<ASYNC_get_async_wait_ctx(3)> and provide a file descriptor to use for
  82 waiting on by calling ASYNC_WAIT_CTX_set_wait_fd(). Typically this would be done
  83 by an engine immediately prior to calling ASYNC_pause_job() and not by end user
  84 code. An existing association with a file descriptor can be obtained using
  85 ASYNC_WAIT_CTX_get_fd() and cleared using ASYNC_WAIT_CTX_clear_fd(). Both of
  86 these functions requires a B<key> value which is unique to the async aware code.
  87 This could be any unique value but a good candidate might be the B<ENGINE *> for
  88 the engine. The B<custom_data> parameter can be any value, and will be returned
  89 in a subsequent call to ASYNC_WAIT_CTX_get_fd(). The
  90 ASYNC_WAIT_CTX_set_wait_fd() function also expects a pointer to a "cleanup"
  91 routine. This can be NULL but if provided will automatically get called when the
  92 ASYNC_WAIT_CTX is freed, and gives the engine the opportunity to close the fd or
  93 any other resources. Note: The "cleanup" routine does not get called if the fd
  94 is cleared directly via a call to ASYNC_WAIT_CTX_clear_fd().
  95
  96 An example of typical usage might be an async capable engine. User code would
  97 initiate cryptographic operations. The engine would initiate those operations
  98 asynchronously and then call ASYNC_WAIT_CTX_set_wait_fd() followed by
  99 ASYNC_pause_job() to return control to the user code. The user code can then
 100 perform other tasks or wait for the job to be ready by calling "select" or other
 101 similar function on the wait file descriptor. The engine can signal to the user
 102 code that the job should be resumed by making the wait file descriptor
 103 "readable". Once resumed the engine should clear the wake signal on the wait
 104 file descriptor.
 105
 106 =head1 RETURN VALUES
 107
 108 ASYNC_WAIT_CTX_new() returns a pointer to the newly allocated ASYNC_WAIT_CTX or
 109 NULL on error.
 110
 111 ASYNC_WAIT_CTX_set_wait_fd, ASYNC_WAIT_CTX_get_fd, ASYNC_WAIT_CTX_get_all_fds,
 112 ASYNC_WAIT_CTX_get_changed_fds and ASYNC_WAIT_CTX_clear_fd all return 1 on
 113 success or 0 on error.
 114
 115 =head1 NOTES
 116
 117 On Windows platforms the openssl/async.h header is dependent on some
 118 of the types customarily made available by including windows.h. The
 119 application developer is likely to require control over when the latter
 120 is included, commonly as one of the first included headers. Therefore
 121 it is defined as an application developer's responsibility to include
 122 windows.h prior to async.h.
 123
 124 =head1 SEE ALSO
 125
 126 L<crypto(3)>, L<ASYNC_start_job(3)>
 127
 128 =head1 HISTORY
 129
 130 ASYNC_WAIT_CTX_new, ASYNC_WAIT_CTX_free, ASYNC_WAIT_CTX_set_wait_fd,
 131 ASYNC_WAIT_CTX_get_fd, ASYNC_WAIT_CTX_get_all_fds,
 132 ASYNC_WAIT_CTX_get_changed_fds, ASYNC_WAIT_CTX_clear_fd were first added to
 133 OpenSSL 1.1.0.
 134
 135 =head1 COPYRIGHT
 136
 137 Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
 138
 139 Licensed under the OpenSSL license (the "License").  You may not use
 140 this file except in compliance with the License.  You can obtain a copy
 141 in the file LICENSE in the source distribution or at
 142 L<https://www.openssl.org/source/license.html>.
 143
 144 =cut