1=pod 2 3=head1 NAME 4 5ASYNC_get_wait_ctx, 6ASYNC_init_thread, ASYNC_cleanup_thread, ASYNC_start_job, ASYNC_pause_job, 7ASYNC_get_current_job, ASYNC_block_pause, ASYNC_unblock_pause, ASYNC_is_capable, 8ASYNC_stack_alloc_fn, ASYNC_stack_free_fn, ASYNC_set_mem_functions, ASYNC_get_mem_functions 9- asynchronous job management functions 10 11=head1 SYNOPSIS 12 13 #include <openssl/async.h> 14 15 int ASYNC_init_thread(size_t max_size, size_t init_size); 16 void ASYNC_cleanup_thread(void); 17 18 int ASYNC_start_job(ASYNC_JOB **job, ASYNC_WAIT_CTX *ctx, int *ret, 19 int (*func)(void *), void *args, size_t size); 20 int ASYNC_pause_job(void); 21 22 ASYNC_JOB *ASYNC_get_current_job(void); 23 ASYNC_WAIT_CTX *ASYNC_get_wait_ctx(ASYNC_JOB *job); 24 void ASYNC_block_pause(void); 25 void ASYNC_unblock_pause(void); 26 27 int ASYNC_is_capable(void); 28 29 typedef void *(*ASYNC_stack_alloc_fn)(size_t *num); 30 typedef void (*ASYNC_stack_free_fn)(void *addr); 31 int ASYNC_set_mem_functions(ASYNC_stack_alloc_fn alloc_fn, 32 ASYNC_stack_free_fn free_fn); 33 void ASYNC_get_mem_functions(ASYNC_stack_alloc_fn *alloc_fn, 34 ASYNC_stack_free_fn *free_fn); 35 36=head1 DESCRIPTION 37 38OpenSSL implements asynchronous capabilities through an B<ASYNC_JOB>. This 39represents code that can be started and executes until some event occurs. At 40that point the code can be paused and control returns to user code until some 41subsequent event indicates that the job can be resumed. 42 43The creation of an B<ASYNC_JOB> is a relatively expensive operation. Therefore, 44for efficiency reasons, jobs can be created up front and reused many times. They 45are held in a pool until they are needed, at which point they are removed from 46the pool, used, and then returned to the pool when the job completes. If the 47user application is multi-threaded, then ASYNC_init_thread() may be called for 48each thread that will initiate asynchronous jobs. Before 49user code exits per-thread resources need to be cleaned up. This will normally 50occur automatically (see L<OPENSSL_init_crypto(3)>) but may be explicitly 51initiated by using ASYNC_cleanup_thread(). No asynchronous jobs must be 52outstanding for the thread when ASYNC_cleanup_thread() is called. Failing to 53ensure this will result in memory leaks. 54 55The I<max_size> argument limits the number of B<ASYNC_JOB>s that will be held in 56the pool. If I<max_size> is set to 0 then no upper limit is set. When an 57B<ASYNC_JOB> is needed but there are none available in the pool already then one 58will be automatically created, as long as the total of B<ASYNC_JOB>s managed by 59the pool does not exceed I<max_size>. When the pool is first initialised 60I<init_size> B<ASYNC_JOB>s will be created immediately. If ASYNC_init_thread() 61is not called before the pool is first used then it will be called automatically 62with a I<max_size> of 0 (no upper limit) and an I<init_size> of 0 (no 63B<ASYNC_JOB>s created up front). 64 65An asynchronous job is started by calling the ASYNC_start_job() function. 66Initially I<*job> should be NULL. I<ctx> should point to an B<ASYNC_WAIT_CTX> 67object created through the L<ASYNC_WAIT_CTX_new(3)> function. I<ret> should 68point to a location where the return value of the asynchronous function should 69be stored on completion of the job. I<func> represents the function that should 70be started asynchronously. The data pointed to by I<args> and of size I<size> 71will be copied and then passed as an argument to I<func> when the job starts. 72ASYNC_start_job will return one of the following values: 73 74=over 4 75 76=item B<ASYNC_ERR> 77 78An error occurred trying to start the job. Check the OpenSSL error queue (e.g. 79see L<ERR_print_errors(3)>) for more details. 80 81=item B<ASYNC_NO_JOBS> 82 83There are no jobs currently available in the pool. This call can be retried 84again at a later time. 85 86=item B<ASYNC_PAUSE> 87 88The job was successfully started but was "paused" before it completed (see 89ASYNC_pause_job() below). A handle to the job is placed in I<*job>. Other work 90can be performed (if desired) and the job restarted at a later time. To restart 91a job call ASYNC_start_job() again passing the job handle in I<*job>. The 92I<func>, I<args> and I<size> parameters will be ignored when restarting a job. 93When restarting a job ASYNC_start_job() B<must> be called from the same thread 94that the job was originally started from. 95 96=item B<ASYNC_FINISH> 97 98The job completed. I<*job> will be NULL and the return value from I<func> will 99be placed in I<*ret>. 100 101=back 102 103At any one time there can be a maximum of one job actively running per thread 104(you can have many that are paused). ASYNC_get_current_job() can be used to get 105a pointer to the currently executing B<ASYNC_JOB>. If no job is currently 106executing then this will return NULL. 107 108If executing within the context of a job (i.e. having been called directly or 109indirectly by the function "func" passed as an argument to ASYNC_start_job()) 110then ASYNC_pause_job() will immediately return control to the calling 111application with B<ASYNC_PAUSE> returned from the ASYNC_start_job() call. A 112subsequent call to ASYNC_start_job passing in the relevant B<ASYNC_JOB> in the 113I<*job> parameter will resume execution from the ASYNC_pause_job() call. If 114ASYNC_pause_job() is called whilst not within the context of a job then no 115action is taken and ASYNC_pause_job() returns immediately. 116 117ASYNC_get_wait_ctx() can be used to get a pointer to the B<ASYNC_WAIT_CTX> 118for the I<job>. B<ASYNC_WAIT_CTX>s contain two different ways to notify 119applications that a job is ready to be resumed. One is a "wait" file 120descriptor, and the other is a "callback" mechanism. 121 122The "wait" file descriptor associated with B<ASYNC_WAIT_CTX> is used for 123applications to wait for the file descriptor to be ready for "read" using a 124system function call such as select or poll (being ready for "read" indicates 125that the job should be resumed). If no file descriptor is made available then 126an application will have to periodically "poll" the job by attempting to restart 127it to see if it is ready to continue. 128 129B<ASYNC_WAIT_CTX>s also have a "callback" mechanism to notify applications. The 130callback is set by an application, and it will be automatically called when an 131engine completes a cryptography operation, so that the application can resume 132the paused work flow without polling. An engine could be written to look whether 133the callback has been set. If it has then it would use the callback mechanism 134in preference to the file descriptor notifications. If a callback is not set 135then the engine may use file descriptor based notifications. Please note that 136not all engines may support the callback mechanism, so the callback may not be 137used even if it has been set. See ASYNC_WAIT_CTX_new() for more details. 138 139The ASYNC_block_pause() function will prevent the currently active job from 140pausing. The block will remain in place until a subsequent call to 141ASYNC_unblock_pause(). These functions can be nested, e.g. if you call 142ASYNC_block_pause() twice then you must call ASYNC_unblock_pause() twice in 143order to re-enable pausing. If these functions are called while there is no 144currently active job then they have no effect. This functionality can be useful 145to avoid deadlock scenarios. For example during the execution of an B<ASYNC_JOB> 146an application acquires a lock. It then calls some cryptographic function which 147invokes ASYNC_pause_job(). This returns control back to the code that created 148the B<ASYNC_JOB>. If that code then attempts to acquire the same lock before 149resuming the original job then a deadlock can occur. By calling 150ASYNC_block_pause() immediately after acquiring the lock and 151ASYNC_unblock_pause() immediately before releasing it then this situation cannot 152occur. 153 154Some platforms cannot support async operations. The ASYNC_is_capable() function 155can be used to detect whether the current platform is async capable or not. 156 157Custom memory allocation functions are supported for the POSIX platform. 158Custom memory allocation functions allow alternative methods of allocating 159stack memory such as mmap, or using stack memory from the current thread. 160Using an ASYNC_stack_alloc_fn callback also allows manipulation of the stack 161size, which defaults to 32k. 162The stack size can be altered by allocating a stack of a size different to 163the requested size, and passing back the new stack size in the callback's I<*num> 164parameter. 165 166=head1 RETURN VALUES 167 168ASYNC_init_thread returns 1 on success or 0 otherwise. 169 170ASYNC_start_job returns one of B<ASYNC_ERR>, B<ASYNC_NO_JOBS>, B<ASYNC_PAUSE> or 171B<ASYNC_FINISH> as described above. 172 173ASYNC_pause_job returns 0 if an error occurred or 1 on success. If called when 174not within the context of an B<ASYNC_JOB> then this is counted as success so 1 175is returned. 176 177ASYNC_get_current_job returns a pointer to the currently executing B<ASYNC_JOB> 178or NULL if not within the context of a job. 179 180ASYNC_get_wait_ctx() returns a pointer to the B<ASYNC_WAIT_CTX> for the job. 181 182ASYNC_is_capable() returns 1 if the current platform is async capable or 0 183otherwise. 184 185ASYNC_set_mem_functions returns 1 if custom stack allocators are supported by 186the current platform and no allocations have already occurred or 0 otherwise. 187 188=head1 NOTES 189 190On Windows platforms the F<< <openssl/async.h> >> header is dependent on some 191of the types customarily made available by including F<< <windows.h> >>. The 192application developer is likely to require control over when the latter 193is included, commonly as one of the first included headers. Therefore, 194it is defined as an application developer's responsibility to include 195F<< <windows.h> >> prior to F<< <openssl/async.h> >>. 196 197=head1 EXAMPLES 198 199The following example demonstrates how to use most of the core async APIs: 200 201 #ifdef _WIN32 202 # include <windows.h> 203 #endif 204 #include <stdio.h> 205 #include <unistd.h> 206 #include <openssl/async.h> 207 #include <openssl/crypto.h> 208 209 int unique = 0; 210 211 void cleanup(ASYNC_WAIT_CTX *ctx, const void *key, OSSL_ASYNC_FD r, void *vw) 212 { 213 OSSL_ASYNC_FD *w = (OSSL_ASYNC_FD *)vw; 214 215 close(r); 216 close(*w); 217 OPENSSL_free(w); 218 } 219 220 int jobfunc(void *arg) 221 { 222 ASYNC_JOB *currjob; 223 unsigned char *msg; 224 int pipefds[2] = {0, 0}; 225 OSSL_ASYNC_FD *wptr; 226 char buf = 'X'; 227 228 currjob = ASYNC_get_current_job(); 229 if (currjob != NULL) { 230 printf("Executing within a job\n"); 231 } else { 232 printf("Not executing within a job - should not happen\n"); 233 return 0; 234 } 235 236 msg = (unsigned char *)arg; 237 printf("Passed in message is: %s\n", msg); 238 239 if (pipe(pipefds) != 0) { 240 printf("Failed to create pipe\n"); 241 return 0; 242 } 243 wptr = OPENSSL_malloc(sizeof(OSSL_ASYNC_FD)); 244 if (wptr == NULL) { 245 printf("Failed to malloc\n"); 246 return 0; 247 } 248 *wptr = pipefds[1]; 249 ASYNC_WAIT_CTX_set_wait_fd(ASYNC_get_wait_ctx(currjob), &unique, 250 pipefds[0], wptr, cleanup); 251 252 /* 253 * Normally some external event would cause this to happen at some 254 * later point - but we do it here for demo purposes, i.e. 255 * immediately signalling that the job is ready to be woken up after 256 * we return to main via ASYNC_pause_job(). 257 */ 258 write(pipefds[1], &buf, 1); 259 260 /* Return control back to main */ 261 ASYNC_pause_job(); 262 263 /* Clear the wake signal */ 264 read(pipefds[0], &buf, 1); 265 266 printf ("Resumed the job after a pause\n"); 267 268 return 1; 269 } 270 271 int main(void) 272 { 273 ASYNC_JOB *job = NULL; 274 ASYNC_WAIT_CTX *ctx = NULL; 275 int ret; 276 OSSL_ASYNC_FD waitfd; 277 fd_set waitfdset; 278 size_t numfds; 279 unsigned char msg[13] = "Hello world!"; 280 281 printf("Starting...\n"); 282 283 ctx = ASYNC_WAIT_CTX_new(); 284 if (ctx == NULL) { 285 printf("Failed to create ASYNC_WAIT_CTX\n"); 286 abort(); 287 } 288 289 for (;;) { 290 switch (ASYNC_start_job(&job, ctx, &ret, jobfunc, msg, sizeof(msg))) { 291 case ASYNC_ERR: 292 case ASYNC_NO_JOBS: 293 printf("An error occurred\n"); 294 goto end; 295 case ASYNC_PAUSE: 296 printf("Job was paused\n"); 297 break; 298 case ASYNC_FINISH: 299 printf("Job finished with return value %d\n", ret); 300 goto end; 301 } 302 303 /* Wait for the job to be woken */ 304 printf("Waiting for the job to be woken up\n"); 305 306 if (!ASYNC_WAIT_CTX_get_all_fds(ctx, NULL, &numfds) 307 || numfds > 1) { 308 printf("Unexpected number of fds\n"); 309 abort(); 310 } 311 ASYNC_WAIT_CTX_get_all_fds(ctx, &waitfd, &numfds); 312 FD_ZERO(&waitfdset); 313 FD_SET(waitfd, &waitfdset); 314 select(waitfd + 1, &waitfdset, NULL, NULL, NULL); 315 } 316 317 end: 318 ASYNC_WAIT_CTX_free(ctx); 319 printf("Finishing\n"); 320 321 return 0; 322 } 323 324The expected output from executing the above example program is: 325 326 Starting... 327 Executing within a job 328 Passed in message is: Hello world! 329 Job was paused 330 Waiting for the job to be woken up 331 Resumed the job after a pause 332 Job finished with return value 1 333 Finishing 334 335=head1 SEE ALSO 336 337L<crypto(7)>, L<ERR_print_errors(3)> 338 339=head1 HISTORY 340 341ASYNC_init_thread, ASYNC_cleanup_thread, 342ASYNC_start_job, ASYNC_pause_job, ASYNC_get_current_job, ASYNC_get_wait_ctx(), 343ASYNC_block_pause(), ASYNC_unblock_pause() and ASYNC_is_capable() were first 344added in OpenSSL 1.1.0. 345 346=head1 COPYRIGHT 347 348Copyright 2015-2022 The OpenSSL Project Authors. All Rights Reserved. 349 350Licensed under the Apache License 2.0 (the "License"). You may not use 351this file except in compliance with the License. You can obtain a copy 352in the file LICENSE in the source distribution or at 353L<https://www.openssl.org/source/license.html>. 354 355=cut 356