blob: b59ee7dac3aa7ea3eaa9b6550ff17a6f57d9d56b [file] [log] [blame]
/*
* Copyright © 2020 Endless Mobile, Inc.
*
* SPDX-License-Identifier: LGPL-2.1-or-later
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
* License as published by the Free Software Foundation; either
* version 2.1 of the License, or (at your option) any later version.
*
* This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public
* License along with this library; if not, see <http://www.gnu.org/licenses/>.
*
* Author: Philip Withnall <withnall@endlessm.com>
*/
/*
* The performance tracing functions allow for the performance of code using
* GLib to be measured by passing metrics from the current process to an
* external measurement process such as `sysprof-cli` or `sysprofd`.
*
* They are designed to execute quickly, especially in the common case where no
* measurement process is connected. They are guaranteed to not block the caller
* and are guaranteed to have zero runtime cost if tracing support is disabled
* at configure time.
*
* Tracing information can be provided as ‘marks’ with a start time and
* duration; or as marks with a start time and no duration. Marks with a
* duration are intended to show the execution time of a piece of code. Marks
* with no duration are intended to show an instantaneous performance problem,
* such as an unexpectedly large allocation, or that a slow path has been taken
* in some code.
*
* |[<!-- language="C" -->
* gint64 begin_time_nsec G_GNUC_UNUSED;
*
* begin_time_nsec = G_TRACE_CURRENT_TIME;
*
* // some code which might take a while
*
* g_trace_mark (begin_time_nsec, G_TRACE_CURRENT_TIME - begin_time_nsec,
* "GLib", "GSource.dispatch",
* "%s ⇒ %s", g_source_get_name (source), need_destroy ? "destroy" : "keep");
* ]|
*
* The tracing API is currently internal to GLib.
*
* Since: 2.66
*/
#include "config.h"
#include "gtrace-private.h"
#include <stdarg.h>
/*
* g_trace_mark:
* @begin_time_nsec: start time of the mark, as returned by %G_TRACE_CURRENT_TIME
* @duration_nsec: duration of the mark, in nanoseconds
* @group: name of the group for categorising this mark
* @name: name of the mark
* @message_format: format for the detailed message for the mark, in `printf()` format
* @...: arguments to substitute into @message_format; none of these should have
* side effects
*
* Add a mark to the trace, starting at @begin_time_nsec and having length
* @duration_nsec (which may be zero). The @group should typically be `GLib`,
* and the @name should concisely describe the call site.
*
* All of the arguments to this function must not have side effects, as the
* entire function call may be dropped if sysprof support is not available.
*
* Since: 2.66
*/
void
(g_trace_mark) (gint64 begin_time_nsec,
gint64 duration_nsec,
const gchar *group,
const gchar *name,
const gchar *message_format,
...)
{
#ifdef HAVE_SYSPROF
va_list args;
va_start (args, message_format);
sysprof_collector_mark_vprintf (begin_time_nsec, duration_nsec, group, name, message_format, args);
va_end (args);
#endif /* HAVE_SYSPROF */
}
/*
* g_trace_define_int64_counter:
* @group: name of the group for categorising this counter
* @name: name of the counter
* @description: description for the counter
*
* Defines a new counter with integer values.
*
* The name should be unique within all counters defined with
* the same @group. The description will be shown in the sysprof UI.
*
* To add entries for this counter to a trace, use
* g_trace_set_int64_counter().
*
* Returns: ID of the counter, for use with g_trace_set_int64_counter(),
* guaranteed to never be zero
*
* Since: 2.68
*/
guint
(g_trace_define_int64_counter) (const char *group,
const char *name,
const char *description)
{
#ifdef HAVE_SYSPROF
SysprofCaptureCounter counter;
counter.id = sysprof_collector_request_counters (1);
/* sysprof not enabled? */
if (counter.id == 0)
return (guint) -1;
counter.type = SYSPROF_CAPTURE_COUNTER_INT64;
counter.value.v64 = 0;
g_strlcpy (counter.category, group, sizeof counter.category);
g_strlcpy (counter.name, name, sizeof counter.name);
g_strlcpy (counter.description, description, sizeof counter.description);
sysprof_collector_define_counters (&counter, 1);
g_assert (counter.id != 0);
return counter.id;
#else
return (guint) -1;
#endif
}
/*
* g_trace_set_int64_counter:
* @id: ID of the counter
* @val: the value to set the counter to
*
* Adds a counter value to a trace.
*
* The ID must be obtained via g_trace_define_int64_counter()
* before using this function.
*
* Since: 2.68
*/
void
(g_trace_set_int64_counter) (guint id,
gint64 val)
{
#ifdef HAVE_SYSPROF
SysprofCaptureCounterValue value;
g_return_if_fail (id != 0);
/* Ignore setting the counter if we failed to define it in the first place. */
if (id == (guint) -1)
return;
value.v64 = val;
sysprof_collector_set_counters (&id, &value, 1);
#endif
}