Commit e74c4bb0 authored by Éric Thiébaut's avatar Éric Thiébaut
Browse files

Normalize API names for thread-pools

parent 2bef73d0
......@@ -26,35 +26,35 @@ TAO_BEGIN_DECLS
* TAO Library provides minimalist thread-pools which are managed by
* only 4 functions:
*
* - tao_create_threadpool() to create a new thread-pool,
* - tao_push_threadpool_job() to push a new job to the end of the job queue
* - tao_threadpool_create() to create a new thread-pool,
* - tao_threadpool_push_job() to push a new job to the end of the job queue
* of a thread-pool,
* - tao_wait_threadpool() to wait for completion of all jobs,
* - tao_destroy_threadpool() to eventually destroy a thread-pool.
* - tao_threadpool_wait() to wait for completion of all jobs,
* - tao_threadpool_destroy() to eventually destroy a thread-pool.
*
* Example of use:
*
* ~~~~~{.c}
* // Create a thread pool of 4 workers.
* tao_threadpool* pool = tao_create_threadpool(4);
* tao_threadpool* pool = tao_threadpool_create(4);
*
* // Push a bunch of jobs and then wait for all jobs to complete.
* tao_push_threadpool_job(pool, func1, arg1);
* tao_push_threadpool_job(pool, func2, arg2);
* tao_threadpool_push_job(pool, func1, arg1);
* tao_threadpool_push_job(pool, func2, arg2);
* ...
* tao_push_threadpool_job(pool, funcN, argN);
* tao_wait_threadpool(pool);
* tao_threadpool_push_job(pool, funcN, argN);
* tao_threadpool_wait(pool);
*
* // Push another bunch of jobs and then wait for all jobs to complete.
* tao_push_threadpool_job(pool, otherfunc1, otherarg1);
* tao_push_threadpool_job(pool, otherfunc2, otherarg2);
* tao_threadpool_push_job(pool, otherfunc1, otherarg1);
* tao_threadpool_push_job(pool, otherfunc2, otherarg2);
* ...
* tao_push_threadpool_job(pool, otherfuncN, otherargN);
* tao_wait_threadpool(pool);
* tao_threadpool_push_job(pool, otherfuncN, otherargN);
* tao_threadpool_wait(pool);
*
* // Destroy the pool when no longer needed (unstarted jobs will be
* // abandoned).
* tao_destroy_threadpool(pool);
* tao_threadpool_destroy(pool);
* ~~~~~
*
* @{
......@@ -74,33 +74,32 @@ typedef struct tao_threadpool_ tao_threadpool;
* @param workers The number of workers (will be at least 2).
*
* @return The address of the thread-pool, `NULL` in case of failure. It is the
* caller's responsibility to call tao_destroy_threadpool() to
* caller's responsibility to call tao_threadpool_destroy() to
* eventually release ressources associated with the thread-pool.
*/
extern tao_threadpool* tao_create_threadpool(
extern tao_threadpool* tao_threadpool_create(
int workers);
/**
* Destroy a thread-pool.
*
* This function destroys a thread-pool releasing all associated
* ressources. Calling this function waits for running jobs to complete.
* Running jobs are completed but unstarted jobs are abandoned.
* This function destroys a thread-pool releasing all associated ressources.
* Calling this function waits for running jobs to complete. Running jobs are
* completed but unstarted jobs are abandoned.
*
* @param pool The address of the thread-pool to destroy.
*/
extern void tao_destroy_threadpool(
extern void tao_threadpool_destroy(
tao_threadpool* pool);
/**
* Push a new job to be executed by a thread-pool.
*
* This function pushes a new job in the queue of pending jobs of a
* thread-pool. Execution of the job is started as soon as possible but
* after previouly pushed jobs have been completed. It is the caller
* responsibility to make sure that the ressources used by the function
* specified to execute the job will remain accessible when this function
* will be executed.
* thread-pool. Execution of the job is started as soon as possible but after
* previouly pushed jobs have been completed. It is the caller responsibility
* to make sure that the ressources used by the function specified to execute
* the job will remain accessible when this function will be executed.
*
* @param pool The address of the thread-pool.
*
......@@ -111,7 +110,7 @@ extern void tao_destroy_threadpool(
* @return @ref TAO_OK is the job has been successfully pushed; @ref TAO_ERROR
* in case of failure.
*/
extern tao_status tao_push_threadpool_job(
extern tao_status tao_threadpool_push_job(
tao_threadpool* pool,
void (*func)(void*),
void* arg);
......@@ -127,7 +126,7 @@ extern tao_status tao_push_threadpool_job(
* @return @ref TAO_OK is the job has been successfully pushed; @ref TAO_ERROR
* in case of failure.
*/
extern tao_status tao_wait_threadpool(
extern tao_status tao_threadpool_wait(
tao_threadpool* pool);
/**
......
......@@ -186,13 +186,13 @@ static double apply_processing(
all_job_data[i].number = (offset + chunk <= number ? chunk :
number - offset);
all_job_data[i].wrk = wrk;
status = tao_push_threadpool_job(pool, run_job, &all_job_data[i]);
status = tao_threadpool_push_job(pool, run_job, &all_job_data[i]);
if (status != TAO_OK) {
fprintf(stderr, "failed to push job (%s)\n", strerror(errno));
exit(1);
}
}
status = tao_wait_threadpool(pool);
status = tao_threadpool_wait(pool);
if (status != TAO_OK) {
fprintf(stderr, "failed to wait jobs (%s)\n", strerror(errno));
exit(1);
......@@ -368,7 +368,7 @@ int main(
r[i] = 1;
}
pool = tao_create_threadpool(workers);
pool = tao_threadpool_create(workers);
if (pool == NULL) {
fprintf(stderr, "failed to create a thread-pool of %ld threads (%s)\n",
workers, strerror(errno));
......@@ -395,7 +395,7 @@ int main(
test_processing(pool, &wrk, chunk, tests, method);
}
tao_destroy_threadpool(pool);
tao_threadpool_destroy(pool);
free(raw);
free(a);
free(b);
......
......@@ -160,7 +160,7 @@ static void finalize(
free((void*)pool);
}
tao_threadpool* tao_create_threadpool(
tao_threadpool* tao_threadpool_create(
int workers)
{
// Allocate and instanciate thread-pool structure.
......@@ -222,7 +222,7 @@ tao_threadpool* tao_create_threadpool(
return NULL;
}
void tao_destroy_threadpool(
void tao_threadpool_destroy(
tao_threadpool* pool)
{
if (pool != NULL) {
......@@ -230,7 +230,7 @@ void tao_destroy_threadpool(
}
}
tao_status tao_wait_threadpool(
tao_status tao_threadpool_wait(
tao_threadpool* pool)
{
tao_status status = TAO_OK;
......@@ -255,7 +255,7 @@ tao_status tao_wait_threadpool(
return status;
}
tao_status tao_push_threadpool_job(
tao_status tao_threadpool_push_job(
tao_threadpool* pool,
void (*func)(void*),
void* arg)
......
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment