From 80788a3c5041a47ea030808712a1926840160733 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Alex=20R=C3=B8nne=20Petersen?= Date: Wed, 22 Nov 2017 12:28:48 +0100 Subject: [docs] Improve profiler API documentation. * Move doc comments to profiler.c so they're picked up by exdoc. * Rewrite mono-api-profiler.html for the new profiler API. * Clarify some aspects of the doc comments. --- docs/sources/mono-api-profiler.html | 262 ++++++++++++++++++++++++++---------- 1 file changed, 191 insertions(+), 71 deletions(-) (limited to 'docs') diff --git a/docs/sources/mono-api-profiler.html b/docs/sources/mono-api-profiler.html index fb51ef2e0f7..540a831471d 100644 --- a/docs/sources/mono-api-profiler.html +++ b/docs/sources/mono-api-profiler.html @@ -1,73 +1,193 @@ -

Profiling Interface

- -

Profiler Operation

- -

The following methods can be used by dynamic profiler - methods to monitor different aspects of the program. - -

A custom profiler will have one public method defined in - the shared library which is the entry point that Mono calls at - startup, it has the following signature: - - 

-	void mono_profiler_startup (const char *desc)
-
- -

Where "desc" is the set of arguments that were passed from - the command line. This routine will call - mono_profiler_install to activate the profiler and - will install one or more filters (one of the various - mono_profiler_install_ functions). - -

In addition, a profiler developer will typically call - mono_profiler_set_events to register which kinds of - traces should be enabled, these can be an OR-ed combination of - the following: - - 

-	MONO_PROFILE_NONE
-        MONO_PROFILE_APPDOMAIN_EVENTS
-        MONO_PROFILE_ASSEMBLY_EVENTS
-        MONO_PROFILE_MODULE_EVENTS    
-        MONO_PROFILE_CLASS_EVENTS     
-        MONO_PROFILE_JIT_COMPILATION  
-        MONO_PROFILE_INLINING         
-        MONO_PROFILE_EXCEPTIONS       
-        MONO_PROFILE_ALLOCATIONS      
-        MONO_PROFILE_GC               
-        MONO_PROFILE_THREADS          
-        MONO_PROFILE_REMOTING         
-        MONO_PROFILE_TRANSITIONS      
-        MONO_PROFILE_ENTER_LEAVE      
-        MONO_PROFILE_COVERAGE         
-        MONO_PROFILE_INS_COVERAGE     
-        MONO_PROFILE_STATISTICAL      
-
- -

Developers can change the set of monitored events at - runtime by calling mono_profiler_set_events. - -

mono_profiler_install

-

mono_profiler_install_allocation

-

mono_profiler_install_appdomain

-

mono_profiler_install_assembly

-

mono_profiler_install_class

-

mono_profiler_install_coverage_filter

-

mono_profiler_install_enter_leave

-

mono_profiler_install_jit_compile

-

mono_profiler_install_module

-

mono_profiler_install_thread

-

mono_profiler_install_transition

-

mono_profiler_install_gc

-

mono_profiler_install_statistical

-

mono_profiler_set_events

-

mono_profiler_get_events

- -

Coverage

- -

To support profiling modules that need to do code coverage - analysis, the following routines is provided: - -

mono_profiler_coverage_get

+

Runtime Profiler API

+

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. +

Profiler Modules

+ +

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: + + 


+void mono_profiler_startup_example (const char *desc)
+
+ +

Here, the example portion of the function name is + the name of the profiler module. It must match the shared library + name (i.e. libmono-profiler-example.so). desc + is the set of arguments that were passed from the command line. + +

For example, a bare bones profiler module might look like this + (example.c): + + 


+#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);
+}
+
+ +

To compile this module, a C compiler must be invoked in a + similar fashion to this, on Linux: + + 


+gcc -fPIC -shared -o libmono-profiler-example.so example.c `pkg-config --cflags mono-2`
+
+ +

Or on OS X: + + 


+gcc -undefined suppress -flat_namespace -o libmono-profiler-example.so example.c `pkg-config --cflags mono-2`
+
+ +

You can then load the module using: + + 


+mono --profile=example hello.exe
+
+ +

(Note that adjusting LD_LIBRARY_PATH may be + necessary in order for the dynamic linker to find the module.) + +

Profiler Functions

+ +

These are the functions usable for profiling programs. + +

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). + +

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. + +

Basic Functions

+ +

These functions are used to load and install profilers. + +

mono_profiler_load

+

mono_profiler_create

+

mono_profiler_set_cleanup_callback

+ +

Code Coverage

+ +

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. + +

mono_profiler_enable_coverage

+

mono_profiler_set_coverage_filter_callback

+

mono_profiler_get_coverage_data

+ +

Statistical Sampling

+ +

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. + +

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. + +

mono_profiler_enable_sampling

+

mono_profiler_set_sample_mode

+

mono_profiler_get_sample_mode

+ +

A callback must be registered to receive sample hit events. + Please see the Callback Registration section below. + +

GC Allocations

+ +

Profilers can be notified about all GC allocations performed + by a program or the Mono runtime. + +

mono_profiler_enable_allocations

+ +

A callback must be registered to receive allocation events. + Please see the Callback Registration section below. + +

Call Instrumentation

+ +

The JIT compiler supports instrumenting managed method entry + and exit points so that a profiler callback will be invoked. + +

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. + +

mono_profiler_set_call_instrumentation_filter_callback

+

mono_profiler_enable_call_context_introspection

+

mono_profiler_call_context_get_this

+

mono_profiler_call_context_get_argument

+

mono_profiler_call_context_get_local

+

mono_profiler_call_context_get_result

+

mono_profiler_call_context_free_buffer

+ +

Callbacks must be registered to receive method entry and exit + events. Please see the Callback Registration section + below. + +

Callback Registration

+ +

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 mono/metadata/profiler.h and + mono/metadata/profiler-events.h headers for a full + listing of these. + +

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. + +

API Stability

+ +

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. + +

Therefore, developers of profiler modules may rarely need to + update their code to work with new versions of the profiler API. + +

Developers who wish to support older versions of the API can + perform a compile time check of the + MONO_PROFILER_API_VERSION macro and maintain code + for both old and new versions. + +

To aid with transitioning to a new version of the profiler + API, the Mono runtime will detect and reject loading profiler + modules which were compiled against older profiler API versions. -- cgit v1.2.3