Cleanup taskprocessor on exit.
[asterisk/asterisk.git] / main / taskprocessor.c
1 /*
2  * Asterisk -- An open source telephony toolkit.
3  *
4  * Copyright (C) 2007-2008, Digium, Inc.
5  *
6  * Dwayne M. Hubbard <dhubbard@digium.com>
7  *
8  * See http://www.asterisk.org for more information about
9  * the Asterisk project. Please do not directly contact
10  * any of the maintainers of this project for assistance;
11  * the project provides a web site, mailing lists and IRC
12  * channels for your use.
13  *
14  * This program is free software, distributed under the terms of
15  * the GNU General Public License Version 2. See the LICENSE file
16  * at the top of the source tree.
17  */
18
19 /*!
20  * \file
21  * \brief Maintain a container of uniquely-named taskprocessor threads that can be shared across modules.
22  *
23  * \author Dwayne Hubbard <dhubbard@digium.com>
24  */
25
26 /*** MODULEINFO
27         <support_level>core</support_level>
28  ***/
29
30 #include "asterisk.h"
31
32 ASTERISK_FILE_VERSION(__FILE__, "$Revision$")
33
34 #include "asterisk/_private.h"
35 #include "asterisk/module.h"
36 #include "asterisk/time.h"
37 #include "asterisk/astobj2.h"
38 #include "asterisk/cli.h"
39 #include "asterisk/taskprocessor.h"
40
41
42 /*!
43  * \brief tps_task structure is queued to a taskprocessor
44  *
45  * tps_tasks are processed in FIFO order and freed by the taskprocessing
46  * thread after the task handler returns.  The callback function that is assigned
47  * to the execute() function pointer is responsible for releasing datap resources if necessary.
48  */
49 struct tps_task {
50         /*! \brief The execute() task callback function pointer */
51         int (*execute)(void *datap);
52         /*! \brief The data pointer for the task execute() function */
53         void *datap;
54         /*! \brief AST_LIST_ENTRY overhead */
55         AST_LIST_ENTRY(tps_task) list;
56 };
57
58 /*! \brief tps_taskprocessor_stats maintain statistics for a taskprocessor. */
59 struct tps_taskprocessor_stats {
60         /*! \brief This is the maximum number of tasks queued at any one time */
61         unsigned long max_qsize;
62         /*! \brief This is the current number of tasks processed */
63         unsigned long _tasks_processed_count;
64 };
65
66 /*! \brief A ast_taskprocessor structure is a singleton by name */
67 struct ast_taskprocessor {
68         /*! \brief Friendly name of the taskprocessor */
69         const char *name;
70         /*! \brief Thread poll condition */
71         ast_cond_t poll_cond;
72         /*! \brief Taskprocessor thread */
73         pthread_t poll_thread;
74         /*! \brief Taskprocessor lock */
75         ast_mutex_t taskprocessor_lock;
76         /*! \brief Taskprocesor thread run flag */
77         unsigned char poll_thread_run;
78         /*! \brief Taskprocessor statistics */
79         struct tps_taskprocessor_stats *stats;
80         /*! \brief Taskprocessor current queue size */
81         long tps_queue_size;
82         /*! \brief Taskprocessor queue */
83         AST_LIST_HEAD_NOLOCK(tps_queue, tps_task) tps_queue;
84         /*! \brief Taskprocessor singleton list entry */
85         AST_LIST_ENTRY(ast_taskprocessor) list;
86 };
87 #define TPS_MAX_BUCKETS 7
88 /*! \brief tps_singletons is the astobj2 container for taskprocessor singletons */
89 static struct ao2_container *tps_singletons;
90
91 /*! \brief CLI <example>taskprocessor ping &lt;blah&gt;</example> operation requires a ping condition */
92 static ast_cond_t cli_ping_cond;
93
94 /*! \brief CLI <example>taskprocessor ping &lt;blah&gt;</example> operation requires a ping condition lock */
95 AST_MUTEX_DEFINE_STATIC(cli_ping_cond_lock);
96
97 /*! \brief The astobj2 hash callback for taskprocessors */
98 static int tps_hash_cb(const void *obj, const int flags);
99 /*! \brief The astobj2 compare callback for taskprocessors */
100 static int tps_cmp_cb(void *obj, void *arg, int flags);
101
102 /*! \brief The task processing function executed by a taskprocessor */
103 static void *tps_processing_function(void *data);
104
105 /*! \brief Destroy the taskprocessor when its refcount reaches zero */
106 static void tps_taskprocessor_destroy(void *tps);
107
108 /*! \brief CLI <example>taskprocessor ping &lt;blah&gt;</example> handler function */
109 static int tps_ping_handler(void *datap);
110
111 /*! \brief Remove the front task off the taskprocessor queue */
112 static struct tps_task *tps_taskprocessor_pop(struct ast_taskprocessor *tps);
113
114 /*! \brief Return the size of the taskprocessor queue */
115 static int tps_taskprocessor_depth(struct ast_taskprocessor *tps);
116
117 static char *cli_tps_ping(struct ast_cli_entry *e, int cmd, struct ast_cli_args *a);
118 static char *cli_tps_report(struct ast_cli_entry *e, int cmd, struct ast_cli_args *a);
119
120 static struct ast_cli_entry taskprocessor_clis[] = {
121         AST_CLI_DEFINE(cli_tps_ping, "Ping a named task processor"),
122         AST_CLI_DEFINE(cli_tps_report, "List instantiated task processors and statistics"),
123 };
124
125 /*!
126  * \internal
127  * \brief Clean up resources on Asterisk shutdown
128  */
129 static void tps_shutdown(void)
130 {
131         ast_cli_unregister_multiple(taskprocessor_clis, ARRAY_LEN(taskprocessor_clis));
132         ao2_t_ref(tps_singletons, -1, "Unref tps_singletons in shutdown");
133         tps_singletons = NULL;
134 }
135
136 /* initialize the taskprocessor container and register CLI operations */
137 int ast_tps_init(void)
138 {
139         if (!(tps_singletons = ao2_container_alloc(TPS_MAX_BUCKETS, tps_hash_cb, tps_cmp_cb))) {
140                 ast_log(LOG_ERROR, "taskprocessor container failed to initialize!\n");
141                 return -1;
142         }
143
144         ast_cond_init(&cli_ping_cond, NULL);
145
146         ast_cli_register_multiple(taskprocessor_clis, ARRAY_LEN(taskprocessor_clis));
147
148         ast_register_atexit(tps_shutdown);
149
150         return 0;
151 }
152
153 /* allocate resources for the task */
154 static struct tps_task *tps_task_alloc(int (*task_exe)(void *datap), void *datap)
155 {
156         struct tps_task *t;
157         if ((t = ast_calloc(1, sizeof(*t)))) {
158                 t->execute = task_exe;
159                 t->datap = datap;
160         }
161         return t;
162 }
163
164 /* release task resources */
165 static void *tps_task_free(struct tps_task *task)
166 {
167         if (task) {
168                 ast_free(task);
169         }
170         return NULL;
171 }
172
173 /* taskprocessor tab completion */
174 static char *tps_taskprocessor_tab_complete(struct ast_taskprocessor *p, struct ast_cli_args *a)
175 {
176         int tklen;
177         int wordnum = 0;
178         char *name = NULL;
179         struct ao2_iterator i;
180
181         if (a->pos != 3)
182                 return NULL;
183
184         tklen = strlen(a->word);
185         i = ao2_iterator_init(tps_singletons, 0);
186         while ((p = ao2_iterator_next(&i))) {
187                 if (!strncasecmp(a->word, p->name, tklen) && ++wordnum > a->n) {
188                         name = ast_strdup(p->name);
189                         ao2_ref(p, -1);
190                         break;
191                 }
192                 ao2_ref(p, -1);
193         }
194         ao2_iterator_destroy(&i);
195         return name;
196 }
197
198 /* ping task handling function */
199 static int tps_ping_handler(void *datap)
200 {
201         ast_mutex_lock(&cli_ping_cond_lock);
202         ast_cond_signal(&cli_ping_cond);
203         ast_mutex_unlock(&cli_ping_cond_lock);
204         return 0;
205 }
206
207 /* ping the specified taskprocessor and display the ping time on the CLI */
208 static char *cli_tps_ping(struct ast_cli_entry *e, int cmd, struct ast_cli_args *a)
209 {
210         struct timeval begin, end, delta;
211         const char *name;
212         struct timeval when;
213         struct timespec ts;
214         struct ast_taskprocessor *tps = NULL;
215
216         switch (cmd) {
217         case CLI_INIT:
218                 e->command = "core ping taskprocessor";
219                 e->usage =
220                         "Usage: core ping taskprocessor <taskprocessor>\n"
221                         "       Displays the time required for a task to be processed\n";
222                 return NULL;
223         case CLI_GENERATE:
224                 return tps_taskprocessor_tab_complete(tps, a);
225         }
226
227         if (a->argc != 4)
228                 return CLI_SHOWUSAGE;
229
230         name = a->argv[3];
231         if (!(tps = ast_taskprocessor_get(name, TPS_REF_IF_EXISTS))) {
232                 ast_cli(a->fd, "\nping failed: %s not found\n\n", name);
233                 return CLI_SUCCESS;
234         }
235         ast_cli(a->fd, "\npinging %s ...", name);
236         when = ast_tvadd((begin = ast_tvnow()), ast_samp2tv(1000, 1000));
237         ts.tv_sec = when.tv_sec;
238         ts.tv_nsec = when.tv_usec * 1000;
239         ast_mutex_lock(&cli_ping_cond_lock);
240         if (ast_taskprocessor_push(tps, tps_ping_handler, 0) < 0) {
241                 ast_cli(a->fd, "\nping failed: could not push task to %s\n\n", name);
242                 ao2_ref(tps, -1);
243                 return CLI_FAILURE;
244         }
245         ast_cond_timedwait(&cli_ping_cond, &cli_ping_cond_lock, &ts);
246         ast_mutex_unlock(&cli_ping_cond_lock);
247         end = ast_tvnow();
248         delta = ast_tvsub(end, begin);
249         ast_cli(a->fd, "\n\t%24s ping time: %.1ld.%.6ld sec\n\n", name, (long)delta.tv_sec, (long int)delta.tv_usec);
250         ao2_ref(tps, -1);
251         return CLI_SUCCESS;
252 }
253
254 static char *cli_tps_report(struct ast_cli_entry *e, int cmd, struct ast_cli_args *a)
255 {
256         char name[256];
257         int tcount;
258         unsigned long qsize;
259         unsigned long maxqsize;
260         unsigned long processed;
261         struct ast_taskprocessor *p;
262         struct ao2_iterator i;
263
264         switch (cmd) {
265         case CLI_INIT:
266                 e->command = "core show taskprocessors";
267                 e->usage =
268                         "Usage: core show taskprocessors\n"
269                         "       Shows a list of instantiated task processors and their statistics\n";
270                 return NULL;
271         case CLI_GENERATE:
272                 return NULL;
273         }
274
275         if (a->argc != e->args)
276                 return CLI_SHOWUSAGE;
277
278         ast_cli(a->fd, "\n\t+----- Processor -----+--- Processed ---+- In Queue -+- Max Depth -+");
279         i = ao2_iterator_init(tps_singletons, 0);
280         while ((p = ao2_iterator_next(&i))) {
281                 ast_copy_string(name, p->name, sizeof(name));
282                 qsize = p->tps_queue_size;
283                 maxqsize = p->stats->max_qsize;
284                 processed = p->stats->_tasks_processed_count;
285                 ast_cli(a->fd, "\n%24s   %17ld %12ld %12ld", name, processed, qsize, maxqsize);
286                 ao2_ref(p, -1);
287         }
288         ao2_iterator_destroy(&i);
289         tcount = ao2_container_count(tps_singletons);
290         ast_cli(a->fd, "\n\t+---------------------+-----------------+------------+-------------+\n\t%d taskprocessors\n\n", tcount);
291         return CLI_SUCCESS;
292 }
293
294 /* this is the task processing worker function */
295 static void *tps_processing_function(void *data)
296 {
297         struct ast_taskprocessor *i = data;
298         struct tps_task *t;
299         int size;
300
301         if (!i) {
302                 ast_log(LOG_ERROR, "cannot start thread_function loop without a ast_taskprocessor structure.\n");
303                 return NULL;
304         }
305
306         while (i->poll_thread_run) {
307                 ast_mutex_lock(&i->taskprocessor_lock);
308                 if (!i->poll_thread_run) {
309                         ast_mutex_unlock(&i->taskprocessor_lock);
310                         break;
311                 }
312                 if (!(size = tps_taskprocessor_depth(i))) {
313                         ast_cond_wait(&i->poll_cond, &i->taskprocessor_lock);
314                         if (!i->poll_thread_run) {
315                                 ast_mutex_unlock(&i->taskprocessor_lock);
316                                 break;
317                         }
318                 }
319                 ast_mutex_unlock(&i->taskprocessor_lock);
320                 /* stuff is in the queue */
321                 if (!(t = tps_taskprocessor_pop(i))) {
322                         ast_log(LOG_ERROR, "Wtf?? %d tasks in the queue, but we're popping blanks!\n", size);
323                         continue;
324                 }
325                 if (!t->execute) {
326                         ast_log(LOG_WARNING, "Task is missing a function to execute!\n");
327                         tps_task_free(t);
328                         continue;
329                 }
330                 t->execute(t->datap);
331
332                 ast_mutex_lock(&i->taskprocessor_lock);
333                 if (i->stats) {
334                         i->stats->_tasks_processed_count++;
335                         if (size > i->stats->max_qsize) {
336                                 i->stats->max_qsize = size;
337                         }
338                 }
339                 ast_mutex_unlock(&i->taskprocessor_lock);
340
341                 tps_task_free(t);
342         }
343         while ((t = tps_taskprocessor_pop(i))) {
344                 tps_task_free(t);
345         }
346         return NULL;
347 }
348
349 /* hash callback for astobj2 */
350 static int tps_hash_cb(const void *obj, const int flags)
351 {
352         const struct ast_taskprocessor *tps = obj;
353
354         return ast_str_case_hash(tps->name);
355 }
356
357 /* compare callback for astobj2 */
358 static int tps_cmp_cb(void *obj, void *arg, int flags)
359 {
360         struct ast_taskprocessor *lhs = obj, *rhs = arg;
361
362         return !strcasecmp(lhs->name, rhs->name) ? CMP_MATCH | CMP_STOP : 0;
363 }
364
365 /* destroy the taskprocessor */
366 static void tps_taskprocessor_destroy(void *tps)
367 {
368         struct ast_taskprocessor *t = tps;
369
370         if (!tps) {
371                 ast_log(LOG_ERROR, "missing taskprocessor\n");
372                 return;
373         }
374         ast_debug(1, "destroying taskprocessor '%s'\n", t->name);
375         /* kill it */
376         ast_mutex_lock(&t->taskprocessor_lock);
377         t->poll_thread_run = 0;
378         ast_cond_signal(&t->poll_cond);
379         ast_mutex_unlock(&t->taskprocessor_lock);
380         pthread_join(t->poll_thread, NULL);
381         t->poll_thread = AST_PTHREADT_NULL;
382         ast_mutex_destroy(&t->taskprocessor_lock);
383         ast_cond_destroy(&t->poll_cond);
384         /* free it */
385         if (t->stats) {
386                 ast_free(t->stats);
387                 t->stats = NULL;
388         }
389         ast_free((char *) t->name);
390 }
391
392 /* pop the front task and return it */
393 static struct tps_task *tps_taskprocessor_pop(struct ast_taskprocessor *tps)
394 {
395         struct tps_task *task;
396
397         if (!tps) {
398                 ast_log(LOG_ERROR, "missing taskprocessor\n");
399                 return NULL;
400         }
401         ast_mutex_lock(&tps->taskprocessor_lock);
402         if ((task = AST_LIST_REMOVE_HEAD(&tps->tps_queue, list))) {
403                 tps->tps_queue_size--;
404         }
405         ast_mutex_unlock(&tps->taskprocessor_lock);
406         return task;
407 }
408
409 static int tps_taskprocessor_depth(struct ast_taskprocessor *tps)
410 {
411         return (tps) ? tps->tps_queue_size : -1;
412 }
413
414 /* taskprocessor name accessor */
415 const char *ast_taskprocessor_name(struct ast_taskprocessor *tps)
416 {
417         if (!tps) {
418                 ast_log(LOG_ERROR, "no taskprocessor specified!\n");
419                 return NULL;
420         }
421         return tps->name;
422 }
423
424 /* Provide a reference to a taskprocessor.  Create the taskprocessor if necessary, but don't
425  * create the taskprocessor if we were told via ast_tps_options to return a reference only
426  * if it already exists */
427 struct ast_taskprocessor *ast_taskprocessor_get(const char *name, enum ast_tps_options create)
428 {
429         struct ast_taskprocessor *p, tmp_tps = {
430                 .name = name,
431         };
432
433         if (ast_strlen_zero(name)) {
434                 ast_log(LOG_ERROR, "requesting a nameless taskprocessor!!!\n");
435                 return NULL;
436         }
437         ao2_lock(tps_singletons);
438         p = ao2_find(tps_singletons, &tmp_tps, OBJ_POINTER);
439         if (p) {
440                 ao2_unlock(tps_singletons);
441                 return p;
442         }
443         if (create & TPS_REF_IF_EXISTS) {
444                 /* calling function does not want a new taskprocessor to be created if it doesn't already exist */
445                 ao2_unlock(tps_singletons);
446                 return NULL;
447         }
448         /* create a new taskprocessor */
449         if (!(p = ao2_alloc(sizeof(*p), tps_taskprocessor_destroy))) {
450                 ao2_unlock(tps_singletons);
451                 ast_log(LOG_WARNING, "failed to create taskprocessor '%s'\n", name);
452                 return NULL;
453         }
454
455         ast_cond_init(&p->poll_cond, NULL);
456         ast_mutex_init(&p->taskprocessor_lock);
457
458         if (!(p->stats = ast_calloc(1, sizeof(*p->stats)))) {
459                 ao2_unlock(tps_singletons);
460                 ast_log(LOG_WARNING, "failed to create taskprocessor stats for '%s'\n", name);
461                 ao2_ref(p, -1);
462                 return NULL;
463         }
464         if (!(p->name = ast_strdup(name))) {
465                 ao2_unlock(tps_singletons);
466                 ao2_ref(p, -1);
467                 return NULL;
468         }
469         p->poll_thread_run = 1;
470         p->poll_thread = AST_PTHREADT_NULL;
471         if (ast_pthread_create(&p->poll_thread, NULL, tps_processing_function, p) < 0) {
472                 ao2_unlock(tps_singletons);
473                 ast_log(LOG_ERROR, "Taskprocessor '%s' failed to create the processing thread.\n", p->name);
474                 ao2_ref(p, -1);
475                 return NULL;
476         }
477         if (!(ao2_link(tps_singletons, p))) {
478                 ao2_unlock(tps_singletons);
479                 ast_log(LOG_ERROR, "Failed to add taskprocessor '%s' to container\n", p->name);
480                 ao2_ref(p, -1);
481                 return NULL;
482         }
483         ao2_unlock(tps_singletons);
484         return p;
485 }
486
487 /* decrement the taskprocessor reference count and unlink from the container if necessary */
488 void *ast_taskprocessor_unreference(struct ast_taskprocessor *tps)
489 {
490         if (tps) {
491                 ao2_lock(tps_singletons);
492                 ao2_unlink(tps_singletons, tps);
493                 if (ao2_ref(tps, -1) > 1) {
494                         ao2_link(tps_singletons, tps);
495                 }
496                 ao2_unlock(tps_singletons);
497         }
498         return NULL;
499 }
500
501 /* push the task into the taskprocessor queue */
502 int ast_taskprocessor_push(struct ast_taskprocessor *tps, int (*task_exe)(void *datap), void *datap)
503 {
504         struct tps_task *t;
505
506         if (!tps || !task_exe) {
507                 ast_log(LOG_ERROR, "%s is missing!!\n", (tps) ? "task callback" : "taskprocessor");
508                 return -1;
509         }
510         if (!(t = tps_task_alloc(task_exe, datap))) {
511                 ast_log(LOG_ERROR, "failed to allocate task!  Can't push to '%s'\n", tps->name);
512                 return -1;
513         }
514         ast_mutex_lock(&tps->taskprocessor_lock);
515         AST_LIST_INSERT_TAIL(&tps->tps_queue, t, list);
516         tps->tps_queue_size++;
517         ast_cond_signal(&tps->poll_cond);
518         ast_mutex_unlock(&tps->taskprocessor_lock);
519         return 0;
520 }
521