Profiling

Profiling — Profiling tools for applications

Functions

Types and Values

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