## GstTrace

GstTrace — Tracing functionality

## Synopsis

    #include <gst/gst.h>

                        GstTrace;
    GstTrace*           gst_trace_new                       (gchar *filename,
                                                             gint size);
    void                gst_trace_destroy                   (GstTrace *trace);
    void                gst_trace_flush                     (GstTrace *trace);
    void                gst_trace_text_flush                (GstTrace *trace);
    #define             gst_trace_add_entry                 (trace,seq,data,msg)
    #define             gst_trace_get_size                  (trace)
    #define             gst_trace_get_offset                (trace)
    #define             gst_trace_get_remaining             (trace)
    void                gst_trace_set_default               (GstTrace *trace);
    void                gst_trace_read_tsc                  (gint64 *dst);
    enum                GstAllocTraceFlags;
                        GstAllocTrace;
    gboolean            gst_alloc_trace_available           (void);
    const GList*        gst_alloc_trace_list                (void);
    int                 gst_alloc_trace_live_all            (void);
    void                gst_alloc_trace_print_all           (void);
    void                gst_alloc_trace_set_flags_all       (GstAllocTraceFlags flags);
    GstAllocTrace*      gst_alloc_trace_get                 (const gchar *name);
    void                gst_alloc_trace_print               (const GstAllocTrace *trace);
    void                gst_alloc_trace_print_live          (void);
    void                gst_alloc_trace_set_flags           (GstAllocTrace *trace,
                                                             GstAllocTraceFlags flags);
    #define             gst_alloc_trace_register            (name)
    #define             gst_alloc_trace_new                 (trace, mem)
    #define             gst_alloc_trace_free                (trace, mem)

## Description

Traces allows to track object allocation. They provide a instance counter per GType. The counter is incremented for each object allocated and decremented it when it's freed.

Example 15. Tracing object instances

        // trace un-freed object instances
        gst_alloc_trace_set_flags_all (GST_ALLOC_TRACE_LIVE);
        if (!gst_alloc_trace_available ()) {
          g_warning ("Trace not available (recompile with trace enabled).");
        }
        gst_alloc_trace_print_live ();
        // do something here
        gst_alloc_trace_print_live ();

Last reviewed on 2005-11-21 (0.9.5)

## Details

### GstTrace

    typedef struct {
    } GstTrace;

Opaque GstTrace structure.

### gst_trace_new ()

    GstTrace*           gst_trace_new                       (gchar *filename,
                                                             gint size);

Create a ringbuffer of `size` in the file with `filename` to store trace results in.

`filename` : | a filename
`size` : | the max size of the file
Returns : | a new GstTrace.

### gst_trace_destroy ()

    void                gst_trace_destroy                   (GstTrace *trace);

Flush an close the previously allocated `trace`.

`trace` : | the GstTrace to destroy

### gst_trace_flush ()

    void                gst_trace_flush                     (GstTrace *trace);

Flush any pending trace entries in `trace` to the trace file. `trace` can be NULL in which case the default GstTrace will be flushed.

`trace` : | the GstTrace to flush.

### gst_trace_text_flush ()

    void                gst_trace_text_flush                (GstTrace *trace);

Flush any pending trace entries in `trace` to the trace file, formatted as a text line with timestamp and sequence numbers. `trace` can be NULL in which case the default GstTrace will be flushed.

`trace` : | the GstTrace to flush.

### gst_trace_add_entry()

    #define             gst_trace_add_entry(trace,seq,data,msg)

Add an entry to `trace` with sequence number `seq`, `data` and `msg`. If `trace` is NULL, the entry will be added to the default GstTrace.

`trace` : | a GstTrace
`seq` : | a sequence number
`data` : | the data to trace
`msg` : | the trace message

### gst_trace_get_size()

    #define 	gst_trace_get_size(trace) 	((trace)->bufsize)

Retrieve the buffer size of `trace`.

`trace` : | a GstTrace

### gst_trace_get_offset()

    #define 	gst_trace_get_offset(trace) 	((trace)->bufoffset)

Retrieve the current buffer offset of `trace`.

`trace` : | a GstTrace

### gst_trace_get_remaining()

    #define 	gst_trace_get_remaining(trace) 	((trace)->bufsize - (trace)->bufoffset)

Retrieve the remaining size in the `trace` buffer.

`trace` : | a GstTrace

### gst_trace_set_default ()

    void                gst_trace_set_default               (GstTrace *trace);

Set the default GstTrace to `trace`.

`trace` : | the GstTrace to set as the default.

### gst_trace_read_tsc ()

    void                gst_trace_read_tsc                  (gint64 *dst);

Read a platform independent timer value that can be used in benchmarks.

`dst` : | pointer to hold the result.

### enum GstAllocTraceFlags

    typedef enum {
      GST_ALLOC_TRACE_LIVE		= (1 << 0),
      GST_ALLOC_TRACE_MEM_LIVE	= (1 << 1)
    } GstAllocTraceFlags;

Flags indicating which tracing feature to enable.

`GST_ALLOC_TRACE_LIVE` | Trace number of non-freed memory
`GST_ALLOC_TRACE_MEM_LIVE` | trace pointers of unfreed memory

### GstAllocTrace

    typedef struct {
      gchar		*name;
      gint		 flags;

      gint		 live;
      GSList	*mem_live;
    } GstAllocTrace;

The main tracing object

gchar *`name`; | The name of the tracing object
gint `flags`; | Flags for this object
gint `live`; | counter for live memory
GSList *`mem_live`; | list with pointers to unfreed memory

### gst_alloc_trace_available ()

    gboolean            gst_alloc_trace_available           (void);

Check if alloc tracing was compiled into the core

Returns : | TRUE if the core was compiled with alloc tracing enabled.

### gst_alloc_trace_list ()

    const GList*        gst_alloc_trace_list                (void);

Get a list of all registered alloc trace objects.

Returns : | a GList of GstAllocTrace objects.

### gst_alloc_trace_live_all ()

    int                 gst_alloc_trace_live_all            (void);

Get the total number of live registered alloc trace objects.

Returns : | the total number of live registered alloc trace objects.

### gst_alloc_trace_print_all ()

    void                gst_alloc_trace_print_all           (void);

Print the status of all registered alloc trace objects.

### gst_alloc_trace_set_flags_all ()

    void                gst_alloc_trace_set_flags_all       (GstAllocTraceFlags flags);

Enable the specified options on all registered alloc trace objects.

`flags` : | the options to enable

### gst_alloc_trace_get ()

    GstAllocTrace*      gst_alloc_trace_get                 (const gchar *name);

Get the named alloc trace object.

`name` : | the name of the alloc trace object
Returns : | a GstAllocTrace with the given name or NULL when no alloc tracer was registered with that name.

### gst_alloc_trace_print ()

    void                gst_alloc_trace_print               (const GstAllocTrace *trace);

Print the status of the given GstAllocTrace.

`trace` : | the GstAllocTrace to print

### gst_alloc_trace_print_live ()

    void                gst_alloc_trace_print_live          (void);

Print the status of all registered alloc trace objects, ignoring those without live objects.

### gst_alloc_trace_set_flags ()

    void                gst_alloc_trace_set_flags           (GstAllocTrace *trace,
                                                             GstAllocTraceFlags flags);

Enable the given features on the given GstAllocTrace object.

`trace` : | the GstAllocTrace
`flags` : | flags to set

### gst_alloc_trace_register()

    #define             gst_alloc_trace_register(name)

Register a new alloc tracer with the given name

`name` : | The name of the tracer object

### gst_alloc_trace_new()

    #define             gst_alloc_trace_new(trace, mem)

Use the tracer to trace a new memory allocation

`trace` : | The tracer to use
`mem` : | The memory allocated

### gst_alloc_trace_free()

    #define             gst_alloc_trace_free(trace, mem)

Trace a memory free operation

`trace` : | The tracer to use
`mem` : | The memory that is freed