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