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