forked from cory/tildefriends
454 lines
17 KiB
Groff
454 lines
17 KiB
Groff
|
.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
|
||
|
|
.\"
|
||
|
|
.\" Standard preamble:
|
||
|
|
.\" ========================================================================
|
||
|
|
.de Sp \" Vertical space (when we can't use .PP)
|
||
|
|
.if t .sp .5v
|
||
|
|
.if n .sp
|
||
|
|
..
|
||
|
|
.de Vb \" Begin verbatim text
|
||
|
|
.ft CW
|
||
|
|
.nf
|
||
|
|
.ne \\$1
|
||
|
|
..
|
||
|
|
.de Ve \" End verbatim text
|
||
|
|
.ft R
|
||
|
|
.fi
|
||
|
|
..
|
||
|
|
.\" Set up some character translations and predefined strings. \*(-- will
|
||
|
|
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
|
||
|
|
.\" double quote, and \*(R" will give a right double quote. \*(C+ will
|
||
|
|
.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
|
||
|
|
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
|
||
|
|
.\" nothing in troff, for use with C<>.
|
||
|
|
.tr \(*W-
|
||
|
|
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
|
||
|
|
.ie n \{\
|
||
|
|
. ds -- \(*W-
|
||
|
|
. ds PI pi
|
||
|
|
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
|
||
|
|
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
|
||
|
|
. ds L" ""
|
||
|
|
. ds R" ""
|
||
|
|
. ds C` ""
|
||
|
|
. ds C' ""
|
||
|
|
'br\}
|
||
|
|
.el\{\
|
||
|
|
. ds -- \|\(em\|
|
||
|
|
. ds PI \(*p
|
||
|
|
. ds L" ``
|
||
|
|
. ds R" ''
|
||
|
|
. ds C`
|
||
|
|
. ds C'
|
||
|
|
'br\}
|
||
|
|
.\"
|
||
|
|
.\" Escape single quotes in literal strings from groff's Unicode transform.
|
||
|
|
.ie \n(.g .ds Aq \(aq
|
||
|
|
.el .ds Aq '
|
||
|
|
.\"
|
||
|
|
.\" If the F register is >0, we'll generate index entries on stderr for
|
||
|
|
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
|
||
|
|
.\" entries marked with X<> in POD. Of course, you'll have to process the
|
||
|
|
.\" output yourself in some meaningful fashion.
|
||
|
|
.\"
|
||
|
|
.\" Avoid warning from groff about undefined register 'F'.
|
||
|
|
.de IX
|
||
|
|
..
|
||
|
|
.nr rF 0
|
||
|
|
.if \n(.g .if rF .nr rF 1
|
||
|
|
.if (\n(rF:(\n(.g==0)) \{\
|
||
|
|
. if \nF \{\
|
||
|
|
. de IX
|
||
|
|
. tm Index:\\$1\t\\n%\t"\\$2"
|
||
|
|
..
|
||
|
|
. if !\nF==2 \{\
|
||
|
|
. nr % 0
|
||
|
|
. nr F 2
|
||
|
|
. \}
|
||
|
|
. \}
|
||
|
|
.\}
|
||
|
|
.rr rF
|
||
|
|
.\"
|
||
|
|
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
|
||
|
|
.\" Fear. Run. Save yourself. No user-serviceable parts.
|
||
|
|
. \" fudge factors for nroff and troff
|
||
|
|
.if n \{\
|
||
|
|
. ds #H 0
|
||
|
|
. ds #V .8m
|
||
|
|
. ds #F .3m
|
||
|
|
. ds #[ \f1
|
||
|
|
. ds #] \fP
|
||
|
|
.\}
|
||
|
|
.if t \{\
|
||
|
|
. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
|
||
|
|
. ds #V .6m
|
||
|
|
. ds #F 0
|
||
|
|
. ds #[ \&
|
||
|
|
. ds #] \&
|
||
|
|
.\}
|
||
|
|
. \" simple accents for nroff and troff
|
||
|
|
.if n \{\
|
||
|
|
. ds ' \&
|
||
|
|
. ds ` \&
|
||
|
|
. ds ^ \&
|
||
|
|
. ds , \&
|
||
|
|
. ds ~ ~
|
||
|
|
. ds /
|
||
|
|
.\}
|
||
|
|
.if t \{\
|
||
|
|
. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
|
||
|
|
. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
|
||
|
|
. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
|
||
|
|
. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
|
||
|
|
. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
|
||
|
|
. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
|
||
|
|
.\}
|
||
|
|
. \" troff and (daisy-wheel) nroff accents
|
||
|
|
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
|
||
|
|
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
|
||
|
|
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
|
||
|
|
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
|
||
|
|
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
|
||
|
|
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
|
||
|
|
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
|
||
|
|
.ds ae a\h'-(\w'a'u*4/10)'e
|
||
|
|
.ds Ae A\h'-(\w'A'u*4/10)'E
|
||
|
|
. \" corrections for vroff
|
||
|
|
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
|
||
|
|
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
|
||
|
|
. \" for low resolution devices (crt and lpr)
|
||
|
|
.if \n(.H>23 .if \n(.V>19 \
|
||
|
|
\{\
|
||
|
|
. ds : e
|
||
|
|
. ds 8 ss
|
||
|
|
. ds o a
|
||
|
|
. ds d- d\h'-1'\(ga
|
||
|
|
. ds D- D\h'-1'\(hy
|
||
|
|
. ds th \o'bp'
|
||
|
|
. ds Th \o'LP'
|
||
|
|
. ds ae ae
|
||
|
|
. ds Ae AE
|
||
|
|
.\}
|
||
|
|
.rm #[ #] #H #V #F C
|
||
|
|
.\" ========================================================================
|
||
|
|
.\"
|
||
|
|
.IX Title "ASYNC_START_JOB 3"
|
||
|
|
.TH ASYNC_START_JOB 3 "2020-04-21" "1.1.1g" "OpenSSL"
|
||
|
|
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
|
||
|
|
.\" way too many mistakes in technical documents.
|
||
|
|
.if n .ad l
|
||
|
|
.nh
|
||
|
|
.SH "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
|
||
|
|
.SH "SYNOPSIS"
|
||
|
|
.IX Header "SYNOPSIS"
|
||
|
|
.Vb 1
|
||
|
|
\& #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);
|
||
|
|
.Ve
|
||
|
|
.SH "DESCRIPTION"
|
||
|
|
.IX Header "DESCRIPTION"
|
||
|
|
OpenSSL implements asynchronous capabilities through an \s-1ASYNC_JOB.\s0 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.
|
||
|
|
.PP
|
||
|
|
The creation of an \s-1ASYNC_JOB\s0 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 \fBASYNC_init_thread()\fR 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 \fBOPENSSL_init_crypto\fR\|(3)) but may be explicitly
|
||
|
|
initiated by using \fBASYNC_cleanup_thread()\fR. No asynchronous jobs must be
|
||
|
|
outstanding for the thread when \fBASYNC_cleanup_thread()\fR is called. Failing to
|
||
|
|
ensure this will result in memory leaks.
|
||
|
|
.PP
|
||
|
|
The \fBmax_size\fR argument limits the number of ASYNC_JOBs that will be held in
|
||
|
|
the pool. If \fBmax_size\fR is set to 0 then no upper limit is set. When an
|
||
|
|
\&\s-1ASYNC_JOB\s0 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 \fBmax_size\fR. When the pool is first initialised
|
||
|
|
\&\fBinit_size\fR ASYNC_JOBs will be created immediately. If \fBASYNC_init_thread()\fR is
|
||
|
|
not called before the pool is first used then it will be called automatically
|
||
|
|
with a \fBmax_size\fR of 0 (no upper limit) and an \fBinit_size\fR of 0 (no ASYNC_JOBs
|
||
|
|
created up front).
|
||
|
|
.PP
|
||
|
|
An asynchronous job is started by calling the \fBASYNC_start_job()\fR function.
|
||
|
|
Initially \fB*job\fR should be \s-1NULL.\s0 \fBctx\fR should point to an \s-1ASYNC_WAIT_CTX\s0
|
||
|
|
object created through the \fBASYNC_WAIT_CTX_new\fR\|(3) function. \fBret\fR should
|
||
|
|
point to a location where the return value of the asynchronous function should
|
||
|
|
be stored on completion of the job. \fBfunc\fR represents the function that should
|
||
|
|
be started asynchronously. The data pointed to by \fBargs\fR and of size \fBsize\fR
|
||
|
|
will be copied and then passed as an argument to \fBfunc\fR when the job starts.
|
||
|
|
ASYNC_start_job will return one of the following values:
|
||
|
|
.IP "\fB\s-1ASYNC_ERR\s0\fR" 4
|
||
|
|
.IX Item "ASYNC_ERR"
|
||
|
|
An error occurred trying to start the job. Check the OpenSSL error queue (e.g.
|
||
|
|
see \fBERR_print_errors\fR\|(3)) for more details.
|
||
|
|
.IP "\fB\s-1ASYNC_NO_JOBS\s0\fR" 4
|
||
|
|
.IX Item "ASYNC_NO_JOBS"
|
||
|
|
There are no jobs currently available in the pool. This call can be retried
|
||
|
|
again at a later time.
|
||
|
|
.IP "\fB\s-1ASYNC_PAUSE\s0\fR" 4
|
||
|
|
.IX Item "ASYNC_PAUSE"
|
||
|
|
The job was successfully started but was \*(L"paused\*(R" before it completed (see
|
||
|
|
\&\fBASYNC_pause_job()\fR below). A handle to the job is placed in \fB*job\fR. Other work
|
||
|
|
can be performed (if desired) and the job restarted at a later time. To restart
|
||
|
|
a job call \fBASYNC_start_job()\fR again passing the job handle in \fB*job\fR. The
|
||
|
|
\&\fBfunc\fR, \fBargs\fR and \fBsize\fR parameters will be ignored when restarting a job.
|
||
|
|
When restarting a job \fBASYNC_start_job()\fR \fBmust\fR be called from the same thread
|
||
|
|
that the job was originally started from.
|
||
|
|
.IP "\fB\s-1ASYNC_FINISH\s0\fR" 4
|
||
|
|
.IX Item "ASYNC_FINISH"
|
||
|
|
The job completed. \fB*job\fR will be \s-1NULL\s0 and the return value from \fBfunc\fR will
|
||
|
|
be placed in \fB*ret\fR.
|
||
|
|
.PP
|
||
|
|
At any one time there can be a maximum of one job actively running per thread
|
||
|
|
(you can have many that are paused). \fBASYNC_get_current_job()\fR can be used to get
|
||
|
|
a pointer to the currently executing \s-1ASYNC_JOB.\s0 If no job is currently executing
|
||
|
|
then this will return \s-1NULL.\s0
|
||
|
|
.PP
|
||
|
|
If executing within the context of a job (i.e. having been called directly or
|
||
|
|
indirectly by the function \*(L"func\*(R" passed as an argument to \fBASYNC_start_job()\fR)
|
||
|
|
then \fBASYNC_pause_job()\fR will immediately return control to the calling
|
||
|
|
application with \s-1ASYNC_PAUSE\s0 returned from the \fBASYNC_start_job()\fR call. A
|
||
|
|
subsequent call to ASYNC_start_job passing in the relevant \s-1ASYNC_JOB\s0 in the
|
||
|
|
\&\fB*job\fR parameter will resume execution from the \fBASYNC_pause_job()\fR call. If
|
||
|
|
\&\fBASYNC_pause_job()\fR is called whilst not within the context of a job then no
|
||
|
|
action is taken and \fBASYNC_pause_job()\fR returns immediately.
|
||
|
|
.PP
|
||
|
|
\&\fBASYNC_get_wait_ctx()\fR can be used to get a pointer to the \s-1ASYNC_WAIT_CTX\s0
|
||
|
|
for the \fBjob\fR. ASYNC_WAIT_CTXs can have a \*(L"wait\*(R" file descriptor associated
|
||
|
|
with them. Applications can wait for the file descriptor to be ready for \*(L"read\*(R"
|
||
|
|
using a system function call such as select or poll (being ready for \*(L"read\*(R"
|
||
|
|
indicates that the job should be resumed). If no file descriptor is made
|
||
|
|
available then an application will have to periodically \*(L"poll\*(R" the job by
|
||
|
|
attempting to restart it to see if it is ready to continue.
|
||
|
|
.PP
|
||
|
|
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 \fBASYNC_WAIT_CTX_set_wait_fd\fR\|(3) followed by
|
||
|
|
\&\fBASYNC_pause_job()\fR 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 \*(L"select\*(R" 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
|
||
|
|
\&\*(L"readable\*(R". Once resumed the engine should clear the wake signal on the wait
|
||
|
|
file descriptor.
|
||
|
|
.PP
|
||
|
|
The \fBASYNC_block_pause()\fR function will prevent the currently active job from
|
||
|
|
pausing. The block will remain in place until a subsequent call to
|
||
|
|
\&\fBASYNC_unblock_pause()\fR. These functions can be nested, e.g. if you call
|
||
|
|
\&\fBASYNC_block_pause()\fR twice then you must call \fBASYNC_unblock_pause()\fR 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 \s-1ASYNC_JOB\s0 an
|
||
|
|
application acquires a lock. It then calls some cryptographic function which
|
||
|
|
invokes \fBASYNC_pause_job()\fR. This returns control back to the code that created
|
||
|
|
the \s-1ASYNC_JOB.\s0 If that code then attempts to acquire the same lock before
|
||
|
|
resuming the original job then a deadlock can occur. By calling
|
||
|
|
\&\fBASYNC_block_pause()\fR immediately after acquiring the lock and
|
||
|
|
\&\fBASYNC_unblock_pause()\fR immediately before releasing it then this situation cannot
|
||
|
|
occur.
|
||
|
|
.PP
|
||
|
|
Some platforms cannot support async operations. The \fBASYNC_is_capable()\fR function
|
||
|
|
can be used to detect whether the current platform is async capable or not.
|
||
|
|
.SH "RETURN VALUES"
|
||
|
|
.IX Header "RETURN VALUES"
|
||
|
|
ASYNC_init_thread returns 1 on success or 0 otherwise.
|
||
|
|
.PP
|
||
|
|
ASYNC_start_job returns one of \s-1ASYNC_ERR, ASYNC_NO_JOBS, ASYNC_PAUSE\s0 or
|
||
|
|
\&\s-1ASYNC_FINISH\s0 as described above.
|
||
|
|
.PP
|
||
|
|
ASYNC_pause_job returns 0 if an error occurred or 1 on success. If called when
|
||
|
|
not within the context of an \s-1ASYNC_JOB\s0 then this is counted as success so 1 is
|
||
|
|
returned.
|
||
|
|
.PP
|
||
|
|
ASYNC_get_current_job returns a pointer to the currently executing \s-1ASYNC_JOB\s0 or
|
||
|
|
\&\s-1NULL\s0 if not within the context of a job.
|
||
|
|
.PP
|
||
|
|
\&\fBASYNC_get_wait_ctx()\fR returns a pointer to the \s-1ASYNC_WAIT_CTX\s0 for the job.
|
||
|
|
.PP
|
||
|
|
\&\fBASYNC_is_capable()\fR returns 1 if the current platform is async capable or 0
|
||
|
|
otherwise.
|
||
|
|
.SH "NOTES"
|
||
|
|
.IX Header "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.
|
||
|
|
.SH "EXAMPLES"
|
||
|
|
.IX Header "EXAMPLES"
|
||
|
|
The following example demonstrates how to use most of the core async APIs:
|
||
|
|
.PP
|
||
|
|
.Vb 7
|
||
|
|
\& #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 = \*(AqX\*(Aq;
|
||
|
|
\&
|
||
|
|
\& currjob = ASYNC_get_current_job();
|
||
|
|
\& if (currjob != NULL) {
|
||
|
|
\& printf("Executing within a job\en");
|
||
|
|
\& } else {
|
||
|
|
\& printf("Not executing within a job \- should not happen\en");
|
||
|
|
\& return 0;
|
||
|
|
\& }
|
||
|
|
\&
|
||
|
|
\& msg = (unsigned char *)arg;
|
||
|
|
\& printf("Passed in message is: %s\en", msg);
|
||
|
|
\&
|
||
|
|
\& if (pipe(pipefds) != 0) {
|
||
|
|
\& printf("Failed to create pipe\en");
|
||
|
|
\& return 0;
|
||
|
|
\& }
|
||
|
|
\& wptr = OPENSSL_malloc(sizeof(OSSL_ASYNC_FD));
|
||
|
|
\& if (wptr == NULL) {
|
||
|
|
\& printf("Failed to malloc\en");
|
||
|
|
\& 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\en");
|
||
|
|
\&
|
||
|
|
\& 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...\en");
|
||
|
|
\&
|
||
|
|
\& ctx = ASYNC_WAIT_CTX_new();
|
||
|
|
\& if (ctx == NULL) {
|
||
|
|
\& printf("Failed to create ASYNC_WAIT_CTX\en");
|
||
|
|
\& abort();
|
||
|
|
\& }
|
||
|
|
\&
|
||
|
|
\& for (;;) {
|
||
|
|
\& switch (ASYNC_start_job(&job, ctx, &ret, jobfunc, msg, sizeof(msg))) {
|
||
|
|
\& case ASYNC_ERR:
|
||
|
|
\& case ASYNC_NO_JOBS:
|
||
|
|
\& printf("An error occurred\en");
|
||
|
|
\& goto end;
|
||
|
|
\& case ASYNC_PAUSE:
|
||
|
|
\& printf("Job was paused\en");
|
||
|
|
\& break;
|
||
|
|
\& case ASYNC_FINISH:
|
||
|
|
\& printf("Job finished with return value %d\en", ret);
|
||
|
|
\& goto end;
|
||
|
|
\& }
|
||
|
|
\&
|
||
|
|
\& /* Wait for the job to be woken */
|
||
|
|
\& printf("Waiting for the job to be woken up\en");
|
||
|
|
\&
|
||
|
|
\& if (!ASYNC_WAIT_CTX_get_all_fds(ctx, NULL, &numfds)
|
||
|
|
\& || numfds > 1) {
|
||
|
|
\& printf("Unexpected number of fds\en");
|
||
|
|
\& 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\en");
|
||
|
|
\&
|
||
|
|
\& return 0;
|
||
|
|
\& }
|
||
|
|
.Ve
|
||
|
|
.PP
|
||
|
|
The expected output from executing the above example program is:
|
||
|
|
.PP
|
||
|
|
.Vb 8
|
||
|
|
\& 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
|
||
|
|
.Ve
|
||
|
|
.SH "SEE ALSO"
|
||
|
|
.IX Header "SEE ALSO"
|
||
|
|
\&\fBcrypto\fR\|(7), \fBERR_print_errors\fR\|(3)
|
||
|
|
.SH "HISTORY"
|
||
|
|
.IX Header "HISTORY"
|
||
|
|
ASYNC_init_thread, ASYNC_cleanup_thread,
|
||
|
|
ASYNC_start_job, ASYNC_pause_job, ASYNC_get_current_job, \fBASYNC_get_wait_ctx()\fR,
|
||
|
|
\&\fBASYNC_block_pause()\fR, \fBASYNC_unblock_pause()\fR and \fBASYNC_is_capable()\fR were first
|
||
|
|
added in OpenSSL 1.1.0.
|
||
|
|
.SH "COPYRIGHT"
|
||
|
|
.IX Header "COPYRIGHT"
|
||
|
|
Copyright 2015\-2019 The OpenSSL Project Authors. All Rights Reserved.
|
||
|
|
.PP
|
||
|
|
Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use
|
||
|
|
this file except in compliance with the License. You can obtain a copy
|
||
|
|
in the file \s-1LICENSE\s0 in the source distribution or at
|
||
|
|
<https://www.openssl.org/source/license.html>.
|