+++ /dev/null
-=pod
-
-=head1 NAME
-
-ASYNC_get_wait_ctx,
-ASYNC_init_thread, ASYNC_cleanup_thread, ASYNC_start_job, ASYNC_pause_job,
-ASYNC_get_current_job, ASYNC_block_pause, ASYNC_unblock_pause, ASYNC_is_capable
-- asynchronous job management functions
-
-=head1 SYNOPSIS
-
- #include <openssl/async.h>
-
- int ASYNC_init_thread(size_t max_size, size_t init_size);
- void ASYNC_cleanup_thread(void);
-
- int ASYNC_start_job(ASYNC_JOB **job, ASYNC_WAIT_CTX *ctx, int *ret,
- int (*func)(void *), void *args, size_t size);
- int ASYNC_pause_job(void);
-
- ASYNC_JOB *ASYNC_get_current_job(void);
- ASYNC_WAIT_CTX *ASYNC_get_wait_ctx(ASYNC_JOB *job);
- void ASYNC_block_pause(void);
- void ASYNC_unblock_pause(void);
-
- int ASYNC_is_capable(void);
-
-=head1 DESCRIPTION
-
-OpenSSL implements asynchronous capabilities through an ASYNC_JOB. This
-represents code that can be started and executes until some event occurs. At
-that point the code can be paused and control returns to user code until some
-subsequent event indicates that the job can be resumed.
-
-The creation of an ASYNC_JOB is a relatively expensive operation. Therefore, for
-efficiency reasons, jobs can be created up front and reused many times. They are
-held in a pool until they are needed, at which point they are removed from the
-pool, used, and then returned to the pool when the job completes. If the user
-application is multi-threaded, then ASYNC_init_thread() may be called for each
-thread that will initiate asynchronous jobs. Before
-user code exits per-thread resources need to be cleaned up. This will normally
-occur automatically (see L<OPENSSL_init_crypto(3)>) but may be explicitly
-initiated by using ASYNC_cleanup_thread(). No asynchronous jobs must be
-outstanding for the thread when ASYNC_cleanup_thread() is called. Failing to
-ensure this will result in memory leaks.
-
-The B<max_size> argument limits the number of ASYNC_JOBs that will be held in
-the pool. If B<max_size> is set to 0 then no upper limit is set. When an
-ASYNC_JOB is needed but there are none available in the pool already then one
-will be automatically created, as long as the total of ASYNC_JOBs managed by the
-pool does not exceed B<max_size>. When the pool is first initialised
-B<init_size> ASYNC_JOBs will be created immediately. If ASYNC_init_thread() is
-not called before the pool is first used then it will be called automatically
-with a B<max_size> of 0 (no upper limit) and an B<init_size> of 0 (no ASYNC_JOBs
-created up front).
-
-An asynchronous job is started by calling the ASYNC_start_job() function.
-Initially B<*job> should be NULL. B<ctx> should point to an ASYNC_WAIT_CTX
-object created through the L<ASYNC_WAIT_CTX_new(3)> function. B<ret> should
-point to a location where the return value of the asynchronous function should
-be stored on completion of the job. B<func> represents the function that should
-be started asynchronously. The data pointed to by B<args> and of size B<size>
-will be copied and then passed as an argument to B<func> when the job starts.
-ASYNC_start_job will return one of the following values:
-
-=over 4
-
-=item B<ASYNC_ERR>
-
-An error occurred trying to start the job. Check the OpenSSL error queue (e.g.
-see L<ERR_print_errors(3)>) for more details.
-
-=item B<ASYNC_NO_JOBS>
-
-There are no jobs currently available in the pool. This call can be retried
-again at a later time.
-
-=item B<ASYNC_PAUSE>
-
-The job was successfully started but was "paused" before it completed (see
-ASYNC_pause_job() below). A handle to the job is placed in B<*job>. Other work
-can be performed (if desired) and the job restarted at a later time. To restart
-a job call ASYNC_start_job() again passing the job handle in B<*job>. The
-B<func>, B<args> and B<size> parameters will be ignored when restarting a job.
-When restarting a job ASYNC_start_job() B<must> be called from the same thread
-that the job was originally started from.
-
-=item B<ASYNC_FINISH>
-
-The job completed. B<*job> will be NULL and the return value from B<func> will
-be placed in B<*ret>.
-
-=back
-
-At any one time there can be a maximum of one job actively running per thread
-(you can have many that are paused). ASYNC_get_current_job() can be used to get
-a pointer to the currently executing ASYNC_JOB. If no job is currently executing
-then this will return NULL.
-
-If executing within the context of a job (i.e. having been called directly or
-indirectly by the function "func" passed as an argument to ASYNC_start_job())
-then ASYNC_pause_job() will immediately return control to the calling
-application with ASYNC_PAUSE returned from the ASYNC_start_job() call. A
-subsequent call to ASYNC_start_job passing in the relevant ASYNC_JOB in the
-B<*job> parameter will resume execution from the ASYNC_pause_job() call. If
-ASYNC_pause_job() is called whilst not within the context of a job then no
-action is taken and ASYNC_pause_job() returns immediately.
-
-ASYNC_get_wait_ctx() can be used to get a pointer to the ASYNC_WAIT_CTX
-for the B<job>. ASYNC_WAIT_CTXs can have a "wait" file descriptor associated
-with them. 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.
-
-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 L<ASYNC_WAIT_CTX_set_wait_fd(3)> 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.
-
-The ASYNC_block_pause() function will prevent the currently active job from
-pausing. The block will remain in place until a subsequent call to
-ASYNC_unblock_pause(). These functions can be nested, e.g. if you call
-ASYNC_block_pause() twice then you must call ASYNC_unblock_pause() twice in
-order to re-enable pausing. If these functions are called while there is no
-currently active job then they have no effect. This functionality can be useful
-to avoid deadlock scenarios. For example during the execution of an ASYNC_JOB an
-application acquires a lock. It then calls some cryptographic function which
-invokes ASYNC_pause_job(). This returns control back to the code that created
-the ASYNC_JOB. If that code then attempts to acquire the same lock before
-resuming the original job then a deadlock can occur. By calling
-ASYNC_block_pause() immediately after acquiring the lock and
-ASYNC_unblock_pause() immediately before releasing it then this situation cannot
-occur.
-
-Some platforms cannot support async operations. The ASYNC_is_capable() function
-can be used to detect whether the current platform is async capable or not.
-
-=head1 RETURN VALUES
-
-ASYNC_init_thread returns 1 on success or 0 otherwise.
-
-ASYNC_start_job returns one of ASYNC_ERR, ASYNC_NO_JOBS, ASYNC_PAUSE or
-ASYNC_FINISH as described above.
-
-ASYNC_pause_job returns 0 if an error occurred or 1 on success. If called when
-not within the context of an ASYNC_JOB then this is counted as success so 1 is
-returned.
-
-ASYNC_get_current_job returns a pointer to the currently executing ASYNC_JOB or
-NULL if not within the context of a job.
-
-ASYNC_get_wait_ctx() returns a pointer to the ASYNC_WAIT_CTX for the job.
-
-ASYNC_is_capable() returns 1 if the current platform is async capable or 0
-otherwise.
-
-=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 EXAMPLE
-
-The following example demonstrates how to use most of the core async APIs:
-
- #ifdef _WIN32
- # include <windows.h>
- #endif
- #include <stdio.h>
- #include <unistd.h>
- #include <openssl/async.h>
- #include <openssl/crypto.h>
-
- int unique = 0;
-
- void cleanup(ASYNC_WAIT_CTX *ctx, const void *key, OSSL_ASYNC_FD r, void *vw)
- {
- OSSL_ASYNC_FD *w = (OSSL_ASYNC_FD *)vw;
- close(r);
- close(*w);
- OPENSSL_free(w);
- }
-
- int jobfunc(void *arg)
- {
- ASYNC_JOB *currjob;
- unsigned char *msg;
- int pipefds[2] = {0, 0};
- OSSL_ASYNC_FD *wptr;
- char buf = 'X';
-
- currjob = ASYNC_get_current_job();
- if (currjob != NULL) {
- printf("Executing within a job\n");
- } else {
- printf("Not executing within a job - should not happen\n");
- return 0;
- }
-
- msg = (unsigned char *)arg;
- printf("Passed in message is: %s\n", msg);
-
- if (pipe(pipefds) != 0) {
- printf("Failed to create pipe\n");
- return 0;
- }
- wptr = OPENSSL_malloc(sizeof(OSSL_ASYNC_FD));
- if (wptr == NULL) {
- printf("Failed to malloc\n");
- return 0;
- }
- *wptr = pipefds[1];
- ASYNC_WAIT_CTX_set_wait_fd(ASYNC_get_wait_ctx(currjob), &unique,
- pipefds[0], wptr, cleanup);
-
- /*
- * Normally some external event would cause this to happen at some
- * later point - but we do it here for demo purposes, i.e.
- * immediately signalling that the job is ready to be woken up after
- * we return to main via ASYNC_pause_job().
- */
- write(pipefds[1], &buf, 1);
-
- /* Return control back to main */
- ASYNC_pause_job();
-
- /* Clear the wake signal */
- read(pipefds[0], &buf, 1);
-
- printf ("Resumed the job after a pause\n");
-
- return 1;
- }
-
- int main(void)
- {
- ASYNC_JOB *job = NULL;
- ASYNC_WAIT_CTX *ctx = NULL;
- int ret;
- OSSL_ASYNC_FD waitfd;
- fd_set waitfdset;
- size_t numfds;
- unsigned char msg[13] = "Hello world!";
-
- printf("Starting...\n");
-
- ctx = ASYNC_WAIT_CTX_new();
- if (ctx == NULL) {
- printf("Failed to create ASYNC_WAIT_CTX\n");
- abort();
- }
-
- for (;;) {
- switch(ASYNC_start_job(&job, ctx, &ret, jobfunc, msg, sizeof(msg))) {
- case ASYNC_ERR:
- case ASYNC_NO_JOBS:
- printf("An error occurred\n");
- goto end;
- case ASYNC_PAUSE:
- printf("Job was paused\n");
- break;
- case ASYNC_FINISH:
- printf("Job finished with return value %d\n", ret);
- goto end;
- }
-
- /* Wait for the job to be woken */
- printf("Waiting for the job to be woken up\n");
-
- if (!ASYNC_WAIT_CTX_get_all_fds(ctx, NULL, &numfds)
- || numfds > 1) {
- printf("Unexpected number of fds\n");
- abort();
- }
- ASYNC_WAIT_CTX_get_all_fds(ctx, &waitfd, &numfds);
- FD_ZERO(&waitfdset);
- FD_SET(waitfd, &waitfdset);
- select(waitfd + 1, &waitfdset, NULL, NULL, NULL);
- }
-
- end:
- ASYNC_WAIT_CTX_free(ctx);
- printf("Finishing\n");
-
- return 0;
- }
-
-The expected output from executing the above example program is:
-
- Starting...
- Executing within a job
- Passed in message is: Hello world!
- Job was paused
- Waiting for the job to be woken up
- Resumed the job after a pause
- Job finished with return value 1
- Finishing
-
-=head1 SEE ALSO
-
-L<crypto(3)>, L<ERR_print_errors(3)>
-
-=head1 HISTORY
-
-ASYNC_init_thread, ASYNC_cleanup_thread,
-ASYNC_start_job, ASYNC_pause_job, ASYNC_get_current_job, ASYNC_get_wait_ctx(),
-ASYNC_block_pause(), ASYNC_unblock_pause() and ASYNC_is_capable() were first
-added to OpenSSL 1.1.0.
-
-=head1 COPYRIGHT
-
-Copyright 2015-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
projects / openssl.git / blobdiff