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:
the leaks tracer object to emit this signal on
a newly-allocated GstStructure
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:
the leaks tracer object to emit this signal on
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:
the leaks tracer object to emit this signal on
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:
the leaks tracer object to emit this signal on
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:
the leaks tracer object to emit this signal on
a newly-allocated GstStructure
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:
the leaks tracer object to emit this signal on
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