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