PJSIP Threading Model

Typedefs
typedef int(*	ast_sip_task) (void *user_data)

Enumerations
enum	ast_sip_scheduler_task_flags {   AST_SIP_SCHED_TASK_DEFAULTS = (0 << 0) , AST_SIP_SCHED_TASK_FIXED = (0 << 0) , AST_SIP_SCHED_TASK_VARIABLE = (1 << 0) , AST_SIP_SCHED_TASK_ONESHOT = (1 << 6) ,   AST_SIP_SCHED_TASK_DATA_NOT_AO2 = (0 << 1) , AST_SIP_SCHED_TASK_DATA_AO2 = (1 << 1) , AST_SIP_SCHED_TASK_DATA_NO_CLEANUP = (0 << 3) , AST_SIP_SCHED_TASK_DATA_FREE = ( 1 << 3 ) ,   AST_SIP_SCHED_TASK_PERIODIC = (0 << 4) , AST_SIP_SCHED_TASK_DELAY = (1 << 4) , AST_SIP_SCHED_TASK_TRACK = (1 << 5) }
	Task flags for the res_pjsip scheduler. More...

Functions
struct ast_taskprocessor *	ast_sip_create_serializer (const char *name)
	Create a new serializer for SIP tasks. More...
struct ast_taskprocessor *	ast_sip_create_serializer_group (const char *name, struct ast_serializer_shutdown_group *shutdown_group)
	Create a new serializer for SIP tasks. More...
struct ast_sip_endpoint *	ast_sip_dialog_get_endpoint (pjsip_dialog *dlg)
	Get the endpoint associated with this dialog. More...
void	ast_sip_dialog_set_endpoint (pjsip_dialog *dlg, struct ast_sip_endpoint *endpoint)
	Set an endpoint on a SIP dialog so in-dialog requests do not undergo endpoint lookup. More...
void	ast_sip_dialog_set_serializer (pjsip_dialog *dlg, struct ast_taskprocessor *serializer)
	Set a serializer on a SIP dialog so requests and responses are automatically serialized. More...
struct ast_taskprocessor *	ast_sip_get_distributor_serializer (pjsip_rx_data *rdata)
	Determine the distributor serializer for the SIP message. More...
int	ast_sip_push_task (struct ast_taskprocessor *serializer, int(*sip_task)(void *), void *task_data)
	Pushes a task to SIP servants. More...
int	ast_sip_push_task_synchronous (struct ast_taskprocessor *serializer, int(*sip_task)(void *), void *task_data)
	Push a task to SIP servants and wait for it to complete. More...
int	ast_sip_push_task_wait_serializer (struct ast_taskprocessor *serializer, int(*sip_task)(void *), void *task_data)
	Push a task to the serializer and wait for it to complete. More...
int	ast_sip_push_task_wait_servant (struct ast_taskprocessor *serializer, int(*sip_task)(void *), void *task_data)
	Push a task to SIP servants and wait for it to complete. More...
int	ast_sip_sched_is_task_running (struct ast_sip_sched_task *schtd)
	Checks if the task is currently running. More...
int	ast_sip_sched_is_task_running_by_name (const char *name)
	Checks if the task is currently running. More...
int	ast_sip_sched_task_cancel (struct ast_sip_sched_task *schtd)
	Cancels the next invocation of a task. More...
int	ast_sip_sched_task_cancel_by_name (const char *name)
	Cancels the next invocation of a task by name. More...
int	ast_sip_sched_task_get_name (struct ast_sip_sched_task *schtd, char *name, size_t maxlen)
	Gets the task name. More...
int	ast_sip_sched_task_get_next_run (struct ast_sip_sched_task *schtd)
	Gets the number of milliseconds until the next invocation. More...
int	ast_sip_sched_task_get_next_run_by_name (const char *name)
	Gets the number of milliseconds until the next invocation. More...
int	ast_sip_sched_task_get_times (struct ast_sip_sched_task *schtd, struct timeval *when_queued, struct timeval *last_start, struct timeval *last_end)
	Gets the last start and end times of the task. More...
int	ast_sip_sched_task_get_times2 (struct ast_sip_sched_task *schtd, struct timeval *when_queued, struct timeval *last_start, struct timeval *last_end, int *interval, int *time_left, struct timeval *next_start)
	Gets the queued, last start, last_end, time left, interval, next run. More...
int	ast_sip_sched_task_get_times_by_name (const char *name, struct timeval *when_queued, struct timeval *last_start, struct timeval *last_end)
	Gets the last start and end times of the task by name. More...
int	ast_sip_sched_task_get_times_by_name2 (const char *name, struct timeval *when_queued, struct timeval *last_start, struct timeval *last_end, int *interval, int *time_left, struct timeval *next_start)
	Gets the queued, last start, last_end, time left, interval, next run by task name. More...
struct ast_sip_sched_task *	ast_sip_schedule_task (struct ast_taskprocessor *serializer, int interval, ast_sip_task sip_task, const char *name, void *task_data, enum ast_sip_scheduler_task_flags flags)
	Schedule a task to run in the res_pjsip thread pool. More...
int	ast_sip_thread_is_servant (void)
	Determine if the current thread is a SIP servant thread. More...

Detailed Description

PJSIP Threading Model

There are three major types of threads that SIP will have to deal with:

• Asterisk threads
• PJSIP threads
• SIP threadpool threads (a.k.a. "servants")

Asterisk Threads

Asterisk threads are those that originate from outside of SIP but within Asterisk. The most common of these threads are PBX (channel) threads and the autoservice thread. Most interaction with these threads will be through channel technology callbacks. Within these threads, it is fine to handle Asterisk data from outside of SIP, but any handling of SIP data should be left to servants, especially if you wish to call into PJSIP for anything. Asterisk threads are not registered with PJLIB, so attempting to call into PJSIP will cause an assertion to be triggered, thus causing the program to crash.

PJSIP Threads

PJSIP threads are those that originate from handling of PJSIP events, such as an incoming SIP request or response, or a transaction timeout. The role of these threads is to process information as quickly as possible so that the next item on the SIP socket(s) can be serviced. On incoming messages, Asterisk automatically will push the request to a servant thread. When your module callback is called, processing will already be in a servant. However, for other PJSIP events, such as transaction state changes due to timer expirations, your module will be called into from a PJSIP thread. If you are called into from a PJSIP thread, then you should push whatever processing is needed to a servant as soon as possible. You can discern if you are currently in a SIP servant thread using the ast_sip_thread_is_servant function.

Servants

Servants are where the bulk of SIP work should be performed. These threads exist in order to do the work that Asterisk threads and PJSIP threads hand off to them. Servant threads register themselves with PJLIB, meaning that they are capable of calling PJSIP and PJLIB functions if they wish.

Serializer

Tasks are handed off to servant threads using the API call ast_sip_push_task. The first parameter of this call is a serializer. If this pointer is NULL, then the work will be handed off to whatever servant can currently handle the task. If this pointer is non-NULL, then the task will not be executed until previous tasks pushed with the same serializer have completed. For more information on serializers and the benefits they provide, see ast_threadpool_serializer

Scheduler

Some situations require that a task run periodically or at a future time. Normally the ast_sched functionality would be used but ast_sched only uses 1 thread for all tasks and that thread isn't registered with PJLIB and therefore can't do any PJSIP related work.ast_sip_sched uses ast_sched only as a scheduled queue. When a task is ready to run, it's pushed to a Serializer to be invoked asynchronously by a Servant. This ensures that the task is executed in a PJLIB registered thread and allows the ast_sched thread to immediately continue processing the queue. The Serializer used by ast_sip_sched is one of your choosing or a random one from the res_pjsip pool if you don't choose one.

Note

Do not make assumptions about individual threads based on a corresponding serializer. In other words, just because several tasks use the same serializer when being pushed to servants, it does not mean that the same thread is necessarily going to execute those tasks, even though they are all guaranteed to be executed in sequence.

Typedef Documentation

ast_sip_task

typedef int(* ast_sip_task) (void *user_data)

Definition at line 1869 of file res_pjsip.h.

Enumeration Type Documentation

ast_sip_scheduler_task_flags

enum ast_sip_scheduler_task_flags

Task flags for the res_pjsip scheduler.

The default is AST_SIP_SCHED_TASK_FIXED | AST_SIP_SCHED_TASK_DATA_NOT_AO2 | AST_SIP_SCHED_TASK_DATA_NO_CLEANUP | AST_SIP_SCHED_TASK_PERIODIC

Enumerator
AST_SIP_SCHED_TASK_DEFAULTS	The defaults
AST_SIP_SCHED_TASK_FIXED	Run at a fixed interval. Stop scheduling if the callback returns <= 0. Any other value is ignored.
AST_SIP_SCHED_TASK_VARIABLE	Run at a variable interval. Stop scheduling if the callback returns <= 0. Any other return value is used as the new interval.
AST_SIP_SCHED_TASK_ONESHOT	Run just once. Return values are ignored.
AST_SIP_SCHED_TASK_DATA_NOT_AO2	The task data is not an AO2 object.
AST_SIP_SCHED_TASK_DATA_AO2	The task data is an AO2 object. A reference count will be held by the scheduler until after the task has run for the final time (if ever).
AST_SIP_SCHED_TASK_DATA_NO_CLEANUP	Don't take any cleanup action on the data
AST_SIP_SCHED_TASK_DATA_FREE	If AST_SIP_SCHED_TASK_DATA_AO2 is set, decrement the reference count otherwise call ast_free on it.
AST_SIP_SCHED_TASK_PERIODIC	The task is scheduled at multiples of interval. See also Interval
AST_SIP_SCHED_TASK_DELAY	The next invocation of the task is at last finish + interval. See also Interval
AST_SIP_SCHED_TASK_TRACK	The scheduled task's events are tracked in the debug log. Schedule events such as scheduling, running, rescheduling, canceling, and destroying are logged about the task.

Definition at line 2063 of file res_pjsip.h.

                                  {
    /*!
     * The defaults
     */
    AST_SIP_SCHED_TASK_DEFAULTS = (0 << 0),
 
    /*!
     * Run at a fixed interval.
     * Stop scheduling if the callback returns <= 0.
     * Any other value is ignored.
     */
    AST_SIP_SCHED_TASK_FIXED = (0 << 0),
    /*!
     * Run at a variable interval.
     * Stop scheduling if the callback returns <= 0.
     * Any other return value is used as the new interval.
     */
    AST_SIP_SCHED_TASK_VARIABLE = (1 << 0),
 
    /*!
     * Run just once.
     * Return values are ignored.
     */
    AST_SIP_SCHED_TASK_ONESHOT = (1 << 6),
 
    /*!
     * The task data is not an AO2 object.
     */
    AST_SIP_SCHED_TASK_DATA_NOT_AO2 = (0 << 1),
    /*!
     * The task data is an AO2 object.
     * A reference count will be held by the scheduler until
     * after the task has run for the final time (if ever).
     */
    AST_SIP_SCHED_TASK_DATA_AO2 = (1 << 1),
 
    /*!
     * Don't take any cleanup action on the data
     */
    AST_SIP_SCHED_TASK_DATA_NO_CLEANUP = (0 << 3),
    /*!
     * If AST_SIP_SCHED_TASK_DATA_AO2 is set, decrement the reference count
     * otherwise call ast_free on it.
     */
    AST_SIP_SCHED_TASK_DATA_FREE = ( 1 << 3 ),
 
    /*!
     * \brief The task is scheduled at multiples of interval
     * \see Interval
     */
    AST_SIP_SCHED_TASK_PERIODIC = (0 << 4),
    /*!
     * \brief The next invocation of the task is at last finish + interval
     * \see Interval
     */
    AST_SIP_SCHED_TASK_DELAY = (1 << 4),
    /*!
     * \brief The scheduled task's events are tracked in the debug log.
     * \details
     * Schedule events such as scheduling, running, rescheduling, canceling,
     * and destroying are logged about the task.
     */
    AST_SIP_SCHED_TASK_TRACK = (1 << 5),
};

Function Documentation

ast_sip_create_serializer()

struct ast_taskprocessor * ast_sip_create_serializer

(

const char *

name

)

Create a new serializer for SIP tasks.

Since

13.8.0

See ast_threadpool_serializer for more information on serializers. SIP creates serializers so that tasks operating on similar data will run in sequence.

Parameters

name	Name of the serializer. (must be unique)

Return values

NULL	Failure
non-NULL	Newly-created serializer

Definition at line 2094 of file res_pjsip.c.

{
    return ast_sip_create_serializer_group(name, NULL);
}

References ast_sip_create_serializer_group(), name, and NULL.

Referenced by allocate_subscription_tree(), ast_res_pjsip_init_options_handling(), ast_sip_session_alloc(), create_websocket_serializer(), distributor_pool_setup(), load_module(), refer_progress_alloc(), and scheduler().

ast_sip_create_serializer_group()

struct ast_taskprocessor * ast_sip_create_serializer_group	(	const char *	name,
		struct ast_serializer_shutdown_group *	shutdown_group
	)

Create a new serializer for SIP tasks.

Since

13.8.0

See ast_threadpool_serializer for more information on serializers. SIP creates serializers so that tasks operating on similar data will run in sequence.

Parameters

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

Return values

NULL	Failure
non-NULL	Newly-created serializer

Definition at line 2089 of file res_pjsip.c.

{
    return ast_threadpool_serializer_group(name, sip_threadpool, shutdown_group);
}

References ast_threadpool_serializer_group(), name, shutdown_group, and sip_threadpool.

Referenced by ast_sip_create_serializer(), sip_options_aor_alloc(), sip_outbound_publisher_alloc(), and sip_outbound_registration_state_alloc().

ast_sip_dialog_get_endpoint()

struct ast_sip_endpoint * ast_sip_dialog_get_endpoint

(

pjsip_dialog *

dlg

)

Get the endpoint associated with this dialog.

This function increases the refcount of the endpoint by one. Release the reference once you are finished with the endpoint.

Parameters

dlg	The SIP dialog from which to retrieve the endpoint

Return values

NULL	No endpoint associated with this dialog
non-NULL	The endpoint.

Definition at line 319 of file pjsip_distributor.c.

{
    struct distributor_dialog_data *dist;
    struct ast_sip_endpoint *endpoint;
 
    dist = ao2_find(dialog_associations, dlg, OBJ_SEARCH_KEY);
    if (dist) {
        ao2_lock(dist);
        endpoint = ao2_bump(dist->endpoint);
        ao2_unlock(dist);
        ao2_ref(dist, -1);
    } else {
        endpoint = NULL;
    }
    return endpoint;
}

References ao2_bump, ao2_find, ao2_lock, ao2_ref, ao2_unlock, dialog_associations, distributor_dialog_data::endpoint, NULL, and OBJ_SEARCH_KEY.

Referenced by digest_create_request_with_auth(), and refer_client_on_evsub_state().

ast_sip_dialog_set_endpoint()

void ast_sip_dialog_set_endpoint	(	pjsip_dialog *	dlg,
		struct ast_sip_endpoint *	endpoint
	)

Set an endpoint on a SIP dialog so in-dialog requests do not undergo endpoint lookup.

Parameters

dlg	The SIP dialog itself
endpoint	The endpoint that this dialog is communicating with

Definition at line 291 of file pjsip_distributor.c.

{
    struct distributor_dialog_data *dist;
 
    ao2_wrlock(dialog_associations);
    dist = ao2_find(dialog_associations, dlg, OBJ_SEARCH_KEY | OBJ_NOLOCK);
    if (!dist) {
        if (endpoint) {
            dist = ao2_alloc(sizeof(*dist), NULL);
            if (dist) {
                dist->dlg = dlg;
                dist->endpoint = endpoint;
                ao2_link_flags(dialog_associations, dist, OBJ_NOLOCK);
                ao2_ref(dist, -1);
            }
        }
    } else {
        ao2_lock(dist);
        dist->endpoint = endpoint;
        if (!dist->serializer && !dist->endpoint) {
            ao2_unlink_flags(dialog_associations, dist, OBJ_NOLOCK);
        }
        ao2_unlock(dist);
        ao2_ref(dist, -1);
    }
    ao2_unlock(dialog_associations);
}

References ao2_alloc, ao2_find, ao2_link_flags, ao2_lock, ao2_ref, ao2_unlink_flags, ao2_unlock, ao2_wrlock, dialog_associations, distributor_dialog_data::dlg, distributor_dialog_data::endpoint, NULL, OBJ_NOLOCK, OBJ_SEARCH_KEY, and distributor_dialog_data::serializer.

Referenced by ast_sip_session_alloc(), clean_sub_tree(), refer_send(), session_end_completion(), and subscription_setup_dialog().

ast_sip_dialog_set_serializer()

void ast_sip_dialog_set_serializer	(	pjsip_dialog *	dlg,
		struct ast_taskprocessor *	serializer
	)

Set a serializer on a SIP dialog so requests and responses are automatically serialized.

Passing a NULL serializer is a way to remove a serializer from a dialog.

Parameters

dlg	The SIP dialog itself
serializer	The serializer to use

Definition at line 263 of file pjsip_distributor.c.

{
    struct distributor_dialog_data *dist;
 
    ao2_wrlock(dialog_associations);
    dist = ao2_find(dialog_associations, dlg, OBJ_SEARCH_KEY | OBJ_NOLOCK);
    if (!dist) {
        if (serializer) {
            dist = ao2_alloc(sizeof(*dist), NULL);
            if (dist) {
                dist->dlg = dlg;
                dist->serializer = serializer;
                ao2_link_flags(dialog_associations, dist, OBJ_NOLOCK);
                ao2_ref(dist, -1);
            }
        }
    } else {
        ao2_lock(dist);
        dist->serializer = serializer;
        if (!dist->serializer && !dist->endpoint) {
            ao2_unlink_flags(dialog_associations, dist, OBJ_NOLOCK);
        }
        ao2_unlock(dist);
        ao2_ref(dist, -1);
    }
    ao2_unlock(dialog_associations);
}

References ao2_alloc, ao2_find, ao2_link_flags, ao2_lock, ao2_ref, ao2_unlink_flags, ao2_unlock, ao2_wrlock, dialog_associations, distributor_dialog_data::dlg, distributor_dialog_data::endpoint, NULL, OBJ_NOLOCK, OBJ_SEARCH_KEY, and distributor_dialog_data::serializer.

Referenced by ast_sip_session_alloc(), clean_sub_tree(), session_end_completion(), and subscription_setup_dialog().

ast_sip_get_distributor_serializer()

struct ast_taskprocessor * ast_sip_get_distributor_serializer

(

pjsip_rx_data *

rdata

)

Determine the distributor serializer for the SIP message.

Since

13.10.0

Parameters

rdata

The incoming message.

Return values

Calculated	distributor serializer on success.
NULL	on error.

Definition at line 445 of file pjsip_distributor.c.

{
    int hash;
    pj_str_t *remote_tag;
    struct ast_taskprocessor *serializer;
 
    if (!rdata->msg_info.msg) {
        return NULL;
    }
 
    if (rdata->msg_info.msg->type == PJSIP_REQUEST_MSG) {
        remote_tag = &rdata->msg_info.from->tag;
    } else {
        remote_tag = &rdata->msg_info.to->tag;
    }
 
    /* Compute the hash from the SIP message call-id and remote-tag */
    hash = pjstr_hash(&rdata->msg_info.cid->id);
    hash = pjstr_hash_add(remote_tag, hash);
    hash = ast_str_hash_restrict(hash);
 
    serializer = ao2_bump(distributor_pool[hash % ARRAY_LEN(distributor_pool)]);
    if (serializer) {
        ast_debug(3, "Calculated serializer %s to use for %s\n",
            ast_taskprocessor_name(serializer), pjsip_rx_data_get_info(rdata));
    }
    return serializer;
}

References ao2_bump, ARRAY_LEN, ast_debug, ast_str_hash_restrict(), ast_taskprocessor_name(), distributor_pool, NULL, pjstr_hash(), and pjstr_hash_add().

Referenced by allocate_subscription_tree(), ast_sip_session_alloc(), distributor(), and subscription_persistence_recreate().

ast_sip_push_task()

int ast_sip_push_task	(	struct ast_taskprocessor *	serializer,
		int(*)(void *)	sip_task,
		void *	task_data
	)

Pushes a task to SIP servants.

This uses the serializer provided to determine how to push the task. If the serializer is NULL, then the task will be pushed to the servants directly. If the serializer is non-NULL, then the task will be queued behind other tasks associated with the same serializer.

Parameters

serializer	The serializer to which the task belongs. Can be NULL
sip_task	The task to execute
task_data	The parameter to pass to the task when it executes

Return values

0	Success
-1	Failure

Definition at line 2099 of file res_pjsip.c.

{
    if (!serializer) {
        serializer = ast_serializer_pool_get(sip_serializer_pool);
    }
 
    return ast_taskprocessor_push(serializer, sip_task, task_data);
}

References ast_serializer_pool_get(), ast_taskprocessor_push(), and sip_serializer_pool.

Referenced by aoc_framehook(), ast_sip_push_task_wait(), ast_sip_session_suspend(), auth_observer(), cancel_and_unpublish(), chan_pjsip_call(), chan_pjsip_digit_end(), chan_pjsip_hangup(), chan_pjsip_indicate(), chan_pjsip_sendtext_data(), chan_pjsip_set_rtp_peer(), chan_pjsip_transfer(), check_delayed_requests(), contact_observer_updated(), distributor(), exten_state_publisher_state_cb(), handle_topology_request_change(), load_module(), mwi_startup_event_cb(), mwi_stasis_cb(), pjsip_set_history(), pjsip_show_history(), publish_expire(), publisher_client_send(), pubsub_on_client_refresh(), pubsub_on_rx_refresh(), pubsub_on_rx_subscribe_request(), pubsub_on_server_timeout(), push_notify(), push_notify_channel(), push_notify_uri(), push_to_serializer(), qualify_contact_cb(), queue_register(), queue_unregister(), refer_attended_task(), refer_blind_callback(), refer_incoming_attended_request(), refer_incoming_refer_request(), refer_progress_bridge(), refer_progress_destroy(), refer_progress_framehook(), refer_progress_framehook_destroy(), register_contact_transport_shutdown_cb(), registration_transport_shutdown_cb(), resend_reinvite(), sched_cb(), send_contact_notify(), send_notify(), session_end_if_disconnected(), session_inv_on_state_changed(), session_termination_cb(), sip_options_contact_status_update(), sip_outbound_publish_callback(), sip_outbound_publish_client_add_publisher(), sip_outbound_registration_apply(), sip_outbound_registration_response_cb(), sip_outbound_registration_state_destroy(), sip_outbound_registration_timer_cb(), sip_publisher_service_queue(), state_changed(), sub_persistence_recreate(), sub_tree_transport_cb(), subscription_persistence_event_cb(), t38_automatic_reject_timer_cb(), and t38_framehook().

ast_sip_push_task_synchronous()

int ast_sip_push_task_synchronous	(	struct ast_taskprocessor *	serializer,
		int(*)(void *)	sip_task,
		void *	task_data
	)

Push a task to SIP servants and wait for it to complete.

Deprecated:

Replaced with ast_sip_push_task_wait_servant().

Definition at line 2174 of file res_pjsip.c.

{
    return ast_sip_push_task_wait_servant(serializer, sip_task, task_data);
}

References ast_sip_push_task_wait_servant().

ast_sip_push_task_wait_serializer()

int ast_sip_push_task_wait_serializer	(	struct ast_taskprocessor *	serializer,
		int(*)(void *)	sip_task,
		void *	task_data
	)

Push a task to the serializer and wait for it to complete.

Like ast_sip_push_task except that it blocks until the task is completed by the specified serializer. If the specified serializer is the current thread then the task executes immediately.

Note

PJPROJECT callbacks tend to have locks already held when called.

Warning

Never hold locks that may be acquired by a SIP servant thread when calling this function. Doing so may cause a deadlock if all SIP servant threads are blocked waiting to acquire the lock while the thread holding the lock is waiting for a free SIP servant thread for the serializer to execute in.

Never hold locks that may be acquired by the serializer when calling this function. Doing so will cause a deadlock.

Never use this function in the pjsip monitor thread (It is a SIP servant thread). This is likely to cause a deadlock.

Use of this function in an ao2 destructor callback is a bad idea. You don't have control over which thread executes the destructor. Attempting to shift execution to another thread with this function is likely to cause deadlock.

Parameters

serializer	The SIP serializer to execute the task. NULL if any of the default serializers can be used.
sip_task	The task to execute
task_data	The parameter to pass to the task when it executes

Note

It is generally better to call ast_sip_push_task_wait_servant() if you pass NULL for the serializer parameter.

The sip_task() return value may need to be distinguished from the failure to push the task.

Returns

sip_task() return value on success.

Return values

-1	Failure to push the task.

Definition at line 2179 of file res_pjsip.c.

{
    if (!serializer) {
        /* Caller doesn't care which PJSIP serializer the task executes under. */
        serializer = ast_serializer_pool_get(sip_serializer_pool);
        if (!serializer) {
            /* No serializer picked to execute the task */
            return -1;
        }
    }
    if (ast_taskprocessor_is_task(serializer)) {
        /*
         * We are the requested serializer so we must execute
         * the task now or deadlock waiting on ourself to
         * execute it.
         */
        return sip_task(task_data);
    }
 
    return ast_sip_push_task_wait(serializer, sip_task, task_data);
}

References ast_serializer_pool_get(), ast_sip_push_task_wait(), ast_taskprocessor_is_task(), and sip_serializer_pool.

Referenced by ami_sip_qualify(), aor_observer_deleted(), aor_observer_modified(), ast_res_pjsip_cleanup_options_handling(), ast_res_pjsip_init_options_handling(), chan_pjsip_answer(), cli_qualify(), cli_reload_qualify_aor(), cli_reload_qualify_endpoint(), contact_observer_created(), contact_observer_deleted(), contact_observer_updated(), endpoint_observer_deleted(), endpoint_observer_modified(), func_read_header(), func_read_headers(), func_read_param(), func_response_read_header(), func_response_read_headers(), func_write_header(), func_write_param(), pjsip_acf_channel_read(), pjsip_acf_dtmf_mode_write(), pjsip_acf_media_offer_write(), pjsip_acf_parse_uri_read(), pjsip_acf_session_refresh_write(), pjsip_app_hangup_handler(), refer_incoming_invite_request(), sip_msg_send(), sip_options_aor_observer_deleted_task(), sip_options_aor_observer_modified_task(), sip_options_cleanup_task(), sip_options_contact_add_management_task(), sip_options_contact_delete_management_task(), sip_options_endpoint_unlink_aor_feeders(), sip_options_synchronize(), sip_options_synchronize_aor(), sip_options_synchronize_endpoint(), sip_options_unused_aor(), sip_outbound_registration_apply(), sip_refer_send(), subscription_persistence_recreate(), and websocket_cb().

ast_sip_push_task_wait_servant()

int ast_sip_push_task_wait_servant	(	struct ast_taskprocessor *	serializer,
		int(*)(void *)	sip_task,
		void *	task_data
	)

Push a task to SIP servants and wait for it to complete.

Like ast_sip_push_task except that it blocks until the task completes. If the current thread is a SIP servant thread then the task executes immediately. Otherwise, the specified serializer executes the task and the current thread waits for it to complete.

Note

PJPROJECT callbacks tend to have locks already held when called.

Warning

Never hold locks that may be acquired by a SIP servant thread when calling this function. Doing so may cause a deadlock if all SIP servant threads are blocked waiting to acquire the lock while the thread holding the lock is waiting for a free SIP servant thread.

Use of this function in an ao2 destructor callback is a bad idea. You don't have control over which thread executes the destructor. Attempting to shift execution to another thread with this function is likely to cause deadlock.

Parameters

serializer	The SIP serializer to execute the task if the current thread is not a SIP servant. NULL if any of the default serializers can be used.
sip_task	The task to execute
task_data	The parameter to pass to the task when it executes

Note

The sip_task() return value may need to be distinguished from the failure to push the task.

Returns

sip_task() return value on success.

Return values

-1	Failure to push the task.

Definition at line 2165 of file res_pjsip.c.

{
    if (ast_sip_thread_is_servant()) {
        return sip_task(task_data);
    }
 
    return ast_sip_push_task_wait(serializer, sip_task, task_data);
}

References ast_sip_push_task_wait(), and ast_sip_thread_is_servant().

Referenced by ami_outbound_registration_detail(), ast_sip_initialize_dns(), ast_sip_push_task_synchronous(), ast_sip_register_service(), ast_sip_unregister_service(), chan_pjsip_request_with_stream_topology(), cli_dump_endpt(), current_state_reusable(), refer_out_of_dialog_destroy(), reload_module(), sip_outbound_publisher_alloc(), sip_transport_state_destroy(), subscription_tree_destructor(), and unload_module().

ast_sip_sched_is_task_running()

int ast_sip_sched_is_task_running

(

struct ast_sip_sched_task *

schtd

)

Checks if the task is currently running.

Since

13.9.0

Parameters

schtd

The task structure pointer

Return values

0	not running
1	running

Definition at line 375 of file pjsip_scheduler.c.

{
    return schtd ? schtd->is_running : 0;
}

References ast_sip_sched_task::is_running.

Referenced by AST_TEST_DEFINE().

ast_sip_sched_is_task_running_by_name()

int ast_sip_sched_is_task_running_by_name

(

const char *

name

)

Checks if the task is currently running.

Since

13.9.0

Parameters

name	The task name

Return values

0	not running or not found
1	running

Definition at line 380 of file pjsip_scheduler.c.

{
    int is_running;
    struct ast_sip_sched_task *schtd;
 
    if (ast_strlen_zero(name)) {
        return 0;
    }
 
    schtd = ao2_find(tasks, name, OBJ_SEARCH_KEY);
    if (!schtd) {
        return 0;
    }
 
    is_running = schtd->is_running;
    ao2_ref(schtd, -1);
    return is_running;
}

References ao2_find, ao2_ref, ast_strlen_zero(), ast_sip_sched_task::is_running, name, OBJ_SEARCH_KEY, and tasks.

Referenced by AST_TEST_DEFINE().

ast_sip_sched_task_cancel()

int ast_sip_sched_task_cancel

(

struct ast_sip_sched_task *

schtd

)

Cancels the next invocation of a task.

Since

13.9.0

Parameters

schtd

The task structure pointer

Return values

0	Success
-1	Failure

Note

Only cancels future invocations not the currently running invocation.

Definition at line 191 of file pjsip_scheduler.c.

{
    int res;
    int sched_id;
 
    if (schtd->flags & AST_SIP_SCHED_TASK_TRACK) {
        ast_log(LOG_DEBUG, "Sched %p: Canceling %s\n", schtd, schtd->name);
    }
 
    /*
     * Prevent any tasks in the serializer queue from
     * running and restarting the scheduled item on us
     * first.
     */
    ao2_lock(schtd);
    schtd->interval = 0;
 
    sched_id = schtd->current_scheduler_id;
    schtd->current_scheduler_id = -1;
    ao2_unlock(schtd);
    res = ast_sched_del(scheduler_context, sched_id);
 
    ao2_unlink(tasks, schtd);
 
    return res;
}

References ao2_lock, ao2_unlink, ao2_unlock, ast_log, ast_sched_del(), AST_SIP_SCHED_TASK_TRACK, ast_sip_sched_task::current_scheduler_id, ast_sip_sched_task::flags, ast_sip_sched_task::interval, LOG_DEBUG, ast_sip_sched_task::name, scheduler_context, and tasks.

Referenced by ast_sip_destroy_scheduler(), ast_sip_sched_task_cancel_by_name(), AST_TEST_DEFINE(), clean_sub_tree(), pubsub_on_rx_refresh(), scheduler(), sip_options_aor_remove_task(), sip_options_apply_aor_configuration(), sip_options_cleanup_aor_task(), sip_options_contact_add_task(), and sip_options_contact_delete_task().

ast_sip_sched_task_cancel_by_name()

int ast_sip_sched_task_cancel_by_name

(

const char *

name

)

Cancels the next invocation of a task by name.

Since

13.9.0

Parameters

name	The task name

Return values

0	Success
-1	Failure

Note

Only cancels future invocations not the currently running invocation.

Definition at line 218 of file pjsip_scheduler.c.

{
    int res;
    struct ast_sip_sched_task *schtd;
 
    if (ast_strlen_zero(name)) {
        return -1;
    }
 
    schtd = ao2_find(tasks, name, OBJ_SEARCH_KEY);
    if (!schtd) {
        return -1;
    }
 
    res = ast_sip_sched_task_cancel(schtd);
    ao2_ref(schtd, -1);
    return res;
}

References ao2_find, ao2_ref, ast_sip_sched_task_cancel(), ast_strlen_zero(), name, OBJ_SEARCH_KEY, and tasks.

Referenced by AST_TEST_DEFINE().

ast_sip_sched_task_get_name()

int ast_sip_sched_task_get_name	(	struct ast_sip_sched_task *	schtd,
		char *	name,
		size_t	maxlen
	)

Gets the task name.

Since

13.9.0

Parameters

schtd	The task structure pointer
name,maxlen

Return values

0	success
1	failure

Definition at line 334 of file pjsip_scheduler.c.

{
    if (maxlen <= 0) {
        return -1;
    }
 
    ao2_lock(schtd);
    ast_copy_string(name, schtd->name, maxlen);
    ao2_unlock(schtd);
 
    return 0;
}

References ao2_lock, ao2_unlock, ast_copy_string(), ast_sip_sched_task::name, and name.

Referenced by clean_sub_tree(), and pubsub_on_rx_refresh().

ast_sip_sched_task_get_next_run()

int ast_sip_sched_task_get_next_run

(

struct ast_sip_sched_task *

schtd

)

Gets the number of milliseconds until the next invocation.

Since

13.9.0

Parameters

schtd

The task structure pointer

Returns

The number of milliseconds until the next invocation or -1 if the task isn't scheduled

Definition at line 347 of file pjsip_scheduler.c.

{
    int delay;
 
    ast_sip_sched_task_get_times2(schtd, NULL, NULL, NULL, NULL, &delay, NULL);
 
    return delay;
}

References ast_sip_sched_task_get_times2(), and NULL.

Referenced by ast_sip_sched_task_get_next_run_by_name(), AST_TEST_DEFINE(), and cli_show_tasks().

ast_sip_sched_task_get_next_run_by_name()

int ast_sip_sched_task_get_next_run_by_name

(

const char *

name

)

Gets the number of milliseconds until the next invocation.

Since

13.9.0

Parameters

name	The task name

Returns

The number of milliseconds until the next invocation or -1 if the task isn't scheduled

Definition at line 356 of file pjsip_scheduler.c.

{
    int next_run;
    struct ast_sip_sched_task *schtd;
 
    if (ast_strlen_zero(name)) {
        return -1;
    }
 
    schtd = ao2_find(tasks, name, OBJ_SEARCH_KEY);
    if (!schtd) {
        return -1;
    }
 
    next_run = ast_sip_sched_task_get_next_run(schtd);
    ao2_ref(schtd, -1);
    return next_run;
}

References ao2_find, ao2_ref, ast_sip_sched_task_get_next_run(), ast_strlen_zero(), name, OBJ_SEARCH_KEY, and tasks.

Referenced by AST_TEST_DEFINE().

ast_sip_sched_task_get_times()

int ast_sip_sched_task_get_times	(	struct ast_sip_sched_task *	schtd,
		struct timeval *	when_queued,
		struct timeval *	last_start,
		struct timeval *	last_end
	)

Gets the last start and end times of the task.

Since

13.9.0

Parameters

	schtd	The task structure pointer
[out]	when_queued	Pointer to a timeval structure to contain the time when queued
[out]	last_start	Pointer to a timeval structure to contain the time when last started
[out]	last_end	Pointer to a timeval structure to contain the time when last ended

Return values

0	Success
-1	Failure

Note

Any of the pointers can be NULL if you don't need them.

Definition at line 299 of file pjsip_scheduler.c.

{
    return ast_sip_sched_task_get_times2(schtd, queued, last_start, last_end, NULL, NULL, NULL);
}

References ast_sip_sched_task_get_times2(), and NULL.

Referenced by scheduler().

ast_sip_sched_task_get_times2()

int ast_sip_sched_task_get_times2	(	struct ast_sip_sched_task *	schtd,
		struct timeval *	when_queued,
		struct timeval *	last_start,
		struct timeval *	last_end,
		int *	interval,
		int *	time_left,
		struct timeval *	next_start
	)

Gets the queued, last start, last_end, time left, interval, next run.

Since

16.15.0

18.1.0

Parameters

	schtd	The task structure pointer
[out]	when_queued	Pointer to a timeval structure to contain the time when queued
[out]	last_start	Pointer to a timeval structure to contain the time when last started
[out]	last_end	Pointer to a timeval structure to contain the time when last ended
[out]	interval	Pointer to an int to contain the interval in ms
[out]	time_left	Pointer to an int to contain the ms left to the next run
[out]	next_start	Pointer to a timeval structure to contain the next run time

Return values

0	Success
-1	Failure

Note

Any of the pointers can be NULL if you don't need them.

Definition at line 237 of file pjsip_scheduler.c.

{
    ao2_lock(schtd);
    if (queued) {
        memcpy(queued, &schtd->when_queued, sizeof(struct timeval));
    }
    if (last_start) {
        memcpy(last_start, &schtd->last_start, sizeof(struct timeval));
    }
    if (last_end) {
        memcpy(last_end, &schtd->last_end, sizeof(struct timeval));
    }
 
    if (interval) {
        *interval = schtd->interval;
    }
 
    if (time_left || next_start) {
        int delay;
        struct timeval since_when;
        struct timeval now;
        struct timeval next;
 
        if (schtd->interval) {
            delay = schtd->interval;
            now = ast_tvnow();
 
            if (schtd->flags & AST_SIP_SCHED_TASK_DELAY) {
                since_when = schtd->is_running ? now : schtd->last_end;
            } else {
                since_when = schtd->last_start.tv_sec ? schtd->last_start : schtd->when_queued;
            }
 
            delay -= ast_tvdiff_ms(now, since_when);
 
            delay = delay < 0 ? 0 : delay;
 
 
            if (time_left) {
                *time_left = delay;
            }
 
            if (next_start) {
                next = ast_tvadd(now, ast_tv(delay / 1000, (delay % 1000) * 1000));
                memcpy(next_start, &next, sizeof(struct timeval));
            }
        } else {
            if (time_left) {
                *time_left = -1;
            }
        }
 
    }
 
    ao2_unlock(schtd);
 
    return 0;
}

References ao2_lock, ao2_unlock, AST_SIP_SCHED_TASK_DELAY, ast_tv(), ast_tvadd(), ast_tvdiff_ms(), ast_tvnow(), ast_sip_sched_task::flags, ast_sip_sched_task::interval, ast_sip_sched_task::is_running, ast_sip_sched_task::last_end, ast_sip_sched_task::last_start, and ast_sip_sched_task::when_queued.

Referenced by ast_sip_sched_task_get_next_run(), ast_sip_sched_task_get_times(), and ast_sip_sched_task_get_times_by_name2().

ast_sip_sched_task_get_times_by_name()

int ast_sip_sched_task_get_times_by_name	(	const char *	name,
		struct timeval *	when_queued,
		struct timeval *	last_start,
		struct timeval *	last_end
	)

Gets the last start and end times of the task by name.

Since

13.9.0

Parameters

	name	The task name
[out]	when_queued	Pointer to a timeval structure to contain the time when queued
[out]	last_start	Pointer to a timeval structure to contain the time when last started
[out]	last_end	Pointer to a timeval structure to contain the time when last ended

Return values

0	Success
-1	Failure

Note

Any of the pointers can be NULL if you don't need them.

Definition at line 327 of file pjsip_scheduler.c.

{
    return ast_sip_sched_task_get_times_by_name2(name, queued, last_start, last_end,
        NULL, NULL, NULL);
}

References ast_sip_sched_task_get_times_by_name2(), ast_sip_sched_task::last_end, ast_sip_sched_task::last_start, name, and NULL.

ast_sip_sched_task_get_times_by_name2()

int ast_sip_sched_task_get_times_by_name2	(	const char *	name,
		struct timeval *	when_queued,
		struct timeval *	last_start,
		struct timeval *	last_end,
		int *	interval,
		int *	time_left,
		struct timeval *	next_start
	)

Gets the queued, last start, last_end, time left, interval, next run by task name.

Since

16.15.0

18.1.0

Parameters

	name	The task name
[out]	when_queued	Pointer to a timeval structure to contain the time when queued
[out]	last_start	Pointer to a timeval structure to contain the time when last started
[out]	last_end	Pointer to a timeval structure to contain the time when last ended
[out]	interval	Pointer to an int to contain the interval in ms
[out]	time_left	Pointer to an int to contain the ms left to the next run
[out]	next_start	Pointer to a timeval structure to contain the next run time

Return values

0	Success
-1	Failure

Note

Any of the pointers can be NULL if you don't need them.

Definition at line 305 of file pjsip_scheduler.c.

{
    int res;
    struct ast_sip_sched_task *schtd;
 
    if (ast_strlen_zero(name)) {
        return -1;
    }
 
    schtd = ao2_find(tasks, name, OBJ_SEARCH_KEY);
    if (!schtd) {
        return -1;
    }
 
    res = ast_sip_sched_task_get_times2(schtd, queued, last_start, last_end, interval, time_left,
        next_start);
    ao2_ref(schtd, -1);
    return res;
}

References ao2_find, ao2_ref, ast_sip_sched_task_get_times2(), ast_strlen_zero(), ast_sip_sched_task::interval, ast_sip_sched_task::last_end, ast_sip_sched_task::last_start, name, OBJ_SEARCH_KEY, and tasks.

Referenced by ast_sip_sched_task_get_times_by_name().

ast_sip_schedule_task()

struct ast_sip_sched_task * ast_sip_schedule_task	(	struct ast_taskprocessor *	serializer,
		int	interval,
		ast_sip_task	sip_task,
		const char *	name,
		void *	task_data,
		enum ast_sip_scheduler_task_flags	flags
	)

Schedule a task to run in the res_pjsip thread pool.

Since

13.9.0

Parameters

serializer	The serializer to use. If NULL, don't use a serializer (see note below)
interval	The invocation interval in milliseconds (see note below)
sip_task	The task to invoke
name	An optional name to associate with the task
task_data	Optional data to pass to the task
flags	One of enum ast_sip_scheduler_task_type

Returns

Pointer to ast_sip_sched_task ao2 object which must be dereferenced when done.

Serialization

Specifying a serializer guarantees serialized execution but NOT specifying a serializer may still result in tasks being effectively serialized if the thread pool is busy. The point of the serializer BTW is not to prevent parallel executions of the SAME task. That happens automatically (see below). It's to prevent the task from running at the same time as other work using the same serializer, whether or not it's being run by the scheduler.

Interval

The interval is used to calculate the next time the task should run. There are two models.

AST_SIP_SCHED_TASK_PERIODIC specifies that the invocations of the task occur at the specific interval. That is, every interval milliseconds, regardless of how long the task takes. If the task takes longer than interval, it will be scheduled at the next available multiple of interval. For example: If the task has an interval of 60 seconds and the task takes 70 seconds, the next invocation will happen at 120 seconds.

AST_SIP_SCHED_TASK_DELAY specifies that the next invocation of the task should start at interval milliseconds after the current invocation has finished.

Definition at line 415 of file pjsip_scheduler.c.

{
#define ID_LEN 13 /* task_deadbeef */
    struct ast_sip_sched_task *schtd;
    int res;
 
    if (interval <= 0) {
        return NULL;
    }
 
    schtd = ao2_alloc((sizeof(*schtd) + (!ast_strlen_zero(name) ? strlen(name) : ID_LEN) + 1),
        schtd_dtor);
    if (!schtd) {
        return NULL;
    }
 
    schtd->serializer = ao2_bump(serializer);
    schtd->task_data = task_data;
    schtd->task = sip_task;
    schtd->interval = interval;
    schtd->flags = flags;
    schtd->last_start = ast_tv(0, 0);
    if (!ast_strlen_zero(name)) {
        strcpy(schtd->name, name); /* Safe */
    } else {
        uint32_t task_id;
 
        task_id = ast_atomic_fetchadd_int(&task_count, 1);
        sprintf(schtd->name, "task_%08x", task_id);
    }
    if (schtd->flags & AST_SIP_SCHED_TASK_TRACK) {
        ast_log(LOG_DEBUG, "Sched %p: Scheduling %s for %d ms\n", schtd, schtd->name,
            interval);
    }
    schtd->when_queued = ast_tvnow();
    if (!(schtd->flags & AST_SIP_SCHED_TASK_DELAY)) {
        schtd->next_periodic = ast_tvadd(schtd->when_queued,
            ast_samp2tv(schtd->interval, 1000));
    }
 
    if (flags & AST_SIP_SCHED_TASK_DATA_AO2) {
        ao2_ref(task_data, +1);
    }
 
    /*
     * We must put it in the 'tasks' container before scheduling
     * the task because we don't want the push_to_serializer()
     * sched task to "remove" it on failure before we even put
     * it in.  If this happens then nothing would remove it from
     * the 'tasks' container.
     */
    ao2_link(tasks, schtd);
 
    /*
     * Lock so we are guaranteed to get the sched id set before
     * the push_to_serializer() sched task can clear it.
     */
    ao2_lock(schtd);
    res = ast_sched_add(scheduler_context, interval, push_to_serializer, schtd);
    schtd->current_scheduler_id = res;
    ao2_unlock(schtd);
    if (res < 0) {
        ao2_unlink(tasks, schtd);
        ao2_ref(schtd, -1);
        return NULL;
    }
 
    return schtd;
#undef ID_LEN
}

References ao2_alloc, ao2_bump, ao2_link, ao2_lock, ao2_ref, ao2_unlink, ao2_unlock, ast_atomic_fetchadd_int(), ast_log, ast_samp2tv(), ast_sched_add(), AST_SIP_SCHED_TASK_DATA_AO2, AST_SIP_SCHED_TASK_DELAY, AST_SIP_SCHED_TASK_TRACK, ast_strlen_zero(), ast_tv(), ast_tvadd(), ast_tvnow(), ast_sip_sched_task::current_scheduler_id, ast_sip_sched_task::flags, ID_LEN, ast_sip_sched_task::interval, ast_sip_sched_task::last_start, LOG_DEBUG, ast_sip_sched_task::name, name, ast_sip_sched_task::next_periodic, NULL, push_to_serializer(), scheduler_context, schtd_dtor(), ast_sip_sched_task::serializer, ast_sip_sched_task::task, task_count, ast_sip_sched_task::task_data, tasks, and ast_sip_sched_task::when_queued.

Referenced by AST_TEST_DEFINE(), initial_notify_task(), scheduler(), sip_options_apply_aor_configuration(), and sip_options_contact_add_task().

ast_sip_thread_is_servant()

int ast_sip_thread_is_servant

(

void

)

Determine if the current thread is a SIP servant thread.

Return values

0	This is not a SIP servant thread
1	This is a SIP servant thread

Definition at line 2310 of file res_pjsip.c.

{
    uint32_t *servant_id;
 
    if (monitor_thread &&
            pthread_self() == *(pthread_t *)pj_thread_get_os_handle(monitor_thread)) {
        return 1;
    }
 
    servant_id = ast_threadstorage_get(&servant_id_storage, sizeof(*servant_id));
    if (!servant_id) {
        return 0;
    }
 
    return *servant_id == SIP_SERVANT_ID;
}

References ast_threadstorage_get(), monitor_thread, servant_id_storage, and SIP_SERVANT_ID.

Referenced by ast_sip_push_task_wait_servant(), refer_progress_destroy(), and task_1().