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