926 lines
32 KiB
HTML
926 lines
32 KiB
HTML
<?xml version="1.0" encoding="us-ascii"?>
|
|
<html xmlns="http://www.w3.org/1999/xhtml">
|
|
<head>
|
|
<title>mono-api-profiler.html</title>
|
|
<style type="text/css">
|
|
.mapi-docs {
|
|
line-height: 1.5;
|
|
padding-left: 2em;
|
|
padding-right: 2em;
|
|
}
|
|
.mapi-docs p {
|
|
max-width: 60em;
|
|
}
|
|
.mapi-docs .mapi-body {
|
|
max-width: 60em;
|
|
}
|
|
.mapi-docs code {
|
|
border: 1px solid rgba(214,214,214,1);
|
|
background-color: rgba(249,249,249,1);
|
|
padding: 0.1em 0.5em;
|
|
}
|
|
.mapi-description code {
|
|
font-family: "Consolas", "Courier", monospace;
|
|
border: 1px solid rgba(214,214,214,1);
|
|
background-color: rgba(249,249,249,1);
|
|
padding: 0.1em 0.2em;
|
|
}
|
|
|
|
.mapi-header {
|
|
padding: 0 0 5pt 5pt;
|
|
margin: 10pt;
|
|
white-space: pre;
|
|
font-family: monospace;
|
|
border: 1px solid rgba(233,233,233,1);
|
|
background-color: rgba(249,249,249,1);
|
|
}
|
|
|
|
.mapi-code {
|
|
padding: 5pt 5pt;
|
|
margin: 10pt;
|
|
white-space: pre;
|
|
font-family: monospace;
|
|
border: 1px solid rgba(233,233,233,1);
|
|
background-color: rgba(249,249,249,1);
|
|
}
|
|
|
|
.mapi-code:first-line {
|
|
line-height: 0px;
|
|
}
|
|
|
|
.mapi-codeblock {
|
|
display: block;
|
|
padding: 5pt 5pt;
|
|
margin: 10pt;
|
|
white-space: pre;
|
|
font-family: monospace;
|
|
border: 1px solid rgba(233,233,233,1);
|
|
background-color: rgba(249,249,249,1);
|
|
}
|
|
|
|
.mapi-entry code {
|
|
border: none;
|
|
background-color: transparent;
|
|
}
|
|
|
|
.mapi-parameters {
|
|
border-collapse: collapse;
|
|
border-spacing: 0;
|
|
empty-cells: hide;
|
|
border: 0;
|
|
margin: 5px 0 26px;
|
|
}
|
|
|
|
.mapi-parameters td {
|
|
border: 1px solid rgba(214,214,214,1);
|
|
border-left-style: none;
|
|
padding: 5px 25px 5px 10px;
|
|
}
|
|
|
|
.mapi-parameters tr>td:last-child {
|
|
border-right: 0;
|
|
}
|
|
|
|
.mapi-parameters td:first-of-type {
|
|
text-align: right;
|
|
padding: 7px;
|
|
vertical-align: top;
|
|
word-break: normal;
|
|
width: 40px;
|
|
}
|
|
|
|
.mapi-parameters tr:last-child>td {
|
|
border-bottom: 0;
|
|
}
|
|
|
|
.mapi-parameters tr:first-child>td {
|
|
border-top: 0;
|
|
}
|
|
|
|
.mapi-parameters tr td:first-of-type {
|
|
text-align: right;
|
|
padding: 7px;
|
|
vertical-align: top;
|
|
word-break: normal;
|
|
width: 40px;
|
|
}
|
|
|
|
.mapi {
|
|
left: -25px;
|
|
margin: 0;
|
|
padding: 13px 25px 0;
|
|
position: relative;
|
|
width: 100%;
|
|
}
|
|
|
|
.mapi-description {
|
|
background: rgba(249,249,249,1);
|
|
border-bottom: 1px solid rgba(233,233,233,1);
|
|
left: -25px;
|
|
margin: 0;
|
|
padding: 13px 25px 0;
|
|
position: relative;
|
|
width: 100%;
|
|
}
|
|
|
|
.mapi-entry {
|
|
background: transparent;
|
|
}
|
|
|
|
.mapi-docs {
|
|
}
|
|
|
|
.mapi-prototype {
|
|
border-left: 5px solid rgba(205,233,244,1);
|
|
padding: .5em;
|
|
margin-top: 5pt;
|
|
margin-bottom: 5pt;
|
|
font-family: "Consolas", "Courier", monospace;
|
|
display: block;
|
|
overflow: auto;
|
|
background-color: #f9f9f9;
|
|
}
|
|
|
|
.mapi-declaration {
|
|
margin-top: 21px;
|
|
}
|
|
|
|
.mapi-section {
|
|
font-size: smaller;
|
|
font-weight: bold;
|
|
margin-top: 21px;
|
|
line-height: 1.5;
|
|
}
|
|
|
|
.mapi-strike {
|
|
text-decoration: line-through;
|
|
}
|
|
|
|
.mapi-deprecated {
|
|
color: red;
|
|
}
|
|
|
|
.mapi-ptr-container {
|
|
background: white;
|
|
border-bottom: 1px solid rgba(233,233,233,1);
|
|
left: -25px;
|
|
padding-left: 25px;
|
|
padding-right: 25px;
|
|
padding-bottom: 13px;
|
|
position: relative;
|
|
width: 100%;
|
|
}
|
|
|
|
.mapi-ptr {
|
|
background: rgba(249,249,249,1);
|
|
border-left: 1px solid rgba(233,233,233,1);
|
|
border-top: 1px solid rgba(233,233,233,1);
|
|
height: 12px;
|
|
left: 37px;
|
|
top: -7px;
|
|
-webkit-transform: rotate(45deg);
|
|
-moz-transform: rotate(45deg);
|
|
-o-transform: rotate(45deg);
|
|
transform: rotate(45deg);
|
|
position: absolute;
|
|
width: 12px;
|
|
}
|
|
|
|
.mapi-height-container {
|
|
left: -25px;
|
|
padding: 0 25px;
|
|
position: relative;
|
|
width: 100%;
|
|
}
|
|
|
|
</style>
|
|
</head>
|
|
<body>
|
|
<div class="mapi-docs">
|
|
<h1>Runtime Profiler API</h1>
|
|
|
|
<p />The profiler API can be used by dynamically loaded profiler
|
|
modules to monitor different aspects of a running program. The
|
|
API is also usable by embedders without having to compile a
|
|
profiler module.
|
|
|
|
<h2>Profiler Modules</h2>
|
|
|
|
<p />A profiler module is simply a shared library with a single
|
|
exported function which is the entry point that Mono calls at
|
|
startup. It must have the following signature:
|
|
|
|
<pre><code class="mapi-codeblock">
|
|
void mono_profiler_startup_example (const char *desc)
|
|
</code></pre>
|
|
|
|
<p />Here, the <code>example</code> portion of the function name is
|
|
the name of the profiler module. It must match the shared library
|
|
name (i.e. <code>libmono-profiler-example.so</code>). <i>desc</i>
|
|
is the set of arguments that were passed from the command line.
|
|
|
|
<p />For example, a bare bones profiler module might look like this
|
|
(<code>example.c</code>):
|
|
|
|
<pre><code class="mapi-codeblock">
|
|
#include <mono/metadata/profiler.h>
|
|
#include <stdio.h>
|
|
|
|
struct _MonoProfiler {
|
|
int dummy;
|
|
}
|
|
|
|
static MonoProfiler profiler;
|
|
|
|
static void
|
|
runtime_inited (MonoProfiler *prof)
|
|
{
|
|
printf ("Hello World");
|
|
}
|
|
|
|
void
|
|
mono_profiler_init_example (const char *desc)
|
|
{
|
|
MonoProfilerHandle handle = mono_profiler_create (&profiler);
|
|
mono_profiler_set_runtime_initialized_callback (handle, runtime_inited);
|
|
}
|
|
</code></pre>
|
|
|
|
<p />To compile this module, a C compiler must be invoked in a
|
|
similar fashion to this, on Linux:
|
|
|
|
<pre><code class="mapi-codeblock">
|
|
gcc -fPIC -shared -o libmono-profiler-example.so example.c `pkg-config --cflags mono-2`
|
|
</code></pre>
|
|
|
|
<p />Or on OS X:
|
|
|
|
<pre><code class="mapi-codeblock">
|
|
gcc -undefined suppress -flat_namespace -o libmono-profiler-example.so example.c `pkg-config --cflags mono-2`
|
|
</code></pre>
|
|
|
|
<p />You can then load the module using:
|
|
|
|
<pre><code class="mapi-codeblock">
|
|
mono --profile=example hello.exe
|
|
</code></pre>
|
|
|
|
<p />(Note that adjusting <code>LD_LIBRARY_PATH</code> may be
|
|
necessary in order for the dynamic linker to find the module.)
|
|
|
|
<h2>Profiler Functions</h2>
|
|
|
|
<p />These are the functions usable for profiling programs.
|
|
|
|
<p />Each function has a note indicating whether they're async
|
|
safe. An async safe function can be invoked in a signal handler
|
|
or when the world is stopped by the GC. Conversely, a function
|
|
that is not async safe must not be invoked in such a context or
|
|
undefined behavior can occur (crashes, deadlocks, etc).
|
|
|
|
<p />Some functions may only be invoked from a profiler module's
|
|
init function (or prior to running managed code in the case of
|
|
embedding). This is noted explicitly only if applicable to a
|
|
function.
|
|
|
|
<h3>Basic Functions</h3>
|
|
|
|
<p />These functions are used to load and install profilers.
|
|
|
|
<a name="api:mono_profiler_load"></a>
|
|
<div class="mapi">
|
|
<div class="mapi-entry "><code>mono_profiler_load</code></div>
|
|
<div class="mapi-height-container">
|
|
<div class="mapi-ptr-container"></div>
|
|
<div class="mapi-description">
|
|
<div class="mapi-ptr"></div>
|
|
|
|
<div class="mapi-declaration mapi-section">Syntax</div>
|
|
<div class="mapi-prototype">void
|
|
mono_profiler_load (const char *desc)
|
|
|
|
</div>
|
|
<p />
|
|
<div class="mapi-section">Description</div>
|
|
<div>
|
|
<p />
|
|
Loads a profiler module based on the specified description. <i>desc</i> can be
|
|
of the form <code>name:args</code> or just <code>name</code>. For example, <code>log:sample</code> and
|
|
<code>log</code> will both load <code>libmono-profiler-log.so</code>. The description is passed
|
|
to the module after it has been loaded. If the specified module has already
|
|
been loaded, this function has no effect.
|
|
<p />
|
|
A module called <code>foo</code> should declare an entry point like so:
|
|
<p />
|
|
<pre><code class="mapi-codeblock">
|
|
void mono_profiler_init_foo (const char *desc)
|
|
{
|
|
}
|
|
</code></pre>
|
|
<p />
|
|
This function is <strong>not</strong> async safe.
|
|
<p />
|
|
This function may <strong>only</strong> be called by embedders prior to running managed
|
|
code.</div>
|
|
</div><!--mapi-description -->
|
|
</div><!--height container -->
|
|
</div> <!-- class=mapi -->
|
|
|
|
<a name="api:mono_profiler_create"></a>
|
|
<div class="mapi">
|
|
<div class="mapi-entry "><code>mono_profiler_create</code></div>
|
|
<div class="mapi-height-container">
|
|
<div class="mapi-ptr-container"></div>
|
|
<div class="mapi-description">
|
|
<div class="mapi-ptr"></div>
|
|
|
|
<div class="mapi-declaration mapi-section">Syntax</div>
|
|
<div class="mapi-prototype">MonoProfilerHandle
|
|
mono_profiler_create (MonoProfiler *prof)
|
|
|
|
</div>
|
|
<p />
|
|
<div class="mapi-section">Description</div>
|
|
<div>
|
|
<p />
|
|
Installs a profiler and returns a handle for it. The handle is used with the
|
|
other functions in the profiler API (e.g. for setting up callbacks). The
|
|
given structure pointer, <i>prof</i>, will be passed to all callbacks from the
|
|
profiler API. It can be <code><code>NULL</code></code>.
|
|
<p />
|
|
Example usage:
|
|
<p />
|
|
<pre><code class="mapi-codeblock">
|
|
struct _MonoProfiler {
|
|
int my_stuff;
|
|
// ...
|
|
};
|
|
|
|
MonoProfiler *prof = malloc (sizeof (MonoProfiler));
|
|
prof->my_stuff = 42;
|
|
MonoProfilerHandle handle = mono_profiler_create (prof);
|
|
mono_profiler_set_shutdown_callback (handle, my_shutdown_cb);
|
|
</code></pre>
|
|
<p />
|
|
This function is <strong>not</strong> async safe.
|
|
<p />
|
|
This function may <strong>only</strong> be called from a profiler's init function or prior
|
|
to running managed code.</div>
|
|
</div><!--mapi-description -->
|
|
</div><!--height container -->
|
|
</div> <!-- class=mapi -->
|
|
|
|
<a name="api:mono_profiler_set_cleanup_callback"></a>
|
|
<div class="mapi">
|
|
<div class="mapi-entry "><code>mono_profiler_set_cleanup_callback</code></div>
|
|
<div class="mapi-height-container">
|
|
<div class="mapi-ptr-container"></div>
|
|
<div class="mapi-description">
|
|
<div class="mapi-ptr"></div>
|
|
|
|
<div class="mapi-declaration mapi-section">Syntax</div>
|
|
<div class="mapi-prototype">void
|
|
mono_profiler_set_cleanup_callback (MonoProfilerHandle handle, MonoProfilerCleanupCallback cb)
|
|
|
|
</div>
|
|
<p />
|
|
<div class="mapi-section">Description</div>
|
|
<div>
|
|
<p />
|
|
Sets a profiler cleanup function. This function will be invoked at shutdown
|
|
when the profiler API is cleaning up its internal structures. It's mainly
|
|
intended for a profiler to free the structure pointer that was passed to
|
|
<code>mono_profiler_create</code>, if necessary.
|
|
<p />
|
|
This function is async safe.</div>
|
|
</div><!--mapi-description -->
|
|
</div><!--height container -->
|
|
|
|
<h3>Code Coverage</h3>
|
|
|
|
<p />These functions provide access to the JIT compiler's code
|
|
coverage support. This functionality can be used to collect
|
|
information about how many times certain code paths have been
|
|
executed.
|
|
|
|
</div> <!-- class=mapi -->
|
|
|
|
<a name="api:mono_profiler_enable_coverage"></a>
|
|
<div class="mapi">
|
|
<div class="mapi-entry "><code>mono_profiler_enable_coverage</code></div>
|
|
<div class="mapi-height-container">
|
|
<div class="mapi-ptr-container"></div>
|
|
<div class="mapi-description">
|
|
<div class="mapi-ptr"></div>
|
|
|
|
<div class="mapi-declaration mapi-section">Syntax</div>
|
|
<div class="mapi-prototype">mono_bool
|
|
mono_profiler_enable_coverage (void)
|
|
|
|
</div>
|
|
<p />
|
|
<div class="mapi-section">Description</div>
|
|
<div>
|
|
<p />
|
|
Enables support for code coverage instrumentation. At the moment, this means
|
|
enabling the debug info subsystem. If this function is not called, it will
|
|
not be possible to use <code>mono_profiler_get_coverage_data</code>. Returns <code><code>TRUE</code></code>
|
|
if code coverage support was enabled, or <code><code>FALSE</code></code> if the function was called
|
|
too late for this to be possible.
|
|
<p />
|
|
This function is <strong>not</strong> async safe.
|
|
<p />
|
|
This function may <strong>only</strong> be called from a profiler's init function or prior
|
|
to running managed code.</div>
|
|
</div><!--mapi-description -->
|
|
</div><!--height container -->
|
|
</div> <!-- class=mapi -->
|
|
|
|
<a name="api:mono_profiler_set_coverage_filter_callback"></a>
|
|
<div class="mapi">
|
|
<div class="mapi-entry "><code>mono_profiler_set_coverage_filter_callback</code></div>
|
|
<div class="mapi-height-container">
|
|
<div class="mapi-ptr-container"></div>
|
|
<div class="mapi-description">
|
|
<div class="mapi-ptr"></div>
|
|
|
|
<div class="mapi-declaration mapi-section">Syntax</div>
|
|
<div class="mapi-prototype">void
|
|
mono_profiler_set_coverage_filter_callback (MonoProfilerHandle handle, MonoProfilerCoverageFilterCallback cb)
|
|
|
|
</div>
|
|
<p />
|
|
<div class="mapi-section">Description</div>
|
|
<div>
|
|
<p />
|
|
Sets a code coverage filter function. The profiler API will invoke filter
|
|
functions from all installed profilers. If any of them return <code><code>TRUE</code></code>, then
|
|
the given method will be instrumented for coverage analysis. All filters are
|
|
guaranteed to be called at least once per method, even if an earlier filter
|
|
has already returned <code><code>TRUE</code></code>.
|
|
<p />
|
|
Note that filter functions must be installed before a method is compiled in
|
|
order to have any effect, i.e. a filter should be registered in a profiler's
|
|
init function or prior to running managed code (if embedding).
|
|
<p />
|
|
This function is async safe.</div>
|
|
</div><!--mapi-description -->
|
|
</div><!--height container -->
|
|
</div> <!-- class=mapi -->
|
|
|
|
<a name="api:mono_profiler_get_coverage_data"></a>
|
|
<div class="mapi">
|
|
<div class="mapi-entry "><code>mono_profiler_get_coverage_data</code></div>
|
|
<div class="mapi-height-container">
|
|
<div class="mapi-ptr-container"></div>
|
|
<div class="mapi-description">
|
|
<div class="mapi-ptr"></div>
|
|
|
|
<div class="mapi-declaration mapi-section">Syntax</div>
|
|
<div class="mapi-prototype">mono_bool
|
|
mono_profiler_get_coverage_data (MonoProfilerHandle handle, MonoMethod *method, MonoProfilerCoverageCallback cb)
|
|
|
|
</div>
|
|
<p />
|
|
<div class="mapi-section">Description</div>
|
|
<div>
|
|
<p />
|
|
Retrieves all coverage data for <i>method</i> and invokes <i>cb</i> for each entry.
|
|
Source location information will only be filled out if <i>method</i> has debug
|
|
info available. Returns <code><code>TRUE</code></code> if <i>method</i> was instrumented for code
|
|
coverage; otherwise, <code><code>FALSE</code></code>.
|
|
<p />
|
|
Please note that the structure passed to <i>cb</i> is only valid for the
|
|
duration of the callback.
|
|
<p />
|
|
This function is <strong>not</strong> async safe.</div>
|
|
</div><!--mapi-description -->
|
|
</div><!--height container -->
|
|
|
|
<h3>Statistical Sampling</h3>
|
|
|
|
<p />Statistical sampling can be used to interrupt managed threads
|
|
based on a certain mode and frequency for the purpose of
|
|
collecting data about their current work.
|
|
|
|
<p />One common use case for this functionality, usually referred
|
|
to as call sampling, is to collect a backtrace from every thread
|
|
when a sampling hit event arrives. This data can then be compiled
|
|
into a report indicating where a program spends most of its time.
|
|
|
|
</div> <!-- class=mapi -->
|
|
|
|
<a name="api:mono_profiler_enable_sampling"></a>
|
|
<div class="mapi">
|
|
<div class="mapi-entry "><code>mono_profiler_enable_sampling</code></div>
|
|
<div class="mapi-height-container">
|
|
<div class="mapi-ptr-container"></div>
|
|
<div class="mapi-description">
|
|
<div class="mapi-ptr"></div>
|
|
|
|
<div class="mapi-declaration mapi-section">Syntax</div>
|
|
<div class="mapi-prototype">mono_bool
|
|
mono_profiler_enable_sampling (MonoProfilerHandle handle)
|
|
|
|
</div>
|
|
<p />
|
|
<div class="mapi-section">Description</div>
|
|
<div>
|
|
<p />
|
|
Enables the sampling thread. Users must call this function if they intend
|
|
to use statistical sampling; <code>mono_profiler_set_sample_mode</code> will have no
|
|
effect if this function has not been called. The first profiler to call this
|
|
function will get ownership over sampling settings (mode and frequency) so
|
|
that no other profiler can change those settings. Returns <code><code>TRUE</code></code> if the
|
|
sampling thread was enabled, or <code><code>FALSE</code></code> if the function was called too late
|
|
for this to be possible.
|
|
<p />
|
|
Note that <code>mono_profiler_set_sample_mode</code> must still be called with a mode
|
|
other than <code>MONO_PROFILER_SAMPLE_MODE_NONE</code> to actually start sampling.
|
|
<p />
|
|
This function is <strong>not</strong> async safe.
|
|
<p />
|
|
This function may <strong>only</strong> be called from a profiler's init function or prior
|
|
to running managed code.</div>
|
|
</div><!--mapi-description -->
|
|
</div><!--height container -->
|
|
</div> <!-- class=mapi -->
|
|
|
|
<a name="api:mono_profiler_set_sample_mode"></a>
|
|
<div class="mapi">
|
|
<div class="mapi-entry "><code>mono_profiler_set_sample_mode</code></div>
|
|
<div class="mapi-height-container">
|
|
<div class="mapi-ptr-container"></div>
|
|
<div class="mapi-description">
|
|
<div class="mapi-ptr"></div>
|
|
|
|
<div class="mapi-declaration mapi-section">Syntax</div>
|
|
<div class="mapi-prototype">mono_bool
|
|
mono_profiler_set_sample_mode (MonoProfilerHandle handle, MonoProfilerSampleMode mode, uint32_t freq)
|
|
|
|
</div>
|
|
<p />
|
|
<div class="mapi-section">Description</div>
|
|
<div>
|
|
<p />
|
|
Sets the sampling mode and frequency (in Hz). <i>freq</i> must be a positive
|
|
number. If the calling profiler has ownership over sampling settings, the
|
|
settings will be changed and this function will return <code><code>TRUE</code></code>; otherwise,
|
|
it returns <code><code>FALSE</code></code> without changing any settings.
|
|
<p />
|
|
This function is async safe.</div>
|
|
</div><!--mapi-description -->
|
|
</div><!--height container -->
|
|
</div> <!-- class=mapi -->
|
|
|
|
<a name="api:mono_profiler_get_sample_mode"></a>
|
|
<div class="mapi">
|
|
<div class="mapi-entry "><code>mono_profiler_get_sample_mode</code></div>
|
|
<div class="mapi-height-container">
|
|
<div class="mapi-ptr-container"></div>
|
|
<div class="mapi-description">
|
|
<div class="mapi-ptr"></div>
|
|
|
|
<div class="mapi-declaration mapi-section">Syntax</div>
|
|
<div class="mapi-prototype">mono_bool
|
|
mono_profiler_get_sample_mode (MonoProfilerHandle handle, MonoProfilerSampleMode *mode, uint32_t *freq)
|
|
|
|
</div>
|
|
<p />
|
|
<div class="mapi-section">Description</div>
|
|
<div>
|
|
<p />
|
|
Retrieves the current sampling mode and/or frequency (in Hz). Returns
|
|
<code><code>TRUE</code></code> if the calling profiler is allowed to change the sampling settings;
|
|
otherwise, <code><code>FALSE</code></code>.
|
|
<p />
|
|
This function is async safe.</div>
|
|
</div><!--mapi-description -->
|
|
</div><!--height container -->
|
|
|
|
<p />A callback must be registered to receive sample hit events.
|
|
Please see the <i>Callback Registration</i> section below.
|
|
|
|
<h3>GC Allocations</h3>
|
|
|
|
<p />Profilers can be notified about all GC allocations performed
|
|
by a program or the Mono runtime.
|
|
|
|
</div> <!-- class=mapi -->
|
|
|
|
<a name="api:mono_profiler_enable_allocations"></a>
|
|
<div class="mapi">
|
|
<div class="mapi-entry "><code>mono_profiler_enable_allocations</code></div>
|
|
<div class="mapi-height-container">
|
|
<div class="mapi-ptr-container"></div>
|
|
<div class="mapi-description">
|
|
<div class="mapi-ptr"></div>
|
|
|
|
<div class="mapi-declaration mapi-section">Syntax</div>
|
|
<div class="mapi-prototype">mono_bool
|
|
mono_profiler_enable_allocations (void)
|
|
|
|
</div>
|
|
<p />
|
|
<div class="mapi-section">Description</div>
|
|
<div>
|
|
<p />
|
|
Enables instrumentation of GC allocations. This is necessary so that managed
|
|
allocators can be instrumented with a call into the profiler API.
|
|
Allocations will not be reported unless this function is called. Returns
|
|
<code><code>TRUE</code></code> if allocation instrumentation was enabled, or <code><code>FALSE</code></code> if the
|
|
function was called too late for this to be possible.
|
|
<p />
|
|
This function is <strong>not</strong> async safe.
|
|
<p />
|
|
This function may <strong>only</strong> be called from a profiler's init function or prior
|
|
to running managed code.</div>
|
|
</div><!--mapi-description -->
|
|
</div><!--height container -->
|
|
|
|
<p />A callback must be registered to receive allocation events.
|
|
Please see the <i>Callback Registration</i> section below.
|
|
|
|
<h3>Call Instrumentation</h3>
|
|
|
|
<p />The JIT compiler supports instrumenting managed method entry
|
|
and exit points so that a profiler callback will be invoked.
|
|
|
|
<p />While such callbacks by themselves have traditionally only
|
|
been useful for call count profiling and the like, Mono gives
|
|
these callbacks access to the arguments, locals, and return
|
|
value of instrumented methods (together referred to as the 'call
|
|
context'). This enables many profiling scenarios that would
|
|
otherwise have required explicit hooks in the base class
|
|
libraries.
|
|
|
|
</div> <!-- class=mapi -->
|
|
|
|
<a name="api:mono_profiler_set_call_instrumentation_filter_callback"></a>
|
|
<div class="mapi">
|
|
<div class="mapi-entry "><code>mono_profiler_set_call_instrumentation_filter_callback</code></div>
|
|
<div class="mapi-height-container">
|
|
<div class="mapi-ptr-container"></div>
|
|
<div class="mapi-description">
|
|
<div class="mapi-ptr"></div>
|
|
|
|
<div class="mapi-declaration mapi-section">Syntax</div>
|
|
<div class="mapi-prototype">void
|
|
mono_profiler_set_call_instrumentation_filter_callback (MonoProfilerHandle handle, MonoProfilerCallInstrumentationFilterCallback cb)
|
|
|
|
</div>
|
|
<p />
|
|
<div class="mapi-section">Description</div>
|
|
<div>
|
|
<p />
|
|
Sets a call instrumentation filter function. The profiler API will invoke
|
|
filter functions from all installed profilers. If any of them return flags
|
|
other than <code>MONO_PROFILER_CALL_INSTRUMENTATION_NONE</code>, then the given method
|
|
will be instrumented as requested. All filters are guaranteed to be called
|
|
at least once per method, even if earlier filters have already specified all
|
|
flags.
|
|
<p />
|
|
Note that filter functions must be installed before a method is compiled in
|
|
order to have any effect, i.e. a filter should be registered in a profiler's
|
|
init function or prior to running managed code (if embedding). Also, to
|
|
instrument a method that's going to be AOT-compiled, a filter must be
|
|
installed at AOT time. This can be done in exactly the same way as one would
|
|
normally, i.e. by passing the <code>--profile</code> option on the command line, by
|
|
calling <code>mono_profiler_load</code>, or simply by using the profiler API as an
|
|
embedder.
|
|
<p />
|
|
Indiscriminate method instrumentation is extremely heavy and will slow down
|
|
most applications to a crawl. Users should consider sampling as a possible
|
|
alternative to such heavy-handed instrumentation.
|
|
<p />
|
|
This function is async safe.</div>
|
|
</div><!--mapi-description -->
|
|
</div><!--height container -->
|
|
</div> <!-- class=mapi -->
|
|
|
|
<a name="api:mono_profiler_enable_call_context_introspection"></a>
|
|
<div class="mapi">
|
|
<div class="mapi-entry "><code>mono_profiler_enable_call_context_introspection</code></div>
|
|
<div class="mapi-height-container">
|
|
<div class="mapi-ptr-container"></div>
|
|
<div class="mapi-description">
|
|
<div class="mapi-ptr"></div>
|
|
|
|
<div class="mapi-declaration mapi-section">Syntax</div>
|
|
<div class="mapi-prototype">mono_bool
|
|
mono_profiler_enable_call_context_introspection (void)
|
|
|
|
</div>
|
|
<p />
|
|
<div class="mapi-section">Description</div>
|
|
<div>
|
|
<p />
|
|
Enables support for retrieving stack frame data from a call context. At the
|
|
moment, this means enabling the debug info subsystem. If this function is not
|
|
called, it will not be possible to use the call context introspection
|
|
functions (they will simply return <code><code>NULL</code>)</code>. Returns <code><code>TRUE</code></code> if call context
|
|
introspection was enabled, or <code><code>FALSE</code></code> if the function was called too late for
|
|
this to be possible.
|
|
<p />
|
|
This function is <strong>not</strong> async safe.
|
|
<p />
|
|
This function may <strong>only</strong> be called from a profiler's init function or prior
|
|
to running managed code.</div>
|
|
</div><!--mapi-description -->
|
|
</div><!--height container -->
|
|
</div> <!-- class=mapi -->
|
|
|
|
<a name="api:mono_profiler_call_context_get_this"></a>
|
|
<div class="mapi">
|
|
<div class="mapi-entry "><code>mono_profiler_call_context_get_this</code></div>
|
|
<div class="mapi-height-container">
|
|
<div class="mapi-ptr-container"></div>
|
|
<div class="mapi-description">
|
|
<div class="mapi-ptr"></div>
|
|
|
|
<div class="mapi-declaration mapi-section">Syntax</div>
|
|
<div class="mapi-prototype">void*
|
|
mono_profiler_call_context_get_this (MonoProfilerCallContext *context)
|
|
|
|
</div>
|
|
<p />
|
|
<div class="mapi-section">Description</div>
|
|
<div>
|
|
<p />
|
|
Given a valid call context from an enter/leave event, retrieves a pointer to
|
|
the <code>this</code> reference for the method. Returns <code><code>NULL</code></code> if none exists (i.e.
|
|
it's a static method) or if call context introspection was not enabled.
|
|
<p />
|
|
The buffer returned by this function must be freed with
|
|
<code>mono_profiler_call_context_free_buffer</code>.
|
|
<p />
|
|
Please note that a call context is only valid for the duration of the
|
|
enter/leave callback it was passed to.
|
|
<p />
|
|
This function is <strong>not</strong> async safe.</div>
|
|
</div><!--mapi-description -->
|
|
</div><!--height container -->
|
|
</div> <!-- class=mapi -->
|
|
|
|
<a name="api:mono_profiler_call_context_get_argument"></a>
|
|
<div class="mapi">
|
|
<div class="mapi-entry "><code>mono_profiler_call_context_get_argument</code></div>
|
|
<div class="mapi-height-container">
|
|
<div class="mapi-ptr-container"></div>
|
|
<div class="mapi-description">
|
|
<div class="mapi-ptr"></div>
|
|
|
|
<div class="mapi-declaration mapi-section">Syntax</div>
|
|
<div class="mapi-prototype">void*
|
|
mono_profiler_call_context_get_argument (MonoProfilerCallContext *context, uint32_t position)
|
|
|
|
</div>
|
|
<p />
|
|
<div class="mapi-section">Description</div>
|
|
<div>
|
|
<p />
|
|
Given a valid call context from an enter/leave event, retrieves a pointer to
|
|
the method argument at the given position. Returns <code><code>NULL</code></code> if <i>position</i> is
|
|
out of bounds or if call context introspection was not enabled.
|
|
<p />
|
|
The buffer returned by this function must be freed with
|
|
<code>mono_profiler_call_context_free_buffer</code>.
|
|
<p />
|
|
Please note that a call context is only valid for the duration of the
|
|
enter/leave callback it was passed to.
|
|
<p />
|
|
This function is <strong>not</strong> async safe.</div>
|
|
</div><!--mapi-description -->
|
|
</div><!--height container -->
|
|
</div> <!-- class=mapi -->
|
|
|
|
<a name="api:mono_profiler_call_context_get_local"></a>
|
|
<div class="mapi">
|
|
<div class="mapi-entry "><code>mono_profiler_call_context_get_local</code></div>
|
|
<div class="mapi-height-container">
|
|
<div class="mapi-ptr-container"></div>
|
|
<div class="mapi-description">
|
|
<div class="mapi-ptr"></div>
|
|
|
|
<div class="mapi-declaration mapi-section">Syntax</div>
|
|
<div class="mapi-prototype">void*
|
|
mono_profiler_call_context_get_local (MonoProfilerCallContext *context, uint32_t position)
|
|
|
|
</div>
|
|
<p />
|
|
<div class="mapi-section">Description</div>
|
|
<div>
|
|
<p />
|
|
Given a valid call context from an enter/leave event, retrieves a pointer to
|
|
the local variable at the given position. Returns <code><code>NULL</code></code> if <i>position</i> is
|
|
out of bounds or if call context introspection was not enabled.
|
|
<p />
|
|
The buffer returned by this function must be freed with
|
|
<code>mono_profiler_call_context_free_buffer</code>.
|
|
<p />
|
|
Please note that a call context is only valid for the duration of the
|
|
enter/leave callback it was passed to.
|
|
<p />
|
|
This function is <strong>not</strong> async safe.</div>
|
|
</div><!--mapi-description -->
|
|
</div><!--height container -->
|
|
</div> <!-- class=mapi -->
|
|
|
|
<a name="api:mono_profiler_call_context_get_result"></a>
|
|
<div class="mapi">
|
|
<div class="mapi-entry "><code>mono_profiler_call_context_get_result</code></div>
|
|
<div class="mapi-height-container">
|
|
<div class="mapi-ptr-container"></div>
|
|
<div class="mapi-description">
|
|
<div class="mapi-ptr"></div>
|
|
|
|
<div class="mapi-declaration mapi-section">Syntax</div>
|
|
<div class="mapi-prototype">void*
|
|
mono_profiler_call_context_get_result (MonoProfilerCallContext *context)
|
|
|
|
</div>
|
|
<p />
|
|
<div class="mapi-section">Description</div>
|
|
<div>
|
|
<p />
|
|
Given a valid call context from an enter/leave event, retrieves a pointer to
|
|
return value of a method. Returns <code><code>NULL</code></code> if the method has no return value
|
|
(i.e. it returns <code>void)</code>, if the leave event was the result of a tail call,
|
|
if the function is called on a context from an enter event, or if call
|
|
context introspection was not enabled.
|
|
<p />
|
|
The buffer returned by this function must be freed with
|
|
<code>mono_profiler_call_context_free_buffer</code>.
|
|
<p />
|
|
Please note that a call context is only valid for the duration of the
|
|
enter/leave callback it was passed to.
|
|
<p />
|
|
This function is <strong>not</strong> async safe.</div>
|
|
</div><!--mapi-description -->
|
|
</div><!--height container -->
|
|
</div> <!-- class=mapi -->
|
|
|
|
<a name="api:mono_profiler_call_context_free_buffer"></a>
|
|
<div class="mapi">
|
|
<div class="mapi-entry "><code>mono_profiler_call_context_free_buffer</code></div>
|
|
<div class="mapi-height-container">
|
|
<div class="mapi-ptr-container"></div>
|
|
<div class="mapi-description">
|
|
<div class="mapi-ptr"></div>
|
|
|
|
<div class="mapi-declaration mapi-section">Syntax</div>
|
|
<div class="mapi-prototype">void
|
|
mono_profiler_call_context_free_buffer (void *buffer)
|
|
|
|
</div>
|
|
<p />
|
|
<div class="mapi-section">Description</div>
|
|
<div>
|
|
<p />
|
|
Frees a buffer returned by one of the call context introspection functions.
|
|
Passing a <code><code>NULL</code></code> value for <i>buffer</i> is allowed, which makes this function
|
|
a no-op.
|
|
<p />
|
|
This function is <strong>not</strong> async safe.</div>
|
|
</div><!--mapi-description -->
|
|
</div><!--height container -->
|
|
|
|
<p />Callbacks must be registered to receive method entry and exit
|
|
events. Please see the <i>Callback Registration</i> section
|
|
below.
|
|
|
|
<h3>Callback Registration</h3>
|
|
|
|
<p />In addition to the above functions, there's a large set of
|
|
functions for installing generic profiler event callbacks. These
|
|
are generated from C macros and so are not documented here.
|
|
Please refer to the <code>mono/metadata/profiler.h</code> and
|
|
<code>mono/metadata/profiler-events.h</code> headers for a full
|
|
listing of these.
|
|
|
|
<p />Callback registration functions are all async safe and can be
|
|
safely invoked from multiple threads at the same time, with the
|
|
caveat that altering a registered callback from one thread will
|
|
not immediately affect another thread that is already invoking
|
|
the current callback.
|
|
|
|
<h2>API Stability</h2>
|
|
|
|
<p />The profiler API does not have the same API stability
|
|
garantees that the rest of the Mono embedding API does. While
|
|
a breaking change to the profiler API is extremely rare, it has
|
|
happened in the past when changing the API in a backwards
|
|
compatible way was deemed to be too much work for too little
|
|
gain.
|
|
|
|
<p />Therefore, developers of profiler modules may rarely need to
|
|
update their code to work with new versions of the profiler API.
|
|
|
|
<p />Developers who wish to support older versions of the API can
|
|
perform a compile time check of the
|
|
<code>MONO_PROFILER_API_VERSION</code> macro and maintain code
|
|
for both old and new versions.
|
|
|
|
<p />To aid with transitioning to a new version of the profiler
|
|
API, the Mono runtime will detect and reject loading profiler
|