obs-studio/docs/sphinx/reference-libobs-util-profiler.rst

Profiler
========

The profiler is used to get information about program performance and
efficiency.

.. type:: typedef struct profiler_snapshot profiler_snapshot_t
.. type:: typedef struct profiler_snapshot_entry profiler_snapshot_entry_t
.. type:: typedef struct profiler_name_store profiler_name_store_t
.. type:: typedef struct profiler_time_entry profiler_time_entry_t

.. code:: cpp

   #include <util/profiler.h>


Profiler Structures
-------------------

.. type:: struct profiler_time_entry
.. member:: uint64_t profiler_time_entry.time_delta
.. member:: uint64_t profiler_time_entry.count


Profiler Control Functions
--------------------------

.. 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.

----------------------


Profiling Functions
-------------------

.. 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.

----------------------


Profiler Name Storage Functions
-------------------------------

.. 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

----------------------


Profiler Data Access Functions
------------------------------

.. 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:: typedef 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:: typedef 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