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