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