gst/gstinfo.c

   1 /* GStreamer
   2  * Copyright (C) 1999,2000 Erik Walthinsen <omega@cse.ogi.edu>
   3  *                    2000 Wim Taymans <wtay@chello.be>
   4  *                    2003 Benjamin Otte <in7y118@public.uni-hamburg.de>
   5  *
   6  * gstinfo.c: debugging functions
   7  *
   8  * This library is free software; you can redistribute it and/or
   9  * modify it under the terms of the GNU Library General Public
  10  * License as published by the Free Software Foundation; either
  11  * version 2 of the License, or (at your option) any later version.
  12  *
  13  * This library is distributed in the hope that it will be useful,
  14  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  15  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  16  * Library General Public License for more details.
  17  *
  18  * You should have received a copy of the GNU Library General Public
  19  * License along with this library; if not, write to the
  20  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  21  * Boston, MA 02111-1307, USA.
  22  */
  23 /**
  24  * SECTION:gstinfo
  25  * @short_description: Debugging and logging facillities
  26  * @see_also: #GstConfig, #Gst for command line parameters
  27  * and environment variables that affect the debugging output.
  28  *
  29  * GStreamer's debugging subsystem is an easy way to get information about what
  30  * the application is doing.
  31  * It is not meant for programming errors. Use GLibs methods (g_warning and so
  32  * on for that.
  33  *
  34  * The debugging subsystem works only after GStreamer has been initilized
  35  * - for example by calling gst_init().
  36  *
  37  * The debugging subsystem is used to log informational messages while the
  38  * application runs.
  39  * Each messages has some properties attached to it. Among these properties
  40  * are the debugging category, the severity (called "level" here) and an obtional
  41  * #GObject it belongs to. Each of these messages is sent to all registered
  42  * debugging handlers, which then handle the messages. GStreamer attaches a
  43  * default handler on startup, which outputs requested messages to stderr.
  44  *
  45  * Messages are output by using shortcut macros like #GST_DEBUG,
  46  * #GST_CAT_ERROR_OBJECT or similar. These all expand to calling gst_debug_log()
  47  * with the right parameters.
  48  * The only thing a developer will probably want to do is define his own
  49  * categories. This is easily done with 3 lines. At the top of your code, declare
  50  * the variables and set the default category.
  51  * <informalexample>
  52  * <programlisting>
  53  * GST_DEBUG_CATEGORY (my_category);    // define category
  54  * &hash;define GST_CAT_DEFAULT my_category     // set as default
  55  * </programlisting>
  56  * </informalexample>
  57  * After that you only need to initialize the category.
  58  * <informalexample>
  59  * <programlisting>
  60  * GST_DEBUG_CATEGORY_INIT (my_category, "my category", 0, "This is my very own");
  61  * </programlisting>
  62  * </informalexample>
  63  * Initialization must be done before the category is used first. Plugins do this
  64  * in their plugin_init function, libraries and applications should do that
  65  * during their initialization.
  66  *
  67  * The whole debugging subsystem can be disabled at build time with passing the
  68  * --disable-gst-debug switch to configure. If this is done, every function, macro
  69  * and even structs described in this file evaluate to default values or nothing
  70  * at all. So don't take addresses of these functions or use other tricks.
  71  * If you must do that for some reason, there is still an option. If the debugging
  72  * subsystem was compiled out, #GST_DISABLE_GST_DEBUG is defined in &lt;gst/gst.h&gt;,
  73  * so you can check that before doing your trick.
  74  * Disabling the debugging subsystem will give you a slight (read: unnoticable)
  75  * speed increase and will reduce the size of your compiled code. The GStreamer
  76  * library itself becomes around 10% smaller.
  77  *
  78  * Please note that there are naming conventions for the names of debugging
  79  * categories. These are explained at GST_DEBUG_CATEGORY_INIT().
  80  */
  81
  82 #include "gst_private.h"
  83 #include "gstinfo.h"
  84
  85 #ifndef GST_DISABLE_GST_DEBUG
  86
  87 #ifdef HAVE_DLFCN_H
  88 #include <dlfcn.h>
  89 #endif
  90 #ifdef HAVE_PRINTF_EXTENSION
  91 #include <printf.h>
  92 #endif
  93 #include <stdio.h>              /* fprintf */
  94 #ifdef HAVE_UNISTD_H
  95 #include <unistd.h>
  96 #endif
  97 #include <string.h>             /* G_VA_COPY */
  98 #include "gst_private.h"
  99 #include "gstutils.h"
 100 #ifdef HAVE_VALGRIND
 101 #include <valgrind/valgrind.h>
 102 #endif
 103
 104 /* underscore is to prevent conflict with GST_CAT_DEBUG define */
 105 GST_DEBUG_CATEGORY_STATIC (_GST_CAT_DEBUG);
 106 /* time of initialization, so we get useful debugging output times */
 107 GstClockTime start_time;
 108
 109 #if 0
 110 #if defined __sgi__
 111 #include <rld_interface.h>
 112 typedef struct DL_INFO
 113 {
 114   const char *dli_fname;
 115   void *dli_fbase;
 116   const char *dli_sname;
 117   void *dli_saddr;
 118   int dli_version;
 119   int dli_reserved1;
 120   long dli_reserved[4];
 121 }
 122 Dl_info;
 123
 124 #define _RLD_DLADDR             14
 125 int dladdr (void *address, Dl_info * dl);
 126
 127 int
 128 dladdr (void *address, Dl_info * dl)
 129 {
 130   void *v;
 131
 132   v = _rld_new_interface (_RLD_DLADDR, address, dl);
 133   return (int) v;
 134 }
 135 #endif /* __sgi__ */
 136 #endif
 137
 138 static void gst_debug_reset_threshold (gpointer category, gpointer unused);
 139 static void gst_debug_reset_all_thresholds (void);
 140
 141 #ifdef HAVE_PRINTF_EXTENSION
 142 static int _gst_info_printf_extension (FILE * stream,
 143     const struct printf_info *info, const void *const *args);
 144 static int _gst_info_printf_extension_arginfo (const struct printf_info *info,
 145     size_t n, int *argtypes);
 146 #endif
 147
 148 struct _GstDebugMessage
 149 {
 150   gchar *message;
 151   const gchar *format;
 152   va_list arguments;
 153 };
 154
 155 /* list of all name/level pairs from --gst-debug and GST_DEBUG */
 156 static GStaticMutex __level_name_mutex = G_STATIC_MUTEX_INIT;
 157 static GSList *__level_name = NULL;
 158 typedef struct
 159 {
 160   GPatternSpec *pat;
 161   GstDebugLevel level;
 162 }
 163 LevelNameEntry;
 164
 165 /* list of all categories */
 166 static GStaticMutex __cat_mutex = G_STATIC_MUTEX_INIT;
 167 static GSList *__categories = NULL;
 168
 169 /* all registered debug handlers */
 170 typedef struct
 171 {
 172   GstLogFunction func;
 173   gpointer user_data;
 174 }
 175 LogFuncEntry;
 176 static GStaticMutex __log_func_mutex = G_STATIC_MUTEX_INIT;
 177 static GSList *__log_functions = NULL;
 178
 179 static gint __default_level;
 180 static gint __use_color;
 181 gboolean __gst_debug_enabled = TRUE;
 182
 183
 184 GstDebugCategory *GST_CAT_DEFAULT = NULL;
 185
 186 GstDebugCategory *GST_CAT_GST_INIT = NULL;
 187 GstDebugCategory *GST_CAT_AUTOPLUG = NULL;
 188 GstDebugCategory *GST_CAT_AUTOPLUG_ATTEMPT = NULL;
 189 GstDebugCategory *GST_CAT_PARENTAGE = NULL;
 190 GstDebugCategory *GST_CAT_STATES = NULL;
 191 GstDebugCategory *GST_CAT_SCHEDULING = NULL;
 192
 193 GstDebugCategory *GST_CAT_BUFFER = NULL;
 194 GstDebugCategory *GST_CAT_CAPS = NULL;
 195 GstDebugCategory *GST_CAT_CLOCK = NULL;
 196 GstDebugCategory *GST_CAT_ELEMENT_PADS = NULL;
 197 GstDebugCategory *GST_CAT_PADS = NULL;
 198 GstDebugCategory *GST_CAT_PIPELINE = NULL;
 199 GstDebugCategory *GST_CAT_PLUGIN_LOADING = NULL;
 200 GstDebugCategory *GST_CAT_PLUGIN_INFO = NULL;
 201 GstDebugCategory *GST_CAT_PROPERTIES = NULL;
 202 GstDebugCategory *GST_CAT_THREAD = NULL;
 203 GstDebugCategory *GST_CAT_TYPES = NULL;
 204 GstDebugCategory *GST_CAT_XML = NULL;
 205 GstDebugCategory *GST_CAT_NEGOTIATION = NULL;
 206 GstDebugCategory *GST_CAT_REFCOUNTING = NULL;
 207 GstDebugCategory *GST_CAT_ERROR_SYSTEM = NULL;
 208 GstDebugCategory *GST_CAT_EVENT = NULL;
 209 GstDebugCategory *GST_CAT_MESSAGE = NULL;
 210 GstDebugCategory *GST_CAT_PARAMS = NULL;
 211 GstDebugCategory *GST_CAT_CALL_TRACE = NULL;
 212 GstDebugCategory *GST_CAT_SIGNAL = NULL;
 213 GstDebugCategory *GST_CAT_PROBE = NULL;
 214 GstDebugCategory *GST_CAT_REGISTRY = NULL;
 215
 216 /* FIXME: export this? */
 217 gboolean
 218 __gst_in_valgrind (void)
 219 {
 220   static enum
 221   {
 222     GST_VG_UNCHECKED,
 223     GST_VG_NO_VALGRIND,
 224     GST_VG_INSIDE
 225   }
 226   in_valgrind = GST_VG_UNCHECKED;
 227
 228   if (in_valgrind == GST_VG_UNCHECKED) {
 229 #ifdef HAVE_VALGRIND
 230     if (RUNNING_ON_VALGRIND) {
 231       GST_CAT_INFO (GST_CAT_GST_INIT, "we're running inside valgrind");
 232       VALGRIND_PRINTF
 233           ("GStreamer has detected that it is running inside valgrind.");
 234       VALGRIND_PRINTF
 235           ("It might now take different code paths to ease debugging.");
 236       VALGRIND_PRINTF ("Of course, this may also lead to different bugs.");
 237       in_valgrind = GST_VG_INSIDE;
 238     } else {
 239       GST_CAT_LOG (GST_CAT_GST_INIT, "not doing extra valgrind stuff");
 240       in_valgrind = GST_VG_NO_VALGRIND;
 241     }
 242 #else
 243     in_valgrind = GST_VG_NO_VALGRIND;
 244 #endif
 245     g_assert (in_valgrind == GST_VG_NO_VALGRIND ||
 246         in_valgrind == GST_VG_INSIDE);
 247   }
 248   return (in_valgrind == GST_VG_INSIDE) ? TRUE : FALSE;
 249 }
 250
 251 /**
 252  * _gst_debug_init:
 253  *
 254  * Initializes the debugging system.
 255  * Normally you don't want to call this, because gst_init does it for you.
 256  */
 257 void
 258 _gst_debug_init (void)
 259 {
 260   GTimeVal current;
 261
 262   gst_atomic_int_set (&__default_level, GST_LEVEL_DEFAULT);
 263   gst_atomic_int_set (&__use_color, 1);
 264
 265   /* get time we started for debugging messages */
 266   g_get_current_time (&current);
 267   start_time = GST_TIMEVAL_TO_TIME (current);
 268
 269 #ifdef HAVE_PRINTF_EXTENSION
 270   register_printf_function (GST_PTR_FORMAT[0], _gst_info_printf_extension,
 271       _gst_info_printf_extension_arginfo);
 272 #endif
 273
 274   /* do NOT use a single debug function before this line has been run */
 275   GST_CAT_DEFAULT = _gst_debug_category_new ("default",
 276       GST_DEBUG_UNDERLINE, NULL);
 277   _GST_CAT_DEBUG = _gst_debug_category_new ("GST_DEBUG",
 278       GST_DEBUG_BOLD | GST_DEBUG_FG_YELLOW, "debugging subsystem");
 279
 280   gst_debug_add_log_function (gst_debug_log_default, NULL);
 281
 282   /* FIXME: add descriptions here */
 283   GST_CAT_GST_INIT = _gst_debug_category_new ("GST_INIT",
 284       GST_DEBUG_BOLD | GST_DEBUG_FG_RED, NULL);
 285   GST_CAT_AUTOPLUG = _gst_debug_category_new ("GST_AUTOPLUG",
 286       GST_DEBUG_BOLD | GST_DEBUG_FG_BLUE, NULL);
 287   GST_CAT_AUTOPLUG_ATTEMPT = _gst_debug_category_new ("GST_AUTOPLUG_ATTEMPT",
 288       GST_DEBUG_BOLD | GST_DEBUG_FG_CYAN | GST_DEBUG_BG_BLUE, NULL);
 289   GST_CAT_PARENTAGE = _gst_debug_category_new ("GST_PARENTAGE",
 290       GST_DEBUG_BOLD | GST_DEBUG_FG_WHITE | GST_DEBUG_BG_RED, NULL);
 291   GST_CAT_STATES = _gst_debug_category_new ("GST_STATES",
 292       GST_DEBUG_BOLD | GST_DEBUG_FG_RED, NULL);
 293   GST_CAT_SCHEDULING = _gst_debug_category_new ("GST_SCHEDULING",
 294       GST_DEBUG_BOLD | GST_DEBUG_FG_MAGENTA, NULL);
 295   GST_CAT_BUFFER = _gst_debug_category_new ("GST_BUFFER",
 296       GST_DEBUG_BOLD | GST_DEBUG_FG_GREEN, NULL);
 297   GST_CAT_CAPS = _gst_debug_category_new ("GST_CAPS",
 298       GST_DEBUG_BOLD | GST_DEBUG_FG_BLUE, NULL);
 299   GST_CAT_CLOCK = _gst_debug_category_new ("GST_CLOCK",
 300       GST_DEBUG_BOLD | GST_DEBUG_FG_YELLOW, NULL);
 301   GST_CAT_ELEMENT_PADS = _gst_debug_category_new ("GST_ELEMENT_PADS",
 302       GST_DEBUG_BOLD | GST_DEBUG_FG_WHITE | GST_DEBUG_BG_RED, NULL);
 303   GST_CAT_PADS = _gst_debug_category_new ("GST_PADS",
 304       GST_DEBUG_BOLD | GST_DEBUG_FG_WHITE | GST_DEBUG_BG_RED, NULL);
 305   GST_CAT_PIPELINE = _gst_debug_category_new ("GST_PIPELINE",
 306       GST_DEBUG_BOLD | GST_DEBUG_FG_WHITE | GST_DEBUG_BG_RED, NULL);
 307   GST_CAT_PLUGIN_LOADING = _gst_debug_category_new ("GST_PLUGIN_LOADING",
 308       GST_DEBUG_BOLD | GST_DEBUG_FG_CYAN, NULL);
 309   GST_CAT_PLUGIN_INFO = _gst_debug_category_new ("GST_PLUGIN_INFO",
 310       GST_DEBUG_BOLD | GST_DEBUG_FG_CYAN, NULL);
 311   GST_CAT_PROPERTIES = _gst_debug_category_new ("GST_PROPERTIES",
 312       GST_DEBUG_BOLD | GST_DEBUG_FG_WHITE | GST_DEBUG_BG_BLUE, NULL);
 313   GST_CAT_THREAD = _gst_debug_category_new ("GST_THREAD",
 314       GST_DEBUG_BOLD | GST_DEBUG_FG_RED, NULL);
 315   GST_CAT_TYPES = _gst_debug_category_new ("GST_TYPES",
 316       GST_DEBUG_BOLD | GST_DEBUG_FG_WHITE | GST_DEBUG_BG_RED, NULL);
 317   GST_CAT_XML = _gst_debug_category_new ("GST_XML",
 318       GST_DEBUG_BOLD | GST_DEBUG_FG_WHITE | GST_DEBUG_BG_RED, NULL);
 319   GST_CAT_NEGOTIATION = _gst_debug_category_new ("GST_NEGOTIATION",
 320       GST_DEBUG_BOLD | GST_DEBUG_FG_BLUE, NULL);
 321   GST_CAT_REFCOUNTING = _gst_debug_category_new ("GST_REFCOUNTING",
 322       GST_DEBUG_BOLD | GST_DEBUG_FG_RED | GST_DEBUG_BG_BLUE, NULL);
 323   GST_CAT_ERROR_SYSTEM = _gst_debug_category_new ("GST_ERROR_SYSTEM",
 324       GST_DEBUG_BOLD | GST_DEBUG_FG_RED | GST_DEBUG_BG_WHITE, NULL);
 325
 326   GST_CAT_EVENT = _gst_debug_category_new ("GST_EVENT",
 327       GST_DEBUG_BOLD | GST_DEBUG_FG_BLUE, NULL);
 328   GST_CAT_MESSAGE = _gst_debug_category_new ("GST_MESSAGE",
 329       GST_DEBUG_BOLD | GST_DEBUG_FG_WHITE | GST_DEBUG_BG_RED, NULL);
 330   GST_CAT_PARAMS = _gst_debug_category_new ("GST_PARAMS",
 331       GST_DEBUG_BOLD | GST_DEBUG_FG_BLACK | GST_DEBUG_BG_YELLOW, NULL);
 332   GST_CAT_CALL_TRACE = _gst_debug_category_new ("GST_CALL_TRACE",
 333       GST_DEBUG_BOLD, NULL);
 334   GST_CAT_SIGNAL = _gst_debug_category_new ("GST_SIGNAL",
 335       GST_DEBUG_BOLD | GST_DEBUG_FG_WHITE | GST_DEBUG_BG_RED, NULL);
 336   GST_CAT_PROBE = _gst_debug_category_new ("GST_PROBE",
 337       GST_DEBUG_BOLD | GST_DEBUG_FG_GREEN, "pad probes");
 338   GST_CAT_REGISTRY = _gst_debug_category_new ("GST_REGISTRY", 0, "registry");
 339
 340
 341   /* print out the valgrind message if we're in valgrind */
 342   __gst_in_valgrind ();
 343 }
 344
 345 /* we can't do this further above, because we initialize the GST_CAT_DEFAULT struct */
 346 #define GST_CAT_DEFAULT _GST_CAT_DEBUG
 347
 348 /**
 349  * gst_debug_log:
 350  * @category: category to log
 351  * @level: level of the message is in
 352  * @file: the file that emitted the message, usually the __FILE__ identifier
 353  * @function: the function that emitted the message
 354  * @line: the line from that the message was emitted, usually __LINE__
 355  * @object: the object this message relates to or NULL if none
 356  * @format: a printf style format string
 357  * @...: optional arguments for the format
 358  *
 359  * Logs the given message using the currently registered debugging handlers.
 360  */
 361 void
 362 gst_debug_log (GstDebugCategory * category, GstDebugLevel level,
 363     const gchar * file, const gchar * function, gint line,
 364     GObject * object, const gchar * format, ...)
 365 {
 366   va_list var_args;
 367
 368   va_start (var_args, format);
 369   gst_debug_log_valist (category, level, file, function, line, object, format,
 370       var_args);
 371   va_end (var_args);
 372 }
 373
 374 /**
 375  * gst_debug_log_valist:
 376  * @category: category to log
 377  * @level: level of the message is in
 378  * @file: the file that emitted the message, usually the __FILE__ identifier
 379  * @function: the function that emitted the message
 380  * @line: the line from that the message was emitted, usually __LINE__
 381  * @object: the object this message relates to or NULL if none
 382  * @format: a printf style format string
 383  * @args: optional arguments for the format
 384  *
 385  * Logs the given message using the currently registered debugging handlers.
 386  */
 387 void
 388 gst_debug_log_valist (GstDebugCategory * category, GstDebugLevel level,
 389     const gchar * file, const gchar * function, gint line,
 390     GObject * object, const gchar * format, va_list args)
 391 {
 392   GstDebugMessage message;
 393   LogFuncEntry *entry;
 394   GSList *handler;
 395
 396   g_return_if_fail (category != NULL);
 397   g_return_if_fail (file != NULL);
 398   g_return_if_fail (function != NULL);
 399   g_return_if_fail (format != NULL);
 400
 401   message.message = NULL;
 402   message.format = format;
 403   G_VA_COPY (message.arguments, args);
 404
 405   handler = __log_functions;
 406   while (handler) {
 407     entry = handler->data;
 408     handler = g_slist_next (handler);
 409     entry->func (category, level, file, function, line, object, &message,
 410         entry->user_data);
 411   }
 412   g_free (message.message);
 413   va_end (message.arguments);
 414 }
 415
 416 /**
 417  * gst_debug_message_get:
 418  * @message: a debug message
 419  *
 420  * Gets the string representation of a #GstDebugMessage. This function is used
 421  * in debug handlers to extract the message.
 422  *
 423  * Returns: the string representation of a #GstDebugMessage.
 424  */
 425 const gchar *
 426 gst_debug_message_get (GstDebugMessage * message)
 427 {
 428   if (message->message == NULL) {
 429     message->message = g_strdup_vprintf (message->format, message->arguments);
 430   }
 431   return message->message;
 432 }
 433
 434
 435 static gchar *
 436 gst_debug_print_object (gpointer ptr)
 437 {
 438   GObject *object = (GObject *) ptr;
 439
 440 #ifdef unused
 441   /* This is a cute trick to detect unmapped memory, but is unportable,
 442    * slow, screws around with madvise, and not actually that useful. */
 443   {
 444     int ret;
 445
 446     ret = madvise ((void *) ((unsigned long) ptr & (~0xfff)), 4096, 0);
 447     if (ret == -1 && errno == ENOMEM) {
 448       buffer = g_strdup_printf ("%p (unmapped memory)", ptr);
 449     }
 450   }
 451 #endif
 452
 453   /* nicely printed object */
 454   if (object == NULL) {
 455     return g_strdup ("(NULL)");
 456   }
 457   if (*(GType *) ptr == GST_TYPE_CAPS) {
 458     return gst_caps_to_string ((GstCaps *) ptr);
 459   }
 460   if (*(GType *) ptr == GST_TYPE_STRUCTURE) {
 461     return gst_structure_to_string ((GstStructure *) ptr);
 462   }
 463 #ifdef USE_POISONING
 464   if (*(guint32 *) ptr == 0xffffffff) {
 465     return g_strdup_printf ("<poisoned@%p>", ptr);
 466   }
 467 #endif
 468   if (GST_IS_PAD (object) && GST_OBJECT_NAME (object)) {
 469     return g_strdup_printf ("<%s:%s>", GST_DEBUG_PAD_NAME (object));
 470   }
 471   if (GST_IS_OBJECT (object) && GST_OBJECT_NAME (object)) {
 472     return g_strdup_printf ("<%s>", GST_OBJECT_NAME (object));
 473   }
 474   if (G_IS_OBJECT (object)) {
 475     return g_strdup_printf ("<%s@%p>", G_OBJECT_TYPE_NAME (object), object);
 476   }
 477
 478   return g_strdup_printf ("%p", ptr);
 479 }
 480
 481 /**
 482  * gst_debug_construct_term_color:
 483  * @colorinfo: the color info
 484  *
 485  * Constructs a string that can be used for getting the desired color in color
 486  * terminals.
 487  * You need to free the string after use.
 488  *
 489  * Returns: a string containing the color definition
 490  */
 491 gchar *
 492 gst_debug_construct_term_color (guint colorinfo)
 493 {
 494   GString *color;
 495   gchar *ret;
 496
 497   color = g_string_new ("\033[00");
 498
 499   if (colorinfo & GST_DEBUG_BOLD) {
 500     g_string_append (color, ";01");
 501   }
 502   if (colorinfo & GST_DEBUG_UNDERLINE) {
 503     g_string_append (color, ";04");
 504   }
 505   if (colorinfo & GST_DEBUG_FG_MASK) {
 506     g_string_append_printf (color, ";3%1d", colorinfo & GST_DEBUG_FG_MASK);
 507   }
 508   if (colorinfo & GST_DEBUG_BG_MASK) {
 509     g_string_append_printf (color, ";4%1d",
 510         (colorinfo & GST_DEBUG_BG_MASK) >> 4);
 511   }
 512   g_string_append (color, "m");
 513
 514   ret = color->str;
 515   g_string_free (color, FALSE);
 516   return ret;
 517 }
 518
 519 /**
 520  * gst_debug_log_default:
 521  * @category: category to log
 522  * @level: level of the message
 523  * @file: the file that emitted the message, usually the __FILE__ identifier
 524  * @function: the function that emitted the message
 525  * @line: the line from that the message was emitted, usually __LINE__
 526  * @message: the actual message
 527  * @object: the object this message relates to or NULL if none
 528  * @unused: an unused variable, reserved for some user_data.
 529  *
 530  * The default logging handler used by GStreamer. Logging functions get called
 531  * whenever a macro like GST_DEBUG or similar is used. This function outputs the
 532  * message and additional info using the glib error handler.
 533  * You can add other handlers by using #gst_debug_add_log_function.
 534  * And you can remove this handler by calling
 535  * gst_debug_remove_log_function (gst_debug_log_default);
 536  */
 537 void
 538 gst_debug_log_default (GstDebugCategory * category, GstDebugLevel level,
 539     const gchar * file, const gchar * function, gint line,
 540     GObject * object, GstDebugMessage * message, gpointer unused)
 541 {
 542   gchar *color;
 543   gchar *clear;
 544   gchar *obj;
 545   gchar *pidcolor;
 546   gint pid;
 547   GTimeVal now;
 548   GstClockTime elapsed;
 549
 550   if (level > gst_debug_category_get_threshold (category))
 551     return;
 552
 553   pid = getpid ();
 554
 555   /* color info */
 556   if (gst_debug_is_colored ()) {
 557     color =
 558         gst_debug_construct_term_color (gst_debug_category_get_color
 559         (category));
 560     clear = "\033[00m";
 561     pidcolor = g_strdup_printf ("\033[3%1dm", pid % 6 + 31);
 562   } else {
 563     color = g_strdup ("");
 564     clear = "";
 565     pidcolor = g_strdup ("");
 566   }
 567
 568   obj = object ? gst_debug_print_object (object) : g_strdup ("");
 569
 570   g_get_current_time (&now);
 571   elapsed = GST_TIMEVAL_TO_TIME (now) - start_time;
 572   g_printerr ("%s (%p - %" GST_TIME_FORMAT
 573       ") %s%15s%s(%s%5d%s) %s%s(%d):%s:%s%s %s\n",
 574       gst_debug_level_get_name (level), g_thread_self (),
 575       GST_TIME_ARGS (elapsed), color,
 576       gst_debug_category_get_name (category), clear, pidcolor, pid, clear,
 577       color, file, line, function, obj, clear, gst_debug_message_get (message));
 578
 579   g_free (color);
 580   g_free (pidcolor);
 581   g_free (obj);
 582 }
 583
 584 /**
 585  * gst_debug_level_get_name:
 586  * @level: the level to get the name for
 587  *
 588  * Get the string trepresentation of a debugging level
 589  *
 590  * Returns: the name
 591  */
 592 const gchar *
 593 gst_debug_level_get_name (GstDebugLevel level)
 594 {
 595   switch (level) {
 596     case GST_LEVEL_NONE:
 597       return "";
 598     case GST_LEVEL_ERROR:
 599       return "ERROR";
 600     case GST_LEVEL_WARNING:
 601       return "WARN ";
 602     case GST_LEVEL_INFO:
 603       return "INFO ";
 604     case GST_LEVEL_DEBUG:
 605       return "DEBUG";
 606     case GST_LEVEL_LOG:
 607       return "LOG  ";
 608     default:
 609       g_warning ("invalid level specified for gst_debug_level_get_name");
 610       return "";
 611   }
 612 }
 613
 614 /**
 615  * gst_debug_add_log_function:
 616  * @func: the function to use
 617  * @data: user data
 618  *
 619  * Adds the logging function to the list of logging functions.
 620  * Be sure to use G_GNUC_NO_INSTRUMENT on that function, it is needed.
 621  */
 622 void
 623 gst_debug_add_log_function (GstLogFunction func, gpointer data)
 624 {
 625   LogFuncEntry *entry;
 626   GSList *list;
 627
 628   g_return_if_fail (func != NULL);
 629
 630   entry = g_new (LogFuncEntry, 1);
 631   entry->func = func;
 632   entry->user_data = data;
 633   /* FIXME: we leak the old list here - other threads might access it right now
 634    * in gst_debug_logv. Another solution is to lock the mutex in gst_debug_logv,
 635    * but that is waaay costly.
 636    * It'd probably be clever to use some kind of RCU here, but I don't know
 637    * anything about that.
 638    */
 639   g_static_mutex_lock (&__log_func_mutex);
 640   list = g_slist_copy (__log_functions);
 641   __log_functions = g_slist_prepend (list, entry);
 642   g_static_mutex_unlock (&__log_func_mutex);
 643
 644   GST_DEBUG ("prepended log function %p (user data %p) to log functions",
 645       func, data);
 646 }
 647
 648 static gint
 649 gst_debug_compare_log_function_by_func (gconstpointer entry, gconstpointer func)
 650 {
 651   gpointer entryfunc = ((LogFuncEntry *) entry)->func;
 652
 653   return (entryfunc < func) ? -1 : (entryfunc > func) ? 1 : 0;
 654 }
 655
 656 static gint
 657 gst_debug_compare_log_function_by_data (gconstpointer entry, gconstpointer data)
 658 {
 659   gpointer entrydata = ((LogFuncEntry *) entry)->user_data;
 660
 661   return (entrydata < data) ? -1 : (entrydata > data) ? 1 : 0;
 662 }
 663
 664 static guint
 665 gst_debug_remove_with_compare_func (GCompareFunc func, gpointer data)
 666 {
 667   GSList *found;
 668   GSList *new;
 669   guint removals = 0;
 670
 671   g_static_mutex_lock (&__log_func_mutex);
 672   new = __log_functions;
 673   while ((found = g_slist_find_custom (new, data, func))) {
 674     if (new == __log_functions) {
 675       new = g_slist_copy (new);
 676       continue;
 677     }
 678     g_free (found->data);
 679     new = g_slist_delete_link (new, found);
 680     removals++;
 681   }
 682   /* FIXME: We leak the old list here. See _add_log_function for why. */
 683   __log_functions = new;
 684   g_static_mutex_unlock (&__log_func_mutex);
 685
 686   return removals;
 687 }
 688
 689 /**
 690  * gst_debug_remove_log_function:
 691  * @func: the log function to remove
 692  *
 693  * Removes all registrered instances of the given logging functions.
 694  *
 695  * Returns: How many instances of the function were removed
 696  */
 697 guint
 698 gst_debug_remove_log_function (GstLogFunction func)
 699 {
 700   guint removals;
 701
 702   g_return_val_if_fail (func != NULL, 0);
 703
 704   removals =
 705       gst_debug_remove_with_compare_func
 706       (gst_debug_compare_log_function_by_func, func);
 707   GST_DEBUG ("removed log function %p %d times from log function list", func,
 708       removals);
 709
 710   return removals;
 711 }
 712
 713 /**
 714  * gst_debug_remove_log_function_by_data:
 715  * @data: user data of the log function to remove
 716  *
 717  * Removes all registrered instances of log functions with the given user data.
 718  *
 719  * Returns: How many instances of the function were removed
 720  */
 721 guint
 722 gst_debug_remove_log_function_by_data (gpointer data)
 723 {
 724   guint removals;
 725
 726   removals =
 727       gst_debug_remove_with_compare_func
 728       (gst_debug_compare_log_function_by_data, data);
 729   GST_DEBUG
 730       ("removed %d log functions with user data %p from log function list",
 731       removals, data);
 732
 733   return removals;
 734 }
 735
 736 /**
 737  * gst_debug_set_colored:
 738  * @colored: Whether to use colored output or not
 739  *
 740  * Sets or unsets the use of coloured debugging output.
 741  */
 742 void
 743 gst_debug_set_colored (gboolean colored)
 744 {
 745   gst_atomic_int_set (&__use_color, colored ? 1 : 0);
 746 }
 747
 748 /**
 749  * gst_debug_is_colored:
 750  *
 751  * Checks if the debugging output should be colored.
 752  *
 753  * Returns: TRUE, if the debug output should be colored.
 754  */
 755 gboolean
 756 gst_debug_is_colored (void)
 757 {
 758   return g_atomic_int_get (&__use_color) == 0 ? FALSE : TRUE;
 759 }
 760
 761 /**
 762  * gst_debug_set_active:
 763  * @active: Whether to use debugging output or not
 764  *
 765  * If activated, debugging messages are sent to the debugging
 766  * handlers.
 767  * It makes sense to deactivate it for speed issues.
 768  * <note><para>This function is not threadsafe. It makes sense to only call it
 769  * during initialization.</para></note>
 770  */
 771 void
 772 gst_debug_set_active (gboolean active)
 773 {
 774   __gst_debug_enabled = active;
 775 }
 776
 777 /**
 778  * gst_debug_is_active:
 779  *
 780  * Checks if debugging output is activated.
 781  *
 782  * Returns: TRUE, if debugging is activated
 783  */
 784 gboolean
 785 gst_debug_is_active (void)
 786 {
 787   return __gst_debug_enabled;
 788 }
 789
 790 /**
 791  * gst_debug_set_default_threshold:
 792  * @level: level to set
 793  *
 794  * Sets the default threshold to the given level and updates all categories to
 795  * use this threshold.
 796  */
 797 void
 798 gst_debug_set_default_threshold (GstDebugLevel level)
 799 {
 800   gst_atomic_int_set (&__default_level, level);
 801   gst_debug_reset_all_thresholds ();
 802 }
 803
 804 /**
 805  * gst_debug_get_default_threshold:
 806  *
 807  * Returns the default threshold that is used for new categories.
 808  *
 809  * Returns: the default threshold level
 810  */
 811 GstDebugLevel
 812 gst_debug_get_default_threshold (void)
 813 {
 814   return (GstDebugLevel) g_atomic_int_get (&__default_level);
 815 }
 816 static void
 817 gst_debug_reset_threshold (gpointer category, gpointer unused)
 818 {
 819   GstDebugCategory *cat = (GstDebugCategory *) category;
 820   GSList *walk;
 821
 822   g_static_mutex_lock (&__level_name_mutex);
 823   walk = __level_name;
 824   while (walk) {
 825     LevelNameEntry *entry = walk->data;
 826
 827     walk = g_slist_next (walk);
 828     if (g_pattern_match_string (entry->pat, cat->name)) {
 829       GST_LOG ("category %s matches pattern %p - gets set to level %d",
 830           cat->name, entry->pat, entry->level);
 831       gst_debug_category_set_threshold (cat, entry->level);
 832       goto exit;
 833     }
 834   }
 835   gst_debug_category_set_threshold (cat, gst_debug_get_default_threshold ());
 836
 837 exit:
 838   g_static_mutex_unlock (&__level_name_mutex);
 839 }
 840 static void
 841 gst_debug_reset_all_thresholds (void)
 842 {
 843   g_static_mutex_lock (&__cat_mutex);
 844   g_slist_foreach (__categories, gst_debug_reset_threshold, NULL);
 845   g_static_mutex_unlock (&__cat_mutex);
 846 }
 847 static void
 848 for_each_threshold_by_entry (gpointer data, gpointer user_data)
 849 {
 850   GstDebugCategory *cat = (GstDebugCategory *) data;
 851   LevelNameEntry *entry = (LevelNameEntry *) user_data;
 852
 853   if (g_pattern_match_string (entry->pat, cat->name)) {
 854     GST_LOG ("category %s matches pattern %p - gets set to level %d",
 855         cat->name, entry->pat, entry->level);
 856     gst_debug_category_set_threshold (cat, entry->level);
 857   }
 858 }
 859
 860 /**
 861  * gst_debug_set_threshold_for_name:
 862  * @name: name of the categories to set
 863  * @level: level to set them to
 864  *
 865  * Sets all categories which match the given glob style pattern to the given
 866  * level.
 867  */
 868 void
 869 gst_debug_set_threshold_for_name (const gchar * name, GstDebugLevel level)
 870 {
 871   GPatternSpec *pat;
 872   LevelNameEntry *entry;
 873
 874   g_return_if_fail (name != NULL);
 875
 876   pat = g_pattern_spec_new (name);
 877   entry = g_new (LevelNameEntry, 1);
 878   entry->pat = pat;
 879   entry->level = level;
 880   g_static_mutex_lock (&__level_name_mutex);
 881   __level_name = g_slist_prepend (__level_name, entry);
 882   g_static_mutex_unlock (&__level_name_mutex);
 883   g_static_mutex_lock (&__cat_mutex);
 884   g_slist_foreach (__categories, for_each_threshold_by_entry, entry);
 885   g_static_mutex_unlock (&__cat_mutex);
 886 }
 887
 888 /**
 889  * gst_debug_unset_threshold_for_name:
 890  * @name: name of the categories to set
 891  *
 892  * Resets all categories with the given name back to the default level.
 893  */
 894 void
 895 gst_debug_unset_threshold_for_name (const gchar * name)
 896 {
 897   GSList *walk;
 898   GPatternSpec *pat;
 899
 900   g_return_if_fail (name != NULL);
 901
 902   pat = g_pattern_spec_new (name);
 903   g_static_mutex_lock (&__level_name_mutex);
 904   walk = __level_name;
 905   /* improve this if you want, it's mighty slow */
 906   while (walk) {
 907     LevelNameEntry *entry = walk->data;
 908
 909     if (g_pattern_spec_equal (entry->pat, pat)) {
 910       __level_name = g_slist_remove_link (__level_name, walk);
 911       g_pattern_spec_free (entry->pat);
 912       g_free (entry);
 913       g_slist_free_1 (walk);
 914       walk = __level_name;
 915     }
 916   }
 917   g_static_mutex_unlock (&__level_name_mutex);
 918   g_pattern_spec_free (pat);
 919   gst_debug_reset_all_thresholds ();
 920 }
 921
 922 GstDebugCategory *
 923 _gst_debug_category_new (gchar * name, guint color, gchar * description)
 924 {
 925   GstDebugCategory *cat;
 926
 927   g_return_val_if_fail (name != NULL, NULL);
 928
 929   cat = g_new (GstDebugCategory, 1);
 930   cat->name = g_strdup (name);
 931   cat->color = color;
 932   if (description != NULL) {
 933     cat->description = g_strdup (description);
 934   } else {
 935     cat->description = g_strdup ("no description");
 936   }
 937   gst_atomic_int_set (&cat->threshold, 0);
 938   gst_debug_reset_threshold (cat, NULL);
 939
 940   /* add to category list */
 941   g_static_mutex_lock (&__cat_mutex);
 942   __categories = g_slist_prepend (__categories, cat);
 943   g_static_mutex_unlock (&__cat_mutex);
 944
 945   return cat;
 946 }
 947
 948 /**
 949  * gst_debug_category_free:
 950  * @category: #GstDebugCategory to free.
 951  *
 952  * Removes and frees the category and all associated resources.
 953  */
 954 void
 955 gst_debug_category_free (GstDebugCategory * category)
 956 {
 957   if (category == NULL)
 958     return;
 959
 960   /* remove from category list */
 961   g_static_mutex_lock (&__cat_mutex);
 962   __categories = g_slist_remove (__categories, category);
 963   g_static_mutex_unlock (&__cat_mutex);
 964
 965   g_free ((gpointer) category->name);
 966   g_free ((gpointer) category->description);
 967   g_free (category);
 968 }
 969
 970 /**
 971  * gst_debug_category_set_threshold:
 972  * @category: a #GstDebugCategory to set threshold of.
 973  * @level: the #GstDebugLevel threshold to set.
 974  *
 975  * Sets the threshold of the category to the given level. Debug information will
 976  * only be output if the threshold is lower or equal to the level of the
 977  * debugging message.
 978  * <note><para>
 979  * Do not use this function in production code, because other functions may
 980  * change the threshold of categories as side effect. It is however a nice
 981  * function to use when debugging (even from gdb).
 982  * </para></note>
 983  */
 984 void
 985 gst_debug_category_set_threshold (GstDebugCategory * category,
 986     GstDebugLevel level)
 987 {
 988   g_return_if_fail (category != NULL);
 989
 990   gst_atomic_int_set (&category->threshold, level);
 991 }
 992
 993 /**
 994  * gst_debug_category_reset_threshold:
 995  * @category: a #GstDebugCategory to reset threshold of.
 996  *
 997  * Resets the threshold of the category to the default level. Debug information
 998  * will only be output if the threshold is lower or equal to the level of the
 999  * debugging message.
1000  * Use this function to set the threshold back to where it was after using
1001  * gst_debug_category_set_threshold().
1002  */
1003 void
1004 gst_debug_category_reset_threshold (GstDebugCategory * category)
1005 {
1006   gst_debug_reset_threshold (category, NULL);
1007 }
1008
1009 /**
1010  * gst_debug_category_get_threshold:
1011  * @category: a #GstDebugCategory to get threshold of.
1012  *
1013  * Returns the threshold of a #GstCategory.
1014  *
1015  * Returns: the #GstDebugLevel that is used as threshold.
1016  */
1017 GstDebugLevel
1018 gst_debug_category_get_threshold (GstDebugCategory * category)
1019 {
1020   return g_atomic_int_get (&category->threshold);
1021 }
1022
1023 /**
1024  * gst_debug_category_get_name:
1025  * @category: a #GstDebugCategory to get name of.
1026  *
1027  * Returns the name of a debug category.
1028  *
1029  * Returns: the name of the category.
1030  */
1031 const gchar *
1032 gst_debug_category_get_name (GstDebugCategory * category)
1033 {
1034   return category->name;
1035 }
1036
1037 /**
1038  * gst_debug_category_get_color:
1039  * @category: a #GstDebugCategory to get the color of.
1040  *
1041  * Returns the color of a debug category used when printing output in this
1042  * category.
1043  *
1044  * Returns: the color of the category.
1045  */
1046 guint
1047 gst_debug_category_get_color (GstDebugCategory * category)
1048 {
1049   return category->color;
1050 }
1051
1052 /**
1053  * gst_debug_category_get_description:
1054  * @category: a #GstDebugCategory to get the description of.
1055  *
1056  * Returns the description of a debug category.
1057  *
1058  * Returns: the description of the category.
1059  */
1060 const gchar *
1061 gst_debug_category_get_description (GstDebugCategory * category)
1062 {
1063   return category->description;
1064 }
1065
1066 /**
1067  * gst_debug_get_all_categories:
1068  *
1069  * Returns a snapshot of a all categories that are currently in use . This list
1070  * may change anytime.
1071  * The caller has to free the list after use.
1072  * <emphasis>This function is not threadsafe, so only use it while only the
1073  * main thread is running.</emphasis>
1074  *
1075  * Returns: the list of categories
1076  */
1077 GSList *
1078 gst_debug_get_all_categories (void)
1079 {
1080   GSList *ret;
1081
1082   g_static_mutex_lock (&__cat_mutex);
1083   ret = g_slist_copy (__categories);
1084   g_static_mutex_unlock (&__cat_mutex);
1085
1086   return ret;
1087 }
1088
1089 /*** FUNCTION POINTERS ********************************************************/
1090
1091 static GHashTable *__gst_function_pointers;     /* NULL */
1092 static GStaticMutex __dbg_functions_mutex = G_STATIC_MUTEX_INIT;
1093
1094 const gchar *
1095 _gst_debug_nameof_funcptr (GstDebugFuncPtr ptr)
1096     G_GNUC_NO_INSTRUMENT;
1097
1098 /* This function MUST NOT return NULL */
1099      const gchar *_gst_debug_nameof_funcptr (GstDebugFuncPtr func)
1100 {
1101   gpointer ptr = (gpointer) func;
1102   gchar *ptrname;
1103
1104 #ifdef HAVE_DLADDR
1105   Dl_info dlinfo;
1106 #endif
1107
1108   if (__gst_function_pointers) {
1109     g_static_mutex_lock (&__dbg_functions_mutex);
1110     ptrname = g_hash_table_lookup (__gst_function_pointers, ptr);
1111     g_static_mutex_unlock (&__dbg_functions_mutex);
1112     if (ptrname)
1113       return ptrname;
1114   }
1115   /* we need to create an entry in the hash table for this one so we don't leak
1116    * the name */
1117 #ifdef HAVE_DLADDR
1118   if (dladdr (ptr, &dlinfo) && dlinfo.dli_sname) {
1119     gchar *name = g_strdup (dlinfo.dli_sname);
1120
1121     _gst_debug_register_funcptr (ptr, name);
1122     return name;
1123   } else
1124 #endif
1125   {
1126     gchar *name = g_strdup_printf ("%p", ptr);
1127
1128     _gst_debug_register_funcptr (ptr, name);
1129     return name;
1130   }
1131 }
1132
1133 void
1134 _gst_debug_register_funcptr (GstDebugFuncPtr func, gchar * ptrname)
1135 {
1136   gpointer ptr = (gpointer) func;
1137
1138   g_static_mutex_lock (&__dbg_functions_mutex);
1139
1140   if (!__gst_function_pointers)
1141     __gst_function_pointers = g_hash_table_new (g_direct_hash, g_direct_equal);
1142   if (!g_hash_table_lookup (__gst_function_pointers, ptr))
1143     g_hash_table_insert (__gst_function_pointers, ptr, ptrname);
1144
1145   g_static_mutex_unlock (&__dbg_functions_mutex);
1146 }
1147
1148 #ifdef HAVE_PRINTF_EXTENSION
1149 static int
1150 _gst_info_printf_extension (FILE * stream, const struct printf_info *info,
1151     const void *const *args)
1152 {
1153   char *buffer;
1154   int len;
1155   void *ptr;
1156
1157   buffer = NULL;
1158   ptr = *(void **) args[0];
1159
1160   buffer = gst_debug_print_object (ptr);
1161   len = fprintf (stream, "%*s", (info->left ? -info->width : info->width),
1162       buffer);
1163
1164   free (buffer);
1165   return len;
1166 }
1167
1168 static int
1169 _gst_info_printf_extension_arginfo (const struct printf_info *info, size_t n,
1170     int *argtypes)
1171 {
1172   if (n > 0)
1173     argtypes[0] = PA_POINTER;
1174   return 1;
1175 }
1176 #endif /* HAVE_PRINTF_EXTENSION */
1177
1178 #else /* !GST_DISABLE_GST_DEBUG */
1179 guint
1180 gst_debug_remove_log_function (GstLogFunction func)
1181 {
1182   return 0;
1183 }
1184
1185 guint
1186 gst_debug_remove_log_function_by_data (gpointer data)
1187 {
1188   return 0;
1189 }
1190
1191 gboolean
1192 __gst_in_valgrind (void)
1193 {
1194   return FALSE;
1195 }
1196
1197 #endif /* GST_DISABLE_GST_DEBUG */
1198
1199
1200 #ifdef GST_ENABLE_FUNC_INSTRUMENTATION
1201 /* FIXME make this thread specific */
1202 static GSList *stack_trace = NULL;
1203
1204 void
1205 __cyg_profile_func_enter (void *this_fn, void *call_site)
1206     G_GNUC_NO_INSTRUMENT;
1207      void __cyg_profile_func_enter (void *this_fn, void *call_site)
1208 {
1209   gchar *name = _gst_debug_nameof_funcptr (this_fn);
1210   gchar *site = _gst_debug_nameof_funcptr (call_site);
1211
1212   GST_CAT_DEBUG (GST_CAT_CALL_TRACE, "entering function %s from %s", name,
1213       site);
1214   stack_trace =
1215       g_slist_prepend (stack_trace, g_strdup_printf ("%8p in %s from %p (%s)",
1216           this_fn, name, call_site, site));
1217
1218   g_free (name);
1219   g_free (site);
1220 }
1221
1222 void
1223 __cyg_profile_func_exit (void *this_fn, void *call_site)
1224     G_GNUC_NO_INSTRUMENT;
1225      void __cyg_profile_func_exit (void *this_fn, void *call_site)
1226 {
1227   gchar *name = _gst_debug_nameof_funcptr (this_fn);
1228
1229   GST_CAT_DEBUG (GST_CAT_CALL_TRACE, "leaving function %s", name);
1230   g_free (stack_trace->data);
1231   stack_trace = g_slist_delete_link (stack_trace, stack_trace);
1232
1233   g_free (name);
1234 }
1235
1236 void
1237 gst_debug_print_stack_trace (void)
1238 {
1239   GSList *walk = stack_trace;
1240   gint count = 0;
1241
1242   if (walk)
1243     walk = g_slist_next (walk);
1244
1245   while (walk) {
1246     gchar *name = (gchar *) walk->data;
1247
1248     g_print ("#%-2d %s\n", count++, name);
1249
1250     walk = g_slist_next (walk);
1251   }
1252 }
1253 #else
1254 void
1255 gst_debug_print_stack_trace (void)
1256 {
1257   /* nothing because it's compiled out */
1258 }
1259
1260 #endif /* GST_ENABLE_FUNC_INTSTRUMENTATION */