File: mono-api-profiler.html

package info (click to toggle)
mono 6.12.0.199%2Bds-4
links: PTS, VCS
area: main
in suites: sid
size: 1,273,192 kB
sloc: cs: 11,181,844; xml: 2,850,076; ansic: 689,413; cpp: 123,344; perl: 59,361; javascript: 30,841; asm: 21,845; makefile: 19,951; sh: 15,030; python: 4,771; pascal: 925; sql: 859; sed: 16; php: 1
file content (925 lines) | stat: -rw-r--r-- 32,842 bytes
parent folder | download | duplicates (7)
<?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 &lt;mono/metadata/profiler.h&gt;
#include &lt;stdio.h&gt;

struct _MonoProfiler {
	int dummy;
}

static MonoProfiler profiler;

static void
runtime_inited (MonoProfiler *prof)
{
	printf (&quot;Hello World&quot;);
}

void
mono_profiler_init_example (const char *desc)
{
	MonoProfilerHandle handle = mono_profiler_create (&amp;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-&gt;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