docs/sphinx/reference-libobs-util-profiler.rst
The profiler is used to get information about program performance and efficiency.
.. type:: struct profiler_snapshot profiler_snapshot_t .. type:: struct profiler_snapshot_entry profiler_snapshot_entry_t .. type:: struct profiler_name_store profiler_name_store_t .. type:: struct profiler_time_entry profiler_time_entry_t
.. code:: cpp
#include <util/profiler.h>
.. struct:: profiler_time_entry .. member:: uint64_t profiler_time_entry.time_delta .. member:: uint64_t profiler_time_entry.count
.. function:: void profiler_start(void)
Starts the profiler.
.. function:: void profiler_stop(void)
Stops the profiler.
.. function:: void profiler_print(profiler_snapshot_t *snap)
Creates a profiler snapshot and saves it within snap.
:param snap: A profiler snapshot object
.. function:: void profiler_print_time_between_calls(profiler_snapshot_t *snap)
Creates a profiler snapshot of time between calls and saves it within snap.
:param snap: A profiler snapshot object
.. function:: void profiler_free(void)
Frees the profiler.
.. function:: void profile_register_root(const char *name, uint64_t expected_time_between_calls)
Registers a root profile node.
:param name: Name of the root profile node :param expected_time_between_calls: The expected time between calls of the profile root node, or 0 if none.
.. function:: void profile_start(const char *name)
Starts a profile node. This profile node will be a child of the last node that was started.
:param name: Name of the profile node
.. function:: void profile_end(const char *name)
:param name: Name of the profile node
.. function:: void profile_reenable_thread(void)
Because :c:func:profiler_start() can be called in a different
thread than the current thread, this is used to specify a point where
it's safe to re-enable profiling in the calling thread. Call this
when you have looped root profile nodes and need to specify a safe
point where the root profile node isn't active and the profiler can
start up in the current thread again.
.. function:: profiler_name_store_t *profiler_name_store_create(void)
Creates a profiler name storage object.
:return: Profiler name store object
.. function:: void profiler_name_store_free(profiler_name_store_t *store)
Frees a profiler name storage object.
:param store: Profiler name storage object
.. function:: const char *profile_store_name(profiler_name_store_t *store, const char *format, ...)
Creates a formatted string and stores it within a profiler name storage object.
:param store: Profiler name storage object :param format: Formatted string :return: The string created from format specifications
.. function:: profiler_snapshot_t *profile_snapshot_create(void)
Creates a profile snapshot. Profiler snapshots are used to obtain data about how the active profiles performed.
:return: A profiler snapshot object
.. function:: void profile_snapshot_free(profiler_snapshot_t *snap)
Frees a profiler snapshot object.
:param snap: A profiler snapshot
.. function:: bool profiler_snapshot_dump_csv(const profiler_snapshot_t *snap, const char *filename)
Creates a CSV file of the profiler snapshot.
:param snap: A profiler snapshot :param filename: The path to the CSV file to save :return: true if successfully written, false otherwise
.. function:: bool profiler_snapshot_dump_csv_gz(const profiler_snapshot_t *snap, const char *filename)
Creates a gzipped CSV file of the profiler snapshot.
:param snap: A profiler snapshot :param filename: The path to the gzipped CSV file to save :return: true if successfully written, false otherwise
.. function:: size_t profiler_snapshot_num_roots(profiler_snapshot_t *snap)
:param snap: A profiler snapshot :return: Number of root profiler nodes in the snapshot
.. type:: bool (*profiler_entry_enum_func)(void *context, profiler_snapshot_entry_t *entry)
Profiler snapshot entry numeration callback
:param context: Private data passed to this callback :param entry: Profiler snapshot entry :return: true to continue enumeration, false otherwise
.. function:: void profiler_snapshot_enumerate_roots(profiler_snapshot_t *snap, profiler_entry_enum_func func, void *context)
Enumerates root profile nodes.
:param snap: A profiler snapshot :param func: Enumeration callback :param context: Private data to pass to the callback
.. type:: bool (*profiler_name_filter_func)(void *data, const char *name, bool *remove)
Callback used to determine what profile nodes are removed/filtered.
:param data: Private data passed to this callback :param name: Profile node name to be filtered :param remove: Used to determined whether the node should be removed or not :return: true to continue enumeration, false otherwise
.. function:: void profiler_snapshot_filter_roots(profiler_snapshot_t *snap, profiler_name_filter_func func, void *data)
Removes/filters profile roots based upon their names.
:param snap: A profiler snapshot :param func: Enumeration callback to filter with :param data: Private data to pass to the callback
.. function:: size_t profiler_snapshot_num_children(profiler_snapshot_entry_t *entry)
:param entry: A profiler snapshot entry :return: Number of children for the entry
.. function:: void profiler_snapshot_enumerate_children(profiler_snapshot_entry_t *entry, profiler_entry_enum_func func, void *context)
Enumerates child entries of a profiler snapshot entry.
:param entry: A profiler snapshot entry :param func: Enumeration callback :param context: Private data passed to the callback
.. function:: const char *profiler_snapshot_entry_name(profiler_snapshot_entry_t *entry)
:param entry: A profiler snapshot entry :return: The name of the profiler snapshot entry
.. function:: profiler_time_entries_t *profiler_snapshot_entry_times(profiler_snapshot_entry_t *entry)
Gets the time entries for a snapshot entry.
:param entry: A profiler snapshot entry :return: An array of profiler time entries
.. function:: uint64_t profiler_snapshot_entry_min_time(profiler_snapshot_entry_t *entry)
Gets the minimum time for a profiler snapshot entry.
:param entry: A profiler snapshot entry :return: The minimum time value for the snapshot entry
.. function:: uint64_t profiler_snapshot_entry_max_time(profiler_snapshot_entry_t *entry)
Gets the maximum time for a profiler snapshot entry.
:param entry: A profiler snapshot entry :return: The maximum time value for the snapshot entry
.. function:: uint64_t profiler_snapshot_entry_overall_count(profiler_snapshot_entry_t *entry)
Gets the overall count for a profiler snapshot entry.
:param entry: A profiler snapshot entry :return: The overall count value for the snapshot entry
.. function:: profiler_time_entries_t *profiler_snapshot_entry_times_between_calls(profiler_snapshot_entry_t *entry)
Gets an array of time between calls for a profiler snapshot entry.
:param entry: A profiler snapshot entry :return: An array of profiler time entries
.. function:: uint64_t profiler_snapshot_entry_expected_time_between_calls(profiler_snapshot_entry_t *entry)
Gets the expected time between calls for a profiler snapshot entry.
:param entry: A profiler snapshot entry :return: The expected time between calls for the snapshot entry, or 0 if not set
.. function:: uint64_t profiler_snapshot_entry_min_time_between_calls(profiler_snapshot_entry_t *entry)
Gets the minimum time seen between calls for a profiler snapshot entry.
:param entry: A profiler snapshot entry :return: The minimum time seen between calls for the snapshot entry
.. function:: uint64_t profiler_snapshot_entry_max_time_between_calls(profiler_snapshot_entry_t *entry)
Gets the maximum time seen between calls for a profiler snapshot entry.
:param entry: A profiler snapshot entry :return: The maximum time seen between calls for the snapshot entry
.. function:: uint64_t profiler_snapshot_entry_overall_between_calls_count(profiler_snapshot_entry_t *entry)
Gets the overall time between calls for a profiler snapshot entry.
:param entry: A profiler snapshot entry :return: The overall time between calls for the snapshot entry