taskpool.h File Reference

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	ast_taskpool_options

Macros
#define	AST_TASKPOOL_OPTIONS_VERSION   1
#define	ast_taskpool_push(pool, task, data)    __ast_taskpool_push(pool, task, data, __FILE__, __LINE__, __PRETTY_FUNCTION__)
#define	ast_taskpool_push_wait(pool, task, data)    __ast_taskpool_push_wait(pool, task, data, __FILE__, __LINE__, __PRETTY_FUNCTION__)
#define	ast_taskpool_serializer_push_wait(pool, task, data)    __ast_taskpool_serializer_push_wait(pool, task, data, __FILE__, __LINE__, __PRETTY_FUNCTION__)

Enumerations
enum	ast_taskpool_selector { AST_TASKPOOL_SELECTOR_DEFAULT = 0 , AST_TASKPOOL_SELECTOR_LEAST_FULL , AST_TASKPOOL_SELECTOR_SEQUENTIAL }
	Selectors for choosing which taskprocessor in a pool to use. More...

Functions
int	__ast_taskpool_push (struct ast_taskpool *pool, int(*task)(void *data), void *data, const char *file, int line, const char *function) attribute_warn_unused_result
	Push a task to the taskpool.
int	__ast_taskpool_push_wait (struct ast_taskpool *pool, int(*task)(void *data), void *data, const char *file, int line, const char *function) attribute_warn_unused_result
	Push a task to the taskpool, and wait for completion.
int	__ast_taskpool_serializer_push_wait (struct ast_taskprocessor *serializer, int(*task)(void *data), void *data, const char *file, int line, const char *function) attribute_warn_unused_result
	Push a task to a serializer, and wait for completion.
struct ast_taskpool *	ast_taskpool_create (const char *name, const struct ast_taskpool_options *options)
	Create a new taskpool.
long	ast_taskpool_queue_size (struct ast_taskpool *pool)
	Get the current number of queued tasks in the taskpool.
struct ast_taskprocessor *	ast_taskpool_serializer (const char *name, struct ast_taskpool *pool)
	Serialized execution of tasks within a ast_taskpool.
struct ast_taskprocessor *	ast_taskpool_serializer_get_current (void)
	Get the taskpool serializer currently associated with this thread.
struct ast_taskprocessor *	ast_taskpool_serializer_group (const char *name, struct ast_taskpool *pool, struct ast_serializer_shutdown_group *shutdown_group)
	Serialized execution of tasks within a ast_taskpool.
int	ast_taskpool_serializer_suspend (struct ast_taskprocessor *serializer)
	Suspend a serializer, causing tasks to be queued until unsuspended.
int	ast_taskpool_serializer_unsuspend (struct ast_taskprocessor *serializer)
	Unsuspend a serializer, causing tasks to be executed.
void	ast_taskpool_shutdown (struct ast_taskpool *pool)
	Shut down a taskpool and remove the underlying taskprocessors.
size_t	ast_taskpool_taskprocessors_count (struct ast_taskpool *pool)
	Get the current number of taskprocessors in the taskpool.

Detailed Description

API providing queued task execution across threads.

Definition in file taskpool.h.

Macro Definition Documentation

AST_TASKPOOL_OPTIONS_VERSION

#define AST_TASKPOOL_OPTIONS_VERSION   1

Definition at line 76 of file taskpool.h.

ast_taskpool_push

#define ast_taskpool_push	(		pool,
			task,
			data
	)		__ast_taskpool_push(pool, task, data, __FILE__, __LINE__, __PRETTY_FUNCTION__)

Definition at line 210 of file taskpool.h.

ast_taskpool_push_wait

#define ast_taskpool_push_wait	(		pool,
			task,
			data
	)		__ast_taskpool_push_wait(pool, task, data, __FILE__, __LINE__, __PRETTY_FUNCTION__)

Definition at line 230 of file taskpool.h.

ast_taskpool_serializer_push_wait

#define ast_taskpool_serializer_push_wait	(		pool,
			task,
			data
	)		__ast_taskpool_serializer_push_wait(pool, task, data, __FILE__, __LINE__, __PRETTY_FUNCTION__)

Definition at line 335 of file taskpool.h.

Enumeration Type Documentation

ast_taskpool_selector

enum ast_taskpool_selector

Selectors for choosing which taskprocessor in a pool to use.

Enumerator
AST_TASKPOOL_SELECTOR_DEFAULT
AST_TASKPOOL_SELECTOR_LEAST_FULL
AST_TASKPOOL_SELECTOR_SEQUENTIAL

Definition at line 69 of file taskpool.h.

                           {
    AST_TASKPOOL_SELECTOR_DEFAULT = 0, /* The selector that is generally the best for most use cases */
    AST_TASKPOOL_SELECTOR_LEAST_FULL,  /* Select the least full taskprocessor */
    AST_TASKPOOL_SELECTOR_SEQUENTIAL,  /* Select taskprocessors in a sequential manner */
};

Function Documentation

__ast_taskpool_push()

int __ast_taskpool_push	(	struct ast_taskpool *	pool,
		int(*)(void *data)	task,
		void *	data,
		const char *	file,
		int	line,
		const char *	function
	)

Push a task to the taskpool.

Since

23.1.0

22.7.0

20.17.0

Tasks pushed into the taskpool will be automatically taken by one of the taskprocessors within

Parameters

pool	The taskpool to add the task to
task	The task to add
data	The parameter for the task

Return values

0	success
-1	failure

Definition at line 544 of file taskpool.c.

{
    RAII_VAR(struct taskpool_taskprocessor *, taskprocessor, NULL, ao2_cleanup);
 
    /* Select the taskprocessor in the pool to use for pushing this task */
    ao2_lock(pool);
    if (!pool->shutting_down) {
        unsigned int growth_threshold_reached = 0;
 
        /* A selector doesn't set taskprocessor to NULL, it will only change the value if a better
         * taskprocessor is found. This means that even if the selector for a dynamic taskprocessor
         * fails for some reason, it will still fall back to the initially found static one if
         * it is present.
         */
        pool->selector(pool, &pool->static_taskprocessors, &taskprocessor, &growth_threshold_reached);
        if (pool->options.auto_increment && growth_threshold_reached) {
            /* If we need to grow then try dynamic taskprocessors */
            pool->selector(pool, &pool->dynamic_taskprocessors, &taskprocessor, &growth_threshold_reached);
            if (growth_threshold_reached) {
                /* If we STILL need to grow then grow the dynamic taskprocessor pool if allowed */
                taskpool_dynamic_pool_grow(pool, &taskprocessor);
            }
 
            /* If a dynamic taskprocessor was used update its last push time */
            if (taskprocessor) {
                taskprocessor->last_pushed = ast_tvnow();
            }
        }
        ao2_bump(taskprocessor);
    }
    ao2_unlock(pool);
 
    if (!taskprocessor) {
        return -1;
    }
 
    if (__ast_taskprocessor_push(taskprocessor->taskprocessor, task, data, file, line, function)) {
        return -1;
    }
 
    return 0;
}

References __ast_taskprocessor_push(), ao2_bump, ao2_cleanup, ao2_lock, ao2_unlock, ast_tvnow(), ast_taskpool_options::auto_increment, ast_taskpool::dynamic_taskprocessors, NULL, ast_taskpool::options, RAII_VAR, ast_taskpool::selector, ast_taskpool::shutting_down, ast_taskpool::static_taskprocessors, task(), taskpool_dynamic_pool_grow(), and taskpool_taskprocessor::taskprocessor.

Referenced by __ast_sip_push_task(), __ast_taskpool_push_wait(), and ast_taskpool_push().

__ast_taskpool_push_wait()

int __ast_taskpool_push_wait	(	struct ast_taskpool *	pool,
		int(*)(void *data)	task,
		void *	data,
		const char *	file,
		int	line,
		const char *	function
	)

Push a task to the taskpool, and wait for completion.

Since

23.1.0

22.7.0

20.17.0

Tasks pushed into the taskpool will be automatically taken by one of the taskprocessors within

Parameters

pool	The taskpool to add the task to
task	The task to add
data	The parameter for the task

Return values

0	success
-1	failure

Definition at line 652 of file taskpool.c.

{
    struct taskpool_sync_task sync_task;
 
    /* If we are already executing within a taskpool taskprocessor then
     * don't bother pushing a new task, just directly execute the task.
     */
    if (ast_taskpool_get_current()) {
        return task(data);
    }
 
    if (taskpool_sync_task_init(&sync_task, task, data)) {
        return -1;
    }
 
    if (__ast_taskpool_push(pool, taskpool_sync_task, &sync_task, file, line, function)) {
        taskpool_sync_task_cleanup(&sync_task);
        return -1;
    }
 
    ast_mutex_lock(&sync_task.lock);
    while (!sync_task.complete) {
        ast_cond_wait(&sync_task.cond, &sync_task.lock);
    }
    ast_mutex_unlock(&sync_task.lock);
 
    taskpool_sync_task_cleanup(&sync_task);
    return sync_task.fail;
}

References __ast_taskpool_push(), ast_cond_wait, ast_mutex_lock, ast_mutex_unlock, ast_taskpool_get_current(), taskpool_sync_task::complete, taskpool_sync_task::cond, taskpool_sync_task::fail, taskpool_sync_task::lock, task(), taskpool_sync_task_cleanup(), and taskpool_sync_task_init().

Referenced by __ast_sip_push_task_wait(), __ast_sip_push_task_wait_serializer(), and ast_taskpool_push_wait().

__ast_taskpool_serializer_push_wait()

int __ast_taskpool_serializer_push_wait	(	struct ast_taskprocessor *	serializer,
		int(*)(void *data)	task,
		void *	data,
		const char *	file,
		int	line,
		const char *	function
	)

Push a task to a serializer, and wait for completion.

Since

23.1.0

22.7.0

20.17.0

Parameters

serializer	The serializer to add the task to
task	The task to add
data	The parameter for the task

Return values

0	success
-1	failure

Definition at line 899 of file taskpool.c.

{
    struct ast_taskprocessor_listener *listener = ast_taskprocessor_listener(serializer);
    struct serializer *ser = ast_taskprocessor_listener_get_user_data(listener);
    struct ast_taskprocessor *prior_serializer;
    struct taskpool_sync_task sync_task;
 
    /* If not in a taskpool taskprocessor we can just queue the task like normal and
     * wait. */
    if (!ast_taskpool_get_current()) {
        if (taskpool_sync_task_init(&sync_task, task, data)) {
            return -1;
        }
 
        if (__ast_taskprocessor_push(serializer, taskpool_sync_task, &sync_task, file, line, function)) {
            taskpool_sync_task_cleanup(&sync_task);
            return -1;
        }
 
        ast_mutex_lock(&sync_task.lock);
        while (!sync_task.complete) {
            ast_cond_wait(&sync_task.cond, &sync_task.lock);
        }
        ast_mutex_unlock(&sync_task.lock);
 
        taskpool_sync_task_cleanup(&sync_task);
        return sync_task.fail;
    }
 
    /* It is possible that we are already executing within a serializer, so stash the existing
     * away so we can restore it.
     */
    prior_serializer = ast_taskpool_serializer_get_current();
 
    ao2_lock(ser);
 
    /* There are two cases where we can or have to directly execute this task:
     * 1. There are no other tasks in the serializer
     * 2. We are already in the serializer
     * In the second case if we don't execute the task now, we will deadlock waiting
     * on it as it will never occur.
     */
    if (!ast_taskprocessor_size(serializer) || prior_serializer == serializer) {
        ast_threadstorage_set_ptr(&current_taskpool_serializer, serializer);
        sync_task.fail = task(data);
        ao2_unlock(ser);
        ast_threadstorage_set_ptr(&current_taskpool_serializer, prior_serializer);
        return sync_task.fail;
    }
 
    if (taskpool_sync_task_init(&sync_task, task, data)) {
        ao2_unlock(ser);
        return -1;
    }
 
    /* First we queue the serialized task */
    if (__ast_taskprocessor_push(serializer, taskpool_sync_task, &sync_task, file, line, function)) {
        taskpool_sync_task_cleanup(&sync_task);
        ao2_unlock(ser);
        return -1;
    }
 
    /* Next we queue the empty task to ensure the serializer doesn't reach empty, this
     * stops two tasks from being queued for the same serializer at the same time.
     */
    if (ast_taskprocessor_push(serializer, taskpool_serializer_empty_task, NULL)) {
        taskpool_sync_task_cleanup(&sync_task);
        ao2_unlock(ser);
        return -1;
    }
 
    /* Now we execute the tasks on the serializer until our sync task is complete */
    ast_threadstorage_set_ptr(&current_taskpool_serializer, serializer);
    while (!sync_task.complete) {
        /* If the serializer is suspended wait until it unsuspends */
        while (ser->suspended == SERIALIZER_SUSPENDED) {
            ast_cond_wait(&ser->cond,  ao2_object_get_lockaddr(ser));
        }
 
        /* The sync task is guaranteed to be executed, so doing a while loop on the complete
         * flag is safe.
         */
        ast_taskprocessor_execute(serializer);
    }
    taskpool_sync_task_cleanup(&sync_task);
    ao2_unlock(ser);
 
    ast_threadstorage_set_ptr(&current_taskpool_serializer, prior_serializer);
 
    return sync_task.fail;
}

References __ast_taskprocessor_push(), ao2_lock, ao2_object_get_lockaddr(), ao2_unlock, ast_cond_wait, ast_mutex_lock, ast_mutex_unlock, ast_taskpool_get_current(), ast_taskpool_serializer_get_current(), ast_taskprocessor_execute(), ast_taskprocessor_listener_get_user_data(), ast_taskprocessor_push, ast_taskprocessor_size(), ast_threadstorage_set_ptr(), taskpool_sync_task::complete, taskpool_sync_task::cond, serializer::cond, taskpool_sync_task::fail, listener(), taskpool_sync_task::lock, NULL, SERIALIZER_SUSPENDED, serializer::suspended, task(), taskpool_serializer_empty_task(), taskpool_sync_task_cleanup(), and taskpool_sync_task_init().

Referenced by __ast_sip_push_task_wait(), __ast_sip_push_task_wait_serializer(), and ast_taskpool_serializer_push_wait().

ast_taskpool_create()

struct ast_taskpool * ast_taskpool_create	(	const char *	name,
		const struct ast_taskpool_options *	options
	)

Create a new taskpool.

Since

23.1.0

22.7.0

20.17.0

This function creates a taskpool. Tasks may be pushed onto this task pool and will be automatically acted upon by taskprocessors within the pool.

Only a single taskpool with a given name may exist. This function will fail if a taskpool with the given name already exists.

Parameters

name	The unique name for the taskpool
options	The behavioral options for this taskpool

Return values

NULL	Failed to create the taskpool
non-NULL	The newly-created taskpool

Note

The ast_taskpool_shutdown function must be called to shut down the taskpool and clean up underlying resources fully.

Definition at line 341 of file taskpool.c.

{
    struct ast_taskpool *pool;
 
    /* Enforce versioning on the passed-in options */
    if (options->version != AST_TASKPOOL_OPTIONS_VERSION) {
        return NULL;
    }
 
    pool = ao2_alloc(sizeof(*pool) + strlen(name) + 1, NULL);
    if (!pool) {
        return NULL;
    }
 
    strcpy(pool->name, name); /* Safe */
    memcpy(&pool->options, options, sizeof(pool->options));
    pool->shrink_sched_id = -1;
 
    /* Verify the passed-in options are valid, and adjust if needed */
    if (options->initial_size < options->minimum_size) {
        pool->options.initial_size = options->minimum_size;
        ast_log(LOG_WARNING, "Taskpool '%s' has an initial size of %d, which is less than the minimum size of %d. Adjusting to %d.\n",
            name, options->initial_size, options->minimum_size, options->minimum_size);
    }
 
    if (options->max_size && pool->options.initial_size > options->max_size) {
        pool->options.max_size = pool->options.initial_size;
        ast_log(LOG_WARNING, "Taskpool '%s' has a max size of %d, which is less than the initial size of %d. Adjusting to %d.\n",
            name, options->max_size, pool->options.initial_size, pool->options.initial_size);
    }
 
    if (!options->auto_increment) {
        if (!pool->options.minimum_size) {
            pool->options.minimum_size = 1;
            ast_log(LOG_WARNING, "Taskpool '%s' has a minimum size of 0, which is not valid without auto increment. Adjusting to 1.\n", name);
        }
        if (!pool->options.max_size) {
            pool->options.max_size = pool->options.minimum_size;
            ast_log(LOG_WARNING, "Taskpool '%s' has a max size of 0, which is not valid without auto increment. Adjusting to %d.\n", name, pool->options.minimum_size);
        }
        if (pool->options.minimum_size != pool->options.max_size) {
            pool->options.minimum_size = pool->options.max_size;
            pool->options.initial_size = pool->options.max_size;
            ast_log(LOG_WARNING, "Taskpool '%s' has a minimum size of %d, while max size is %d. Adjusting all sizes to %d due to lack of auto increment.\n",
                name, options->minimum_size, pool->options.max_size, pool->options.max_size);
        }
    } else if (!options->growth_threshold) {
        pool->options.growth_threshold = TASKPOOL_GROW_THRESHOLD;
    }
 
    if (options->selector == AST_TASKPOOL_SELECTOR_DEFAULT || options->selector == AST_TASKPOOL_SELECTOR_LEAST_FULL) {
        pool->selector = taskpool_least_full_selector;
    } else if (options->selector == AST_TASKPOOL_SELECTOR_SEQUENTIAL) {
        pool->selector = taskpool_sequential_selector;
    } else {
        ast_log(LOG_WARNING, "Taskpool '%s' has an invalid selector of %d. Adjusting to default selector.\n",
            name, options->selector);
        pool->selector = taskpool_least_full_selector;
    }
 
    if (taskpool_taskprocessors_init(&pool->static_taskprocessors, pool->options.minimum_size)) {
        ao2_ref(pool, -1);
        return NULL;
    }
 
    /* Create the static taskprocessors based on the passed-in options */
    for (int i = 0; i < pool->options.minimum_size; i++) {
        struct taskpool_taskprocessor *taskprocessor;
 
        taskprocessor = taskpool_taskprocessor_alloc(pool, 's');
        if (!taskprocessor) {
            /* The reference to pool is passed to ast_taskpool_shutdown */
            ast_taskpool_shutdown(pool);
            return NULL;
        }
 
        if (AST_VECTOR_APPEND(&pool->static_taskprocessors.taskprocessors, taskprocessor)) {
            ao2_ref(taskprocessor, -1);
            /* The reference to pool is passed to ast_taskpool_shutdown */
            ast_taskpool_shutdown(pool);
            return NULL;
        }
    }
 
    if (taskpool_taskprocessors_init(&pool->dynamic_taskprocessors,
        pool->options.initial_size - pool->options.minimum_size)) {
        ast_taskpool_shutdown(pool);
        return NULL;
    }
 
    /* Create the dynamic taskprocessor based on the passed-in options */
    for (int i = 0; i < (pool->options.initial_size - pool->options.minimum_size); i++) {
        struct taskpool_taskprocessor *taskprocessor;
 
        taskprocessor = taskpool_taskprocessor_alloc(pool, 'd');
        if (!taskprocessor) {
            /* The reference to pool is passed to ast_taskpool_shutdown */
            ast_taskpool_shutdown(pool);
            return NULL;
        }
 
        if (AST_VECTOR_APPEND(&pool->dynamic_taskprocessors.taskprocessors, taskprocessor)) {
            ao2_ref(taskprocessor, -1);
            /* The reference to pool is passed to ast_taskpool_shutdown */
            ast_taskpool_shutdown(pool);
            return NULL;
        }
    }
 
    /* If idle timeout support is enabled kick off a scheduled task to shrink the dynamic pool periodically, we do
     * this no matter if there are dynamic taskprocessor present to reduce the work needed within the push function
     * and to reduce complexity.
     */
    if (options->idle_timeout && options->auto_increment) {
        pool->shrink_sched_id = ast_sched_add(sched, options->idle_timeout * 1000, taskpool_dynamic_pool_shrink, ao2_bump(pool));
        if (pool->shrink_sched_id < 0) {
            ao2_ref(pool, -1);
            /* The second reference to pool is passed to ast_taskpool_shutdown */
            ast_taskpool_shutdown(pool);
            return NULL;
        }
    }
 
    return pool;
}

References ao2_alloc, ao2_bump, ao2_ref, ast_log, ast_sched_add(), AST_TASKPOOL_OPTIONS_VERSION, AST_TASKPOOL_SELECTOR_DEFAULT, AST_TASKPOOL_SELECTOR_LEAST_FULL, AST_TASKPOOL_SELECTOR_SEQUENTIAL, ast_taskpool_shutdown(), AST_VECTOR_APPEND, ast_taskpool::dynamic_taskprocessors, ast_taskpool_options::growth_threshold, ast_taskpool_options::initial_size, LOG_WARNING, ast_taskpool_options::max_size, ast_taskpool_options::minimum_size, ast_taskpool::name, name, NULL, ast_taskpool::options, options, ast_taskpool::selector, ast_taskpool::shrink_sched_id, ast_taskpool::static_taskprocessors, taskpool_dynamic_pool_shrink(), TASKPOOL_GROW_THRESHOLD, taskpool_least_full_selector(), taskpool_sequential_selector(), taskpool_taskprocessor_alloc(), taskpool_taskprocessors_init(), taskpool_taskprocessor::taskprocessor, and taskpool_taskprocessors::taskprocessors.

Referenced by ast_sorcery_init(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), handle_cli_taskpool_push_efficiency(), handle_cli_taskpool_push_serializer_efficiency(), load_module(), sel_run_case(), and stasis_init().

ast_taskpool_queue_size()

long ast_taskpool_queue_size

(

struct ast_taskpool *

pool

)

Get the current number of queued tasks in the taskpool.

Since

23.1.0

22.7.0

20.17.0

Parameters

pool	The taskpool to query

Return values

The	number of queued tasks in the taskpool

Definition at line 481 of file taskpool.c.

{
    long queue_size = 0;
 
    ao2_lock(pool);
    AST_VECTOR_CALLBACK_VOID(&pool->static_taskprocessors.taskprocessors, TASKPOOL_QUEUE_SIZE_ADD, queue_size);
    AST_VECTOR_CALLBACK_VOID(&pool->dynamic_taskprocessors.taskprocessors, TASKPOOL_QUEUE_SIZE_ADD, queue_size);
    ao2_unlock(pool);
 
    return queue_size;
}

References ao2_lock, ao2_unlock, AST_VECTOR_CALLBACK_VOID, ast_taskpool::dynamic_taskprocessors, ast_taskpool::static_taskprocessors, TASKPOOL_QUEUE_SIZE_ADD, and taskpool_taskprocessors::taskprocessors.

Referenced by ast_sip_taskpool_queue_size().

ast_taskpool_serializer()

struct ast_taskprocessor * ast_taskpool_serializer	(	const char *	name,
		struct ast_taskpool *	pool
	)

Serialized execution of tasks within a ast_taskpool.

Since

23.1.0

22.7.0

20.17.0

A ast_taskprocessor with the same contract as a default taskprocessor (tasks execute serially) except instead of executing out of a dedicated thread, execution occurs in a taskprocessor from a ast_taskpool.

While it guarantees that each task will complete before executing the next, there is no guarantee as to which thread from the pool individual tasks will execute. This normally only matters if your code relies on thread specific information, such as thread locals.

Use ast_taskprocessor_unreference() to dispose of the returned ast_taskprocessor.

Only a single taskprocessor with a given name may exist. This function will fail if a taskprocessor with the given name already exists.

Parameters

name	Name of the serializer. (must be unique)
pool	ast_taskpool for execution.

Returns

ast_taskprocessor for enqueuing work.

Return values

NULL

on error.

Definition at line 877 of file taskpool.c.

{
    return ast_taskpool_serializer_group(name, pool, NULL);
}

References ast_taskpool_serializer_group(), name, and NULL.

Referenced by AST_TEST_DEFINE(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), handle_cli_taskpool_push_serializer_efficiency(), internal_stasis_subscribe(), sel_run_case(), and sorcery_object_type_alloc().

ast_taskpool_serializer_get_current()

struct ast_taskprocessor * ast_taskpool_serializer_get_current

(

void

)

Get the taskpool serializer currently associated with this thread.

Note

The returned pointer is valid while the serializer thread is running.

Use ao2_ref() on serializer if you are going to keep it for another thread. To unref it you must then use ast_taskprocessor_unreference().

Return values

serializer	on success.
NULL	on error or no serializer associated with the thread.

Definition at line 842 of file taskpool.c.

{
    return ast_threadstorage_get_ptr(&current_taskpool_serializer);
}

References ast_threadstorage_get_ptr().

Referenced by __ast_taskpool_serializer_push_wait(), record_serializer(), requeue_task(), rfc3326_outgoing_request(), rfc3326_outgoing_response(), serializer_efficiency_task(), and simple_task().

ast_taskpool_serializer_group()

struct ast_taskprocessor * ast_taskpool_serializer_group	(	const char *	name,
		struct ast_taskpool *	pool,
		struct ast_serializer_shutdown_group *	shutdown_group
	)

Serialized execution of tasks within a ast_taskpool.

Since

23.1.0

22.7.0

20.17.0

A ast_taskprocessor with the same contract as a default taskprocessor (tasks execute serially) except instead of executing out of a dedicated thread, execution occurs in a taskprocessor from a ast_taskpool.

While it guarantees that each task will complete before executing the next, there is no guarantee as to which thread from the pool individual tasks will execute. This normally only matters if your code relies on thread specific information, such as thread locals.

Use ast_taskprocessor_unreference() to dispose of the returned ast_taskprocessor.

Only a single taskprocessor with a given name may exist. This function will fail if a taskprocessor with the given name already exists.

Parameters

name	Name of the serializer. (must be unique)
pool	ast_taskpool for execution.
shutdown_group	Group shutdown controller. (NULL if no group association)

Returns

ast_taskprocessor for enqueuing work.

Return values

NULL

on error.

Definition at line 847 of file taskpool.c.

{
    struct serializer *ser;
    struct ast_taskprocessor_listener *listener;
    struct ast_taskprocessor *tps;
 
    ser = serializer_create(pool, shutdown_group);
    if (!ser) {
        return NULL;
    }
 
    listener = ast_taskprocessor_listener_alloc(&serializer_tps_listener_callbacks, ser);
    if (!listener) {
        ao2_ref(ser, -1);
        return NULL;
    }
 
    tps = ast_taskprocessor_create_with_listener(name, listener);
    if (!tps) {
        /* ser ref transferred to listener but not cleaned without tps */
        ao2_ref(ser, -1);
    } else if (shutdown_group) {
        ast_serializer_shutdown_group_inc(shutdown_group);
    }
 
    ao2_ref(listener, -1);
    return tps;
}

References ao2_ref, ast_serializer_shutdown_group_inc(), ast_taskprocessor_create_with_listener(), ast_taskprocessor_listener_alloc(), listener(), name, NULL, serializer_create(), serializer_tps_listener_callbacks, and shutdown_group.

Referenced by ast_serializer_taskpool_create(), ast_sip_create_serializer_group(), and ast_taskpool_serializer().

ast_taskpool_serializer_suspend()

int ast_taskpool_serializer_suspend

(

struct ast_taskprocessor *

serializer

)

Suspend a serializer, causing tasks to be queued until unsuspended.

Since

23.2.0

22.8.0

20.18.0

Parameters

serializer

The serializer to suspend

Return values

0	success
-1	failure

Note

May only be invoked from outside of the taskpool

Definition at line 1018 of file taskpool.c.

{
    struct ast_taskprocessor_listener *listener = ast_taskprocessor_listener(serializer);
    struct serializer *ser = ast_taskprocessor_listener_get_user_data(listener);
 
    /* This suspension process works by inserting a checkpoint into the queue of the
     * serializer. Once this checkpoint is reached the taskpool taskprocessor handling
     * the queue stops prematurely and does not get requeued. For the case where a
     * synchronous task wait is in progress it is instead paused temporarily. Once
     * the serializer is unsuspended a new execution task is queued into the taskpool
     * to resume execution and any paused synchronous task waits are awoken to resume
     * their own execution as well. This approach minimizes the number of threads that
     * are paused waiting, nominally to 0.
     */
 
    if (ast_taskpool_get_current()) {
        return -1;
    }
 
    ao2_lock(ser);
 
    /* If the serializer is already suspending or suspended, just return immediately.
     * This mirrors the original behavior from PJSIP.
     */
    if (ser->suspended != SERIALIZER_UNSUSPENDED) {
        ao2_unlock(ser);
        return 0;
    }
 
    ser->suspended = SERIALIZER_SUSPENDING;
 
    ao2_unlock(ser);
 
    /* Once this returns successfully there is no thread executing the tasks on the serializer,
     * so they will accumulate until the serializer is unsuspended.
     */
    if (ast_taskpool_serializer_push_wait(serializer, taskpool_serializer_suspend_task, serializer)) {
        /* Suspension failed, so unsuspend as doing otherwise would leave the serializer in a stuck
         * state.
         */
        ao2_lock(ser);
        ser->suspended = SERIALIZER_UNSUSPENDED;
        ao2_unlock(ser);
        return -1;
    }
 
    return 0;
}

References ao2_lock, ao2_unlock, ast_taskpool_get_current(), ast_taskpool_serializer_push_wait, ast_taskprocessor_listener_get_user_data(), listener(), SERIALIZER_SUSPENDING, SERIALIZER_UNSUSPENDED, serializer::suspended, and taskpool_serializer_suspend_task().

Referenced by ast_sip_session_suspend(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), and AST_TEST_DEFINE().

ast_taskpool_serializer_unsuspend()

int ast_taskpool_serializer_unsuspend

(

struct ast_taskprocessor *

serializer

)

Unsuspend a serializer, causing tasks to be executed.

Since

23.2.0

22.8.0

20.18.0

Parameters

serializer

The serializer to unsuspend

Return values

0	success
-1	failure

Note

May only be invoked from outside of the taskpool

Definition at line 1067 of file taskpool.c.

{
    struct ast_taskprocessor_listener *listener = ast_taskprocessor_listener(serializer);
    struct serializer *ser = ast_taskprocessor_listener_get_user_data(listener);
 
    if (ast_taskpool_get_current()) {
        return -1;
    }
 
    ao2_lock(ser);
 
    if (ser->suspended != SERIALIZER_SUSPENDED) {
        ao2_unlock(ser);
        return 0;
    }
 
    ser->suspended = SERIALIZER_UNSUSPENDED;
 
    /* Notify any other interested threads that this one has awoken */
    ast_cond_broadcast(&ser->cond);
 
    /* And now we kick off handling of the queued tasks once again */
    if (ast_taskpool_push(ser->pool, execute_tasks, ao2_bump(serializer))) {
        ast_taskprocessor_unreference(serializer);
    }
 
    ao2_unlock(ser);
 
    return 0;
}

References ao2_bump, ao2_lock, ao2_unlock, ast_cond_broadcast, ast_taskpool_get_current(), ast_taskpool_push, ast_taskprocessor_listener_get_user_data(), ast_taskprocessor_unreference(), serializer::cond, execute_tasks(), listener(), serializer::pool, SERIALIZER_SUSPENDED, SERIALIZER_UNSUSPENDED, and serializer::suspended.

Referenced by ast_sip_session_unsuspend(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), and AST_TEST_DEFINE().

ast_taskpool_shutdown()

void ast_taskpool_shutdown

(

struct ast_taskpool *

pool

)

Shut down a taskpool and remove the underlying taskprocessors.

Since

23.1.0

22.7.0

20.17.0

Parameters

pool	The pool to shut down

Note

This will decrement the reference to the pool

Definition at line 692 of file taskpool.c.

{
    if (!pool) {
        return;
    }
 
    /* Mark this pool as shutting down so nothing new is pushed */
    ao2_lock(pool);
    pool->shutting_down = 1;
    ao2_unlock(pool);
 
    /* Stop the shrink scheduled item if present */
    AST_SCHED_DEL_UNREF(sched, pool->shrink_sched_id, ao2_ref(pool, -1));
 
    /* Clean up all the taskprocessors */
    taskpool_taskprocessors_cleanup(&pool->static_taskprocessors);
    taskpool_taskprocessors_cleanup(&pool->dynamic_taskprocessors);
 
    ao2_ref(pool, -1);
}

References ao2_lock, ao2_ref, ao2_unlock, AST_SCHED_DEL_UNREF, ast_taskpool::dynamic_taskprocessors, ast_taskpool::shrink_sched_id, ast_taskpool::shutting_down, ast_taskpool::static_taskprocessors, and taskpool_taskprocessors_cleanup().

Referenced by ast_taskpool_create(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), handle_cli_taskpool_push_efficiency(), handle_cli_taskpool_push_serializer_efficiency(), load_module(), sel_run_case(), sorcery_cleanup(), stasis_cleanup(), and unload_module().

ast_taskpool_taskprocessors_count()

size_t ast_taskpool_taskprocessors_count

(

struct ast_taskpool *

pool

)

Get the current number of taskprocessors in the taskpool.

Since

23.1.0

22.7.0

20.17.0

Parameters

pool	The taskpool to query

Return values

The	number of taskprocessors in the taskpool

Definition at line 468 of file taskpool.c.

{
    size_t count;
 
    ao2_lock(pool);
    count = AST_VECTOR_SIZE(&pool->static_taskprocessors.taskprocessors) + AST_VECTOR_SIZE(&pool->dynamic_taskprocessors.taskprocessors);
    ao2_unlock(pool);
 
    return count;
}

References ao2_lock, ao2_unlock, AST_VECTOR_SIZE, ast_taskpool::dynamic_taskprocessors, ast_taskpool::static_taskprocessors, and taskpool_taskprocessors::taskprocessors.

Referenced by AST_TEST_DEFINE(), and AST_TEST_DEFINE().