From 8227255006f3a7e5091e1637f8b5cc904355f045 Mon Sep 17 00:00:00 2001 From: Matt Caswell Date: Fri, 9 Oct 2015 16:39:35 +0100 Subject: [PATCH] Add clarification to docs on ASYNC_free_pool() Clarify that you must only call this after all async jobs have completed - otherwise you could get memory leaks. Reviewed-by: Rich Salz --- doc/crypto/ASYNC_start_job.pod | 24 ++++++++++++++---------- 1 file changed, 14 insertions(+), 10 deletions(-) diff --git a/doc/crypto/ASYNC_start_job.pod b/doc/crypto/ASYNC_start_job.pod index 6086260ff5..4abe017263 100644 --- a/doc/crypto/ASYNC_start_job.pod +++ b/doc/crypto/ASYNC_start_job.pod @@ -37,16 +37,20 @@ any of the asynchronous job functions, user code should first call ASYNC_init_pool(). If the user application is multi-threaded, then this should be done for each thread that will initiate asynchronous jobs. Before user code exits it should free the pool up (for each thread where a pool was initialised) -using ASYNC_free_pool(). The B argument limits the number of -ASYNC_JOBs that will be held in the pool. If B 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. When the pool is -first initialised B ASYNC_JOBs will be created immediately. If -ASYNC_init_pool() is not called before the pool is first used then it will be -called automatically with a B of 0 (no upper limit) and an -B of 0 (no ASYNC_JOBs created up front). If a pool is created in this -way it must still be cleaned up with an explicit call to ASYNC_free_pool(). +using ASYNC_free_pool(). No asynchronous jobs must be outstanding for the thread +when ASYNC_free_pool() is called. Failing to ensure this will result in memory +leaks. + +The B argument limits the number of ASYNC_JOBs that will be held in +the pool. If B 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. When the pool is first initialised +B ASYNC_JOBs will be created immediately. If ASYNC_init_pool() is not +called before the pool is first used then it will be called automatically with a +B of 0 (no upper limit) and an B of 0 (no ASYNC_JOBs +created up front). If a pool is created in this way it must still be cleaned up +with an explicit call to ASYNC_free_pool(). An asynchronous job is started by calling the ASYNC_start_job() function. Initially B<*job> should be NULL. B should point to a location where the