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