Top | ![]() |
![]() |
![]() |
![]() |
#define | EOS_PROFILE_PROBE() |
EosProfileProbe * | eos_profile_probe_start () |
void | eos_profile_probe_stop () |
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
macro to declare the profiling probe, and have it
automatically collected at the end of the scope, for instance:g_autoptr()
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
.
#define EOS_PROFILE_PROBE(name)
A convenience macro that creates a profiling probe at the given location.
Since: 0.6
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.
file |
the source file for the probe, typically represented by |
|
line |
the line in the source |
|
function |
the function for the probe, typically represented by |
|
name |
a unique name for the probe |
a profile probe identifier; use eos_profile_probe_stop()
to stop the profiling on the returned probe.
[transfer none]
Since: 0.6
void
eos_profile_probe_stop (EosProfileProbe *probe
);
Stops a profiling probe started using eos_profile_probe_start()
.
Since: 0.6
typedef struct _EosProfileProbe EosProfileProbe;
An opaque identifier for a profiling probe.
Since: 0.6