# leaks

This tracing module tracks the lifetimes of GstObject and GstMiniObject objects and prints a list of leaks to the debug log under `GST_TRACER:7` when gst_deinit is called, and also prints a g_warning.

Starting with GStreamer 1.18, you can also use GObject action signals on the tracer object to fetch leak information. Use gst_tracing_get_active_tracers to get a list of all active tracers and find the right one by name.

If the `GST_LEAKS_TRACER_SIG` env variable is defined, you can use the following POSIX signals to interact with the leaks tracer:

- SIGUSR1: log alive objects
- SIGUSR2: create a checkpoint and print a list of objects created and destroyed since the previous checkpoint.

You can activate this tracer in the usual way by adding the string 'leaks' to the environment variable `GST_TRACERS`. Such as: `GST_TRACERS=leaks`

Note that the values are separated by semicolon (`;`), such as: `GST_TRACERS=leaks;latency`, and multiple instances of the same tracer can be active at the same time.

The tracer properties can also be set to each tracer by passing the object properties in the list of parameters to the tracer. This uses the same serialization format as GstStructure (without a name).

Examples:

    GST_TRACERS='leaks(filters="GstEvent,GstMessage",stack-traces-flags=none)'

    GST_TRACERS='leaks(filters="GstBuffer",stack-traces-flags=full,check-refs=true);leaks(name=all-leaks)'

## GstLeaksTracer

    GObject
        ╰──GInitiallyUnowned
            ╰──GstObject
                ╰──GstTracer
                    ╰──GstLeaksTracer

Opaque GstLeaksTracer data structure

### Action Signals

#### activity-get-checkpoint

    g_signal_emit_by_name (leakstracer, "activity-get-checkpoint", &ret);

    ret = leakstracer.emit ("activity-get-checkpoint")

    let ret = leakstracer.emit ("activity-get-checkpoint");

You must call this after calling `activity-start-tracking` and you should call `activity-stop-tracking` when you are done tracking.

Returns a GstStructure with two fields: `"objects-created-list"` and `"objects-removed-list"`, each of which is a GValue of type GST_TYPE_LIST containing all objects that were created/removed since the last checkpoint, or since tracking started if this is the first checkpoint.

The list elements are in order of creation/removal. Each list element is a GValue containing a GstStructure with the following fields:

`type-name`: a string representing the type of the object `address`: a string representing the address of the object; the object itself cannot be returned since we don't own it and it may be freed at any moment, or it may already have been freed

Parameters:

`leakstracer` (GstElement *) –

the leaks tracer object to emit this signal on

Returns (GstStructure *) –

a newly-allocated GstStructure

Flags: Run Last / Action

Since : 1.18

#### activity-log-checkpoint

    g_signal_emit_by_name (leakstracer, "activity-log-checkpoint");

    ret = leakstracer.emit ("activity-log-checkpoint")

    let ret = leakstracer.emit ("activity-log-checkpoint");

You must call this after calling `activity-start-tracking` and you should call `activity-stop-tracking` when you are done tracking.

List all objects that were created or removed since the last checkpoint, or since tracking started if this is the first checkpoint.

This action signal is equivalent to `activity-get-checkpoint` except that the checkpoint data will be printed to the debug log under `GST_TRACER:7`.

Parameters:

`leakstracer` (GstElement *) –

the leaks tracer object to emit this signal on

Flags: Run Last / Action

Since : 1.18

#### activity-start-tracking

    g_signal_emit_by_name (leakstracer, "activity-start-tracking");

    ret = leakstracer.emit ("activity-start-tracking")

    let ret = leakstracer.emit ("activity-start-tracking");

Start storing information about all objects that are being created or removed. Call `stop-tracking` to stop.

NOTE: You do not need to call this to use the *-live-objects action signals listed above.

Parameters:

`leakstracer` (GstElement *) –

the leaks tracer object to emit this signal on

Flags: Run Last / Action

Since : 1.18

#### activity-stop-tracking

    g_signal_emit_by_name (leakstracer, "activity-stop-tracking");

    ret = leakstracer.emit ("activity-stop-tracking")

    let ret = leakstracer.emit ("activity-stop-tracking");

Stop tracking all objects that are being created or removed, undoes the effects of the `start-tracking` signal.

Parameters:

`leakstracer` (GstElement *) –

the leaks tracer object to emit this signal on

Flags: Run Last / Action

Since : 1.18

#### get-live-objects

    g_signal_emit_by_name (leakstracer, "get-live-objects", &ret);

    ret = leakstracer.emit ("get-live-objects")

    let ret = leakstracer.emit ("get-live-objects");

Returns a GstStructure containing a GValue of type GST_TYPE_LIST which is a list of GstStructure objects containing information about the objects that are still alive, which is useful for detecting leaks. Each GstStructure object has the following fields:

`object`: containing the leaked object itself `ref-count`: the current reference count of the object `trace`: the allocation stack trace for the object, only available if the `stack-traces-flags` param is set to `full` `ref-infos`: a GValue of type GST_TYPE_LIST which is a list of GstStructure objects containing information about the ref/unref history of the object; only available if the `check-refs` param is set to `true`

Each `ref-infos` GstStructure has the following fields:

`ts`: the timestamp for the ref/unref `desc`: either "reffed" or "unreffed" `ref-count`: the reference count after the ref/unref `trace`: the stack trace for the ref/unref

Notes on usage: This action signal is supposed to be called at the end of an application before it exits, or at the end of an execution run when all streaming has stopped and all pipelines have been freed. It is assumed that at this point any GStreamer object that is still alive is leaked, and there are no legitimate owners any more. As such, ownership of the leaked objects is transferred to you then, assuming no other code still retrains references to them.

If that's not the case, and there is code somewhere still holding a reference, then the application behaviour is undefined after this function is called, since we will have stolen some other code's valid reference and when the returned GstStructure is freed that code will be holding a reference to an invalid object, which will most likely crash sooner or later.

If you don't want to just check for leaks at the end of a program, the activity checkpoint action signals might be a better fit for your use case.

Parameters:

`leakstracer` (GstElement *) –

the leaks tracer object to emit this signal on

Returns (GstStructure *) –

a newly-allocated GstStructure

Flags: Run Last / Action

Since : 1.18

#### log-live-objects

    g_signal_emit_by_name (leakstracer, "log-live-objects");

    ret = leakstracer.emit ("log-live-objects")

    let ret = leakstracer.emit ("log-live-objects");

Logs all objects that are still alive to the debug log in the same format as the logging during gst_deinit.

Parameters:

`leakstracer` (GstElement *) –

the leaks tracer object to emit this signal on

Flags: Run Last / Action

Since : 1.18

### Properties

#### check-refs

    “check-refs” gboolean

Whether to record every location where a leaked object was reffed and unreffed. When enabled, the tracer will collect stack traces for every ref/unref operation on tracked objects.

Flags : Read / Write / Construct Only

Default value : false

Since : 1.26

#### filters

    “filters” gchararray

Comma-separated list of GObject types to track. Only objects of these types or their subtypes will be monitored for leaks.

Example: "GstEvent,GstMessage" to only track GstEvent and GstMessage objects.

Flags : Read / Write / Construct Only

Since : 1.26

#### log-leaks-on-deinit

    “log-leaks-on-deinit” gboolean

Whether to report all leaks on gst_deinit by printing them in the debug log. When enabled, any detected leaks will be logged under GST_TRACER:7 when the GStreamer is being shut down.

Flags : Read / Write / Construct Only

Default value : true

Since : 1.26

#### stack-traces-flags

    “stack-traces-flags” GstLeaksStackTraceFlags*

Stack trace collection mode. Controls whether and how stack traces are collected for object allocations and ref/unref operations.

Flags : Read / Write / Construct Only

Default value : disabled

Since : 1.26

The results of the search are