## Profiling

Profiling — Profiling tools for applications

## Functions

#define | EOS_PROFILE_PROBE()
EosProfileProbe * | eos_profile_probe_start ()
void | eos_profile_probe_stop ()

## Types and Values

| EosProfileProbe

## Object Hierarchy

        GBoxed
        ╰── EosProfileProbe

## Description

The profiling API provided by the Endless SDK is a simple tool for defining profiling probes and collecting data over multiple calls.

### Enabling profiling

Profile probes try to be as close to zero-cost as possible; they are only enabled if the `EOS_PROFILE` environment variable is set. This means that you can leave the profile probes in your code, and they will be inert until the environment is set up for profiling.

### Using profiling probes

Typically, you want to declare a profiling probe at the beginning of the section of the code you wish to measure, and stop it at the end.

The profiling probes are identified by a unique name, typically expressed as a path, like `/com/example/ExampleProbe`; this allows creating a tree of probes.

If you are using the C API and a GCC-compatible compiler, you will want to use the ``g_autoptr()`` macro to declare the profiling probe, and have it automatically collected at the end of the scope, for instance:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18

    static void
    some_function (SomeObject *obj)
    {
      some_set_up (obj);

      // Here begins the section we wish to profile
      g_autoptr(EosProfileProbe) outer = EOS_PROFILE ("/com/example/some-function");

      some_expensive_computation (obj);
      some_additional_work (obj);

      if (some_state (obj))
        {
          g_autoptr(EosProfileProbe) inner = EOS_PROFILE ("/com/example/some-function/state");

          some_more_computation (obj);
        }
    }

In the example above, the `outer` probe is created after we performed some operation; since we are not interested into its cost, we are going to ignore it. Additionally, the `inner` probe is created conditionally on some state, so we can also gather information on the actual number of times the inner function is called. In either cases, both the `outer` and `inner` probes are automatically stopped once they get out of scope.

### Capturing profiling data

By default, when the `EOS_PROFILE` environment variable is set, you will get a summary at the end of the process, sent to the standard output.

It is also possible to redirect the profiling data to a capture file, by setting the `EOS_PROFILE` environment variable to the `capture` value. In that case, the profiling data will be stored in a binary format at the end of the process, and you can use the `eos-profile` tool to extract the probes, timings, and generate a summary. The default filename for the captured data is based on the name of the binary and the process ID, and it's saved under the `$XDG_CACHE_HOME` directory (see: `g_get_user_cache_dir()`).

You can also specify the name of the capture file, by setting the `EOS_PROFILE` environment variable to `capture:/path/to/file`.

## Functions

### EOS_PROFILE_PROBE()

    #define             EOS_PROFILE_PROBE(name)

A convenience macro that creates a profiling probe at the given location.

#### Parameters

name | the name of the profiling probe |

Since: 0.6

### eos_profile_probe_start ()

    EosProfileProbe *
    eos_profile_probe_start (const char *file,
                             gsize line,
                             const char *function,
                             const char *name);

Starts a profiling probe for `name` , creating it if necessary.

#### Parameters

file | the source file for the probe, typically represented by `__FILE__` |
line | the line in the source `file` , typically represented by `__LINE__` |
function | the function for the probe, typically represented by `G_STRFUNC` |
name | a unique name for the probe |

#### Returns

a profile probe identifier; use `eos_profile_probe_stop()` to stop the profiling on the returned probe.

[transfer none]

Since: 0.6

### eos_profile_probe_stop ()

    void
    eos_profile_probe_stop (EosProfileProbe *probe);

Stops a profiling probe started using `eos_profile_probe_start()`.

#### Parameters

probe | a EosProfileProbe |

Since: 0.6

## Types and Values

### EosProfileProbe

    typedef struct _EosProfileProbe EosProfileProbe;

An opaque identifier for a profiling probe.

Since: 0.6