95bff720e60f365ba946b361486af1680f02cbd1
[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  * \brief tps_task structure is queued to a taskprocessor
43  *
44  * tps_tasks are processed in FIFO order and freed by the taskprocessing
45  * thread after the task handler returns.  The callback function that is assigned
46  * to the execute() function pointer is responsible for releasing datap resources if necessary.
47  */
48 struct tps_task {
49         /*! \brief The execute() task callback function pointer */
50         int (*execute)(void *datap);
51         /*! \brief The data pointer for the task execute() function */
52         void *datap;
53         /*! \brief AST_LIST_ENTRY overhead */
54         AST_LIST_ENTRY(tps_task) list;
55 };
56
57 /*! \brief tps_taskprocessor_stats maintain statistics for a taskprocessor. */
58 struct tps_taskprocessor_stats {
59         /*! \brief This is the maximum number of tasks queued at any one time */
60         unsigned long max_qsize;
61         /*! \brief This is the current number of tasks processed */
62         unsigned long _tasks_processed_count;
63 };
64
65 /*! \brief A ast_taskprocessor structure is a singleton by name */
66 struct ast_taskprocessor {
67         /*! \brief Friendly name of the taskprocessor */
68         const char *name;
69         /*! \brief Taskprocessor statistics */
70         struct tps_taskprocessor_stats *stats;
71         /*! \brief Taskprocessor current queue size */
72         long tps_queue_size;
73         /*! \brief Taskprocessor queue */
74         AST_LIST_HEAD_NOLOCK(tps_queue, tps_task) tps_queue;
75         /*! \brief Taskprocessor singleton list entry */
76         AST_LIST_ENTRY(ast_taskprocessor) list;
77         struct ast_taskprocessor_listener *listener;
78         /*! Indicates if the taskprocessor is in the process of shuting down */
79         unsigned int shutting_down:1;
80 };
81 #define TPS_MAX_BUCKETS 7
82 /*! \brief tps_singletons is the astobj2 container for taskprocessor singletons */
83 static struct ao2_container *tps_singletons;
84
85 /*! \brief CLI <example>taskprocessor ping &lt;blah&gt;</example> operation requires a ping condition */
86 static ast_cond_t cli_ping_cond;
87
88 /*! \brief CLI <example>taskprocessor ping &lt;blah&gt;</example> operation requires a ping condition lock */
89 AST_MUTEX_DEFINE_STATIC(cli_ping_cond_lock);
90
91 /*! \brief The astobj2 hash callback for taskprocessors */
92 static int tps_hash_cb(const void *obj, const int flags);
93 /*! \brief The astobj2 compare callback for taskprocessors */
94 static int tps_cmp_cb(void *obj, void *arg, int flags);
95
96 /*! \brief The task processing function executed by a taskprocessor */
97 static void *tps_processing_function(void *data);
98
99 /*! \brief Destroy the taskprocessor when its refcount reaches zero */
100 static void tps_taskprocessor_destroy(void *tps);
101
102 /*! \brief CLI <example>taskprocessor ping &lt;blah&gt;</example> handler function */
103 static int tps_ping_handler(void *datap);
104
105 /*! \brief Remove the front task off the taskprocessor queue */
106 static struct tps_task *tps_taskprocessor_pop(struct ast_taskprocessor *tps);
107
108 /*! \brief Return the size of the taskprocessor queue */
109 static int tps_taskprocessor_depth(struct ast_taskprocessor *tps);
110
111 static char *cli_tps_ping(struct ast_cli_entry *e, int cmd, struct ast_cli_args *a);
112 static char *cli_tps_report(struct ast_cli_entry *e, int cmd, struct ast_cli_args *a);
113
114 static struct ast_cli_entry taskprocessor_clis[] = {
115         AST_CLI_DEFINE(cli_tps_ping, "Ping a named task processor"),
116         AST_CLI_DEFINE(cli_tps_report, "List instantiated task processors and statistics"),
117 };
118
119 struct default_taskprocessor_listener_pvt {
120         pthread_t poll_thread;
121         ast_mutex_t lock;
122         ast_cond_t cond;
123         int wake_up;
124         int dead;
125 };
126
127
128 static void default_tps_wake_up(struct default_taskprocessor_listener_pvt *pvt, int should_die)
129 {
130         SCOPED_MUTEX(lock, &pvt->lock);
131         pvt->wake_up = 1;
132         pvt->dead = should_die;
133         ast_cond_signal(&pvt->cond);
134 }
135
136 static int default_tps_idle(struct default_taskprocessor_listener_pvt *pvt)
137 {
138         SCOPED_MUTEX(lock, &pvt->lock);
139         while (!pvt->wake_up) {
140                 ast_cond_wait(&pvt->cond, lock);
141         }
142         pvt->wake_up = 0;
143         return pvt->dead;
144 }
145
146 /*!
147  * \brief Function that processes tasks in the taskprocessor
148  * \internal
149  */
150 static void *tps_processing_function(void *data)
151 {
152         struct ast_taskprocessor_listener *listener = data;
153         struct ast_taskprocessor *tps = listener->tps;
154         struct default_taskprocessor_listener_pvt *pvt = listener->private_data;
155         int dead = 0;
156
157         while (!dead) {
158                 if (!ast_taskprocessor_execute(tps)) {
159                         dead = default_tps_idle(pvt);
160                 }
161         }
162         return NULL;
163 }
164
165 static void *default_listener_alloc(struct ast_taskprocessor_listener *listener)
166 {
167         struct default_taskprocessor_listener_pvt *pvt;
168
169         pvt = ast_calloc(1, sizeof(*pvt));
170         if (!pvt) {
171                 return NULL;
172         }
173         ast_cond_init(&pvt->cond, NULL);
174         ast_mutex_init(&pvt->lock);
175         pvt->poll_thread = AST_PTHREADT_NULL;
176         return pvt;
177 }
178
179 static int default_listener_start(struct ast_taskprocessor_listener *listener)
180 {
181         struct default_taskprocessor_listener_pvt *pvt = listener->private_data;
182
183         if (ast_pthread_create(&pvt->poll_thread, NULL, tps_processing_function, listener)) {
184                 return -1;
185         }
186
187         return 0;
188 }
189
190 static void default_task_pushed(struct ast_taskprocessor_listener *listener, int was_empty)
191 {
192         struct default_taskprocessor_listener_pvt *pvt = listener->private_data;
193
194         if (was_empty) {
195                 default_tps_wake_up(pvt, 0);
196         }
197 }
198
199 static void default_emptied(struct ast_taskprocessor_listener *listener)
200 {
201         /* No-op */
202 }
203
204 static void default_listener_shutdown(struct ast_taskprocessor_listener *listener)
205 {
206         struct default_taskprocessor_listener_pvt *pvt = listener->private_data;
207         default_tps_wake_up(pvt, 1);
208         pthread_join(pvt->poll_thread, NULL);
209         pvt->poll_thread = AST_PTHREADT_NULL;
210 }
211
212 static void default_listener_destroy(void *obj)
213 {
214         struct default_taskprocessor_listener_pvt *pvt = obj;
215         ast_mutex_destroy(&pvt->lock);
216         ast_cond_destroy(&pvt->cond);
217         ast_free(pvt);
218 }
219
220 static const struct ast_taskprocessor_listener_callbacks default_listener_callbacks = {
221         .alloc = default_listener_alloc,
222         .start = default_listener_start,
223         .task_pushed = default_task_pushed,
224         .emptied = default_emptied,
225         .shutdown = default_listener_shutdown,
226         .destroy = default_listener_destroy,
227 };
228
229 /*!
230  * \internal
231  * \brief Clean up resources on Asterisk shutdown
232  */
233 static void tps_shutdown(void)
234 {
235         ast_cli_unregister_multiple(taskprocessor_clis, ARRAY_LEN(taskprocessor_clis));
236         ao2_t_ref(tps_singletons, -1, "Unref tps_singletons in shutdown");
237         tps_singletons = NULL;
238 }
239
240 /* initialize the taskprocessor container and register CLI operations */
241 int ast_tps_init(void)
242 {
243         if (!(tps_singletons = ao2_container_alloc(TPS_MAX_BUCKETS, tps_hash_cb, tps_cmp_cb))) {
244                 ast_log(LOG_ERROR, "taskprocessor container failed to initialize!\n");
245                 return -1;
246         }
247
248         ast_cond_init(&cli_ping_cond, NULL);
249
250         ast_cli_register_multiple(taskprocessor_clis, ARRAY_LEN(taskprocessor_clis));
251
252         ast_register_atexit(tps_shutdown);
253
254         return 0;
255 }
256
257 /* allocate resources for the task */
258 static struct tps_task *tps_task_alloc(int (*task_exe)(void *datap), void *datap)
259 {
260         struct tps_task *t;
261         if ((t = ast_calloc(1, sizeof(*t)))) {
262                 t->execute = task_exe;
263                 t->datap = datap;
264         }
265         return t;
266 }
267
268 /* release task resources */
269 static void *tps_task_free(struct tps_task *task)
270 {
271         if (task) {
272                 ast_free(task);
273         }
274         return NULL;
275 }
276
277 /* taskprocessor tab completion */
278 static char *tps_taskprocessor_tab_complete(struct ast_taskprocessor *p, struct ast_cli_args *a)
279 {
280         int tklen;
281         int wordnum = 0;
282         char *name = NULL;
283         struct ao2_iterator i;
284
285         if (a->pos != 3)
286                 return NULL;
287
288         tklen = strlen(a->word);
289         i = ao2_iterator_init(tps_singletons, 0);
290         while ((p = ao2_iterator_next(&i))) {
291                 if (!strncasecmp(a->word, p->name, tklen) && ++wordnum > a->n) {
292                         name = ast_strdup(p->name);
293                         ao2_ref(p, -1);
294                         break;
295                 }
296                 ao2_ref(p, -1);
297         }
298         ao2_iterator_destroy(&i);
299         return name;
300 }
301
302 /* ping task handling function */
303 static int tps_ping_handler(void *datap)
304 {
305         ast_mutex_lock(&cli_ping_cond_lock);
306         ast_cond_signal(&cli_ping_cond);
307         ast_mutex_unlock(&cli_ping_cond_lock);
308         return 0;
309 }
310
311 /* ping the specified taskprocessor and display the ping time on the CLI */
312 static char *cli_tps_ping(struct ast_cli_entry *e, int cmd, struct ast_cli_args *a)
313 {
314         struct timeval begin, end, delta;
315         const char *name;
316         struct timeval when;
317         struct timespec ts;
318         struct ast_taskprocessor *tps = NULL;
319
320         switch (cmd) {
321         case CLI_INIT:
322                 e->command = "core ping taskprocessor";
323                 e->usage =
324                         "Usage: core ping taskprocessor <taskprocessor>\n"
325                         "       Displays the time required for a task to be processed\n";
326                 return NULL;
327         case CLI_GENERATE:
328                 return tps_taskprocessor_tab_complete(tps, a);
329         }
330
331         if (a->argc != 4)
332                 return CLI_SHOWUSAGE;
333
334         name = a->argv[3];
335         if (!(tps = ast_taskprocessor_get(name, TPS_REF_IF_EXISTS))) {
336                 ast_cli(a->fd, "\nping failed: %s not found\n\n", name);
337                 return CLI_SUCCESS;
338         }
339         ast_cli(a->fd, "\npinging %s ...", name);
340         when = ast_tvadd((begin = ast_tvnow()), ast_samp2tv(1000, 1000));
341         ts.tv_sec = when.tv_sec;
342         ts.tv_nsec = when.tv_usec * 1000;
343         ast_mutex_lock(&cli_ping_cond_lock);
344         if (ast_taskprocessor_push(tps, tps_ping_handler, 0) < 0) {
345                 ast_cli(a->fd, "\nping failed: could not push task to %s\n\n", name);
346                 ao2_ref(tps, -1);
347                 return CLI_FAILURE;
348         }
349         ast_cond_timedwait(&cli_ping_cond, &cli_ping_cond_lock, &ts);
350         ast_mutex_unlock(&cli_ping_cond_lock);
351         end = ast_tvnow();
352         delta = ast_tvsub(end, begin);
353         ast_cli(a->fd, "\n\t%24s ping time: %.1ld.%.6ld sec\n\n", name, (long)delta.tv_sec, (long int)delta.tv_usec);
354         ao2_ref(tps, -1);
355         return CLI_SUCCESS;
356 }
357
358 static char *cli_tps_report(struct ast_cli_entry *e, int cmd, struct ast_cli_args *a)
359 {
360         char name[256];
361         int tcount;
362         unsigned long qsize;
363         unsigned long maxqsize;
364         unsigned long processed;
365         struct ast_taskprocessor *p;
366         struct ao2_iterator i;
367
368         switch (cmd) {
369         case CLI_INIT:
370                 e->command = "core show taskprocessors";
371                 e->usage =
372                         "Usage: core show taskprocessors\n"
373                         "       Shows a list of instantiated task processors and their statistics\n";
374                 return NULL;
375         case CLI_GENERATE:
376                 return NULL;
377         }
378
379         if (a->argc != e->args)
380                 return CLI_SHOWUSAGE;
381
382         ast_cli(a->fd, "\n\t+----- Processor -----+--- Processed ---+- In Queue -+- Max Depth -+");
383         i = ao2_iterator_init(tps_singletons, 0);
384         while ((p = ao2_iterator_next(&i))) {
385                 ast_copy_string(name, p->name, sizeof(name));
386                 qsize = p->tps_queue_size;
387                 maxqsize = p->stats->max_qsize;
388                 processed = p->stats->_tasks_processed_count;
389                 ast_cli(a->fd, "\n%24s   %17ld %12ld %12ld", name, processed, qsize, maxqsize);
390                 ao2_ref(p, -1);
391         }
392         ao2_iterator_destroy(&i);
393         tcount = ao2_container_count(tps_singletons);
394         ast_cli(a->fd, "\n\t+---------------------+-----------------+------------+-------------+\n\t%d taskprocessors\n\n", tcount);
395         return CLI_SUCCESS;
396 }
397
398 /* hash callback for astobj2 */
399 static int tps_hash_cb(const void *obj, const int flags)
400 {
401         const struct ast_taskprocessor *tps = obj;
402         const char *name = flags & OBJ_KEY ? obj : tps->name;
403
404         return ast_str_case_hash(name);
405 }
406
407 /* compare callback for astobj2 */
408 static int tps_cmp_cb(void *obj, void *arg, int flags)
409 {
410         struct ast_taskprocessor *lhs = obj, *rhs = arg;
411         const char *rhsname = flags & OBJ_KEY ? arg : rhs->name;
412
413         return !strcasecmp(lhs->name, rhsname) ? CMP_MATCH | CMP_STOP : 0;
414 }
415
416 /* destroy the taskprocessor */
417 static void tps_taskprocessor_destroy(void *tps)
418 {
419         struct ast_taskprocessor *t = tps;
420         struct tps_task *task;
421
422         if (!tps) {
423                 ast_log(LOG_ERROR, "missing taskprocessor\n");
424                 return;
425         }
426         ast_debug(1, "destroying taskprocessor '%s'\n", t->name);
427         /* free it */
428         if (t->stats) {
429                 ast_free(t->stats);
430                 t->stats = NULL;
431         }
432         ast_free((char *) t->name);
433         if (t->listener) {
434                 /* This code should not be reached since the listener
435                  * should have been destroyed before the taskprocessor could
436                  * be destroyed
437                  */
438                 ao2_ref(t->listener, -1);
439                 t->listener = NULL;
440         }
441         while ((task = AST_LIST_REMOVE_HEAD(&t->tps_queue, list))) {
442                 tps_task_free(task);
443         }
444 }
445
446 /* pop the front task and return it */
447 static struct tps_task *tps_taskprocessor_pop(struct ast_taskprocessor *tps)
448 {
449         struct tps_task *task;
450         SCOPED_AO2LOCK(lock, tps);
451
452         if (tps->shutting_down) {
453                 return NULL;
454         }
455
456         if ((task = AST_LIST_REMOVE_HEAD(&tps->tps_queue, list))) {
457                 tps->tps_queue_size--;
458         }
459         return task;
460 }
461
462 static int tps_taskprocessor_depth(struct ast_taskprocessor *tps)
463 {
464         return (tps) ? tps->tps_queue_size : -1;
465 }
466
467 /* taskprocessor name accessor */
468 const char *ast_taskprocessor_name(struct ast_taskprocessor *tps)
469 {
470         if (!tps) {
471                 ast_log(LOG_ERROR, "no taskprocessor specified!\n");
472                 return NULL;
473         }
474         return tps->name;
475 }
476
477 static void listener_destroy(void *obj)
478 {
479         struct ast_taskprocessor_listener *listener = obj;
480
481         listener->callbacks->destroy(listener->private_data);
482 }
483
484 static void listener_shutdown(struct ast_taskprocessor_listener *listener)
485 {
486         listener->callbacks->shutdown(listener);
487         ao2_ref(listener->tps, -1);
488 }
489
490 struct ast_taskprocessor_listener *ast_taskprocessor_listener_alloc(const struct ast_taskprocessor_listener_callbacks *callbacks)
491 {
492         RAII_VAR(struct ast_taskprocessor_listener *, listener,
493                         ao2_alloc(sizeof(*listener), listener_destroy), ao2_cleanup);
494
495         if (!listener) {
496                 return NULL;
497         }
498         listener->callbacks = callbacks;
499
500         ao2_ref(listener, +1);
501         return listener;
502 }
503
504 /* Provide a reference to a taskprocessor.  Create the taskprocessor if necessary, but don't
505  * create the taskprocessor if we were told via ast_tps_options to return a reference only
506  * if it already exists */
507 struct ast_taskprocessor *ast_taskprocessor_get(const char *name, enum ast_tps_options create)
508 {
509         struct ast_taskprocessor *p;
510         struct ast_taskprocessor_listener *listener;
511
512         if (ast_strlen_zero(name)) {
513                 ast_log(LOG_ERROR, "requesting a nameless taskprocessor!!!\n");
514                 return NULL;
515         }
516         p = ao2_find(tps_singletons, name, OBJ_KEY);
517         if (p) {
518                 return p;
519         }
520         if (create & TPS_REF_IF_EXISTS) {
521                 /* calling function does not want a new taskprocessor to be created if it doesn't already exist */
522                 return NULL;
523         }
524         /* Create a new taskprocessor. Start by creating a default listener */
525         listener = ast_taskprocessor_listener_alloc(&default_listener_callbacks);
526         if (!listener) {
527                 return NULL;
528         }
529
530         p = ast_taskprocessor_create_with_listener(name, listener);
531         if (!p) {
532                 ao2_ref(listener, -1);
533                 return NULL;
534         }
535
536         /* Unref listener here since the taskprocessor has gained a reference to the listener */
537         ao2_ref(listener, -1);
538         return p;
539
540 }
541
542 struct ast_taskprocessor *ast_taskprocessor_create_with_listener(const char *name, struct ast_taskprocessor_listener *listener)
543 {
544         RAII_VAR(struct ast_taskprocessor *, p,
545                         ao2_alloc(sizeof(*p), tps_taskprocessor_destroy),
546                         ao2_cleanup);
547
548         if (!p) {
549                 ast_log(LOG_WARNING, "failed to create taskprocessor '%s'\n", name);
550                 return NULL;
551         }
552
553         if (!(p->stats = ast_calloc(1, sizeof(*p->stats)))) {
554                 ast_log(LOG_WARNING, "failed to create taskprocessor stats for '%s'\n", name);
555                 return NULL;
556         }
557         if (!(p->name = ast_strdup(name))) {
558                 ao2_ref(p, -1);
559                 return NULL;
560         }
561
562         ao2_ref(listener, +1);
563         p->listener = listener;
564
565         ao2_ref(p, +1);
566         listener->tps = p;
567
568         /* Allocation of private data must come after setting taskprocessor parameters
569          * so that listeners who rely on taskprocessor data will have access to it.
570          */
571         listener->private_data = listener->callbacks->alloc(listener);
572         if (!listener->private_data) {
573                 return NULL;
574         }
575
576         if (!(ao2_link(tps_singletons, p))) {
577                 ast_log(LOG_ERROR, "Failed to add taskprocessor '%s' to container\n", p->name);
578                 return NULL;
579         }
580
581         if (p->listener->callbacks->start(p->listener)) {
582                 ast_log(LOG_ERROR, "Unable to start taskprocessor listener for taskprocessor %s\n", p->name);
583                 ast_taskprocessor_unreference(p);
584                 return NULL;
585         }
586
587         /* RAII_VAR will decrement the refcount at the end of the function.
588          * Since we want to pass back a reference to p, we bump the refcount
589          */
590         ao2_ref(p, +1);
591         return p;
592 }
593
594 /* decrement the taskprocessor reference count and unlink from the container if necessary */
595 void *ast_taskprocessor_unreference(struct ast_taskprocessor *tps)
596 {
597         if (!tps) {
598                 return NULL;
599         }
600
601         if (ao2_ref(tps, -1) > 3) {
602                 return NULL;
603         }
604         /* If we're down to 3 references, then those must be:
605          * 1. The reference we just got rid of
606          * 2. The container
607          * 3. The listener
608          */
609         ao2_unlink(tps_singletons, tps);
610         listener_shutdown(tps->listener);
611         return NULL;
612 }
613
614 /* push the task into the taskprocessor queue */
615 int ast_taskprocessor_push(struct ast_taskprocessor *tps, int (*task_exe)(void *datap), void *datap)
616 {
617         struct tps_task *t;
618         int previous_size;
619
620         if (!tps || !task_exe) {
621                 ast_log(LOG_ERROR, "%s is missing!!\n", (tps) ? "task callback" : "taskprocessor");
622                 return -1;
623         }
624         if (!(t = tps_task_alloc(task_exe, datap))) {
625                 ast_log(LOG_ERROR, "failed to allocate task!  Can't push to '%s'\n", tps->name);
626                 return -1;
627         }
628         ao2_lock(tps);
629         AST_LIST_INSERT_TAIL(&tps->tps_queue, t, list);
630         previous_size = tps->tps_queue_size++;
631         ao2_unlock(tps);
632         tps->listener->callbacks->task_pushed(tps->listener, previous_size ? 0 : 1);
633         return 0;
634 }
635
636 int ast_taskprocessor_execute(struct ast_taskprocessor *tps)
637 {
638         struct tps_task *t;
639         int size;
640
641         if (!(t = tps_taskprocessor_pop(tps))) {
642                 return 0;
643         }
644
645         t->execute(t->datap);
646
647         tps_task_free(t);
648
649         ao2_lock(tps);
650         size = tps_taskprocessor_depth(tps);
651         if (tps->stats) {
652                 tps->stats->_tasks_processed_count++;
653                 if (size > tps->stats->max_qsize) {
654                         tps->stats->max_qsize = size;
655                 }
656         }
657         ao2_unlock(tps);
658
659         if (size == 0) {
660                 tps->listener->callbacks->emptied(tps->listener);
661                 return 0;
662         }
663         return 1;
664 }