[runtime] Introduce versioning of the profiler API.

The profiler API needs to evolve with the runtime. By versioning the API we can
at least to some degree let developers know when their modules are out of date
and how to update them.

diff --git a/mono/metadata/profiler.c b/mono/metadata/profiler.c
index 6c99a60b788fcfcca60582a0e2c299c086f584e9..e113e535a59c710993b8ca9312a6e929355424ea 100644 (file)
--- a/mono/metadata/profiler.c
+++ b/mono/metadata/profiler.c
@@ -116,6 +116,7 @@ MonoProfileFlags mono_profiler_events;
 /**
  * mono_profiler_install:
  * @prof: a MonoProfiler structure pointer, or a pointer to a derived structure.
+ * @version: profiler API version (see profiler.h)
  * @callback: the function to invoke at shutdown
  *
  * Use mono_profiler_install to activate profiling in the Mono runtime.
@@ -125,8 +126,11 @@ MonoProfileFlags mono_profiler_events;
  *
  */
 void
-mono_profiler_install (MonoProfiler *prof, MonoProfileFunc callback)
+mono_profiler_install (MonoProfiler *prof, int version, MonoProfileFunc callback)
 {
+       if (version != MONO_PROFILER_VERSION)
+               g_warning ("Profiler module API version (%i) potentially incompatible with current API version (%i)", version, MONO_PROFILER_VERSION);
+
        ProfilerDesc *desc = g_new0 (ProfilerDesc, 1);
        if (!prof_list)
                mono_mutex_init_recursive (&profiler_coverage_mutex);

diff --git a/mono/metadata/profiler.h b/mono/metadata/profiler.h
index 42e2f1f27dd50f0ce0f9e4d56a518729235b9736..b0250d9bc976752d64e4e2a600032c38b75e4994 100644 (file)
--- a/mono/metadata/profiler.h
+++ b/mono/metadata/profiler.h
@@ -6,6 +6,29 @@
 
 MONO_BEGIN_DECLS
 
+/*
+ * The profiler API is considered unstable because it needs to evolve with the
+ * Mono runtime. Profilers will pass in the profiler API version they are built
+ * against when calling mono_profiler_install (). If the profiler API version
+ * of the runtime is not equal to the one passed in, Mono will print a warning
+ * letting developers know that a profiler module needs to be updated.
+ *
+ * When you have updated a module to be compatible with a version of the
+ * profiler API, make it pass in the current value of MONO_PROFILER_VERSION.
+ * Pass the value literally; using the macro will defeat the purpose.
+ * (Modules within Mono are exceptions to this rule.)
+ *
+ * mono_profiler_install () is the single function guaranteed to be stable.
+ *
+ * -- Change Log --
+ *
+ * Version 1:
+ *
+ *  - Introduced profiler API versioning.
+ */
+
+#define MONO_PROFILER_VERSION 1
+
 #define MONO_PROFILER_MAX_STAT_CALL_CHAIN_DEPTH 128
 
 typedef enum {
@@ -160,7 +183,7 @@ typedef void (*MonoProfilerCodeBufferNew) (MonoProfiler *prof, void* buffer, int
 /*
  * Function the profiler may call.
  */
-MONO_API void mono_profiler_install       (MonoProfiler *prof, MonoProfileFunc shutdown_callback);
+MONO_API void mono_profiler_install       (MonoProfiler *prof, int version, MonoProfileFunc shutdown_callback);
 MONO_API void mono_profiler_set_events    (MonoProfileFlags events);
 
 MONO_API MonoProfileFlags mono_profiler_get_events (void);

diff --git a/mono/mini/debugger-agent.c b/mono/mini/debugger-agent.c
index cf1cc148e1b3c82629a98374e3f5a8880f4e4e6b..18626489afc2407dca878a01c69169b3b3fbfa59 100644 (file)
--- a/mono/mini/debugger-agent.c
+++ b/mono/mini/debugger-agent.c
@@ -991,7 +991,7 @@ mono_debugger_agent_init (void)
        mono_mutex_init (&debugger_thread_exited_mutex);
        mono_cond_init (&debugger_thread_exited_cond, NULL);
 
-       mono_profiler_install ((MonoProfiler*)&debugger_profiler, runtime_shutdown);
+       mono_profiler_install ((MonoProfiler*)&debugger_profiler, MONO_PROFILER_VERSION, runtime_shutdown);
        mono_profiler_set_events (MONO_PROFILE_APPDOMAIN_EVENTS | MONO_PROFILE_THREADS | MONO_PROFILE_ASSEMBLY_EVENTS | MONO_PROFILE_JIT_COMPILATION | MONO_PROFILE_METHOD_EVENTS);
        mono_profiler_install_runtime_initialized (runtime_initialized);
        mono_profiler_install_appdomain (NULL, appdomain_load, appdomain_start_unload, appdomain_unload);

diff --git a/mono/profiler/mono-codeanalyst.c b/mono/profiler/mono-codeanalyst.c
index a6d13a0731674040ffd6e5d3bed2e921b081dbd9..3bfa23a77fdf06899ab0d6d48c0a94e576d83545 100644 (file)
--- a/mono/profiler/mono-codeanalyst.c
+++ b/mono/profiler/mono-codeanalyst.c
@@ -73,7 +73,7 @@ mono_profiler_startup (const char *desc)
 {
        CAJIT_Initialize ();
 
-       mono_profiler_install (NULL, codeanalyst_shutdown);
+       mono_profiler_install (NULL, MONO_PROFILER_VERSION, codeanalyst_shutdown);
        mono_profiler_install_jit_end (method_jit_result);
        mono_profiler_set_events (MONO_PROFILE_JIT_COMPILATION);
 }

diff --git a/mono/profiler/mono-profiler-aot.c b/mono/profiler/mono-profiler-aot.c
index ba614b4de7e0f6c55e4cd49ce7c433522f6344c1..0aa878ab1166c56e00b62afedf2d00f4efe7d90f 100644 (file)
--- a/mono/profiler/mono-profiler-aot.c
+++ b/mono/profiler/mono-profiler-aot.c
@@ -145,7 +145,7 @@ mono_profiler_startup (const char *desc)
        prof = g_new0 (MonoProfiler, 1);
        prof->images = g_hash_table_new (NULL, NULL);
 
-       mono_profiler_install (prof, prof_shutdown);
+       mono_profiler_install (prof, MONO_PROFILER_VERSION, prof_shutdown);
        
        mono_profiler_install_jit_compile (prof_jit_enter, prof_jit_leave);
 

diff --git a/mono/profiler/mono-profiler-iomap.c b/mono/profiler/mono-profiler-iomap.c
index bc0dd2c1b65cc1ad70d71a62ae54332c18750afa..926d6a8385d8decea99cc7b3826de80a3945e708 100644 (file)
--- a/mono/profiler/mono-profiler-iomap.c
+++ b/mono/profiler/mono-profiler-iomap.c
@@ -537,7 +537,7 @@ void mono_profiler_startup (const char *desc)
        prof->saved_strings_hash = g_hash_table_new (NULL, NULL);
        prof->string_locations_hash = g_hash_table_new (mismatched_files_guint32_hash, mismatched_files_guint32_equal);
 
-       mono_profiler_install (prof, profiler_shutdown);
+       mono_profiler_install (prof, MONO_PROFILER_VERSION, profiler_shutdown);
        mono_profiler_install_runtime_initialized (runtime_initialized_cb);
        mono_profiler_install_iomap (mono_portability_iomap_event);
        mono_profiler_install_allocation (mono_portability_remember_alloc);

diff --git a/mono/profiler/mono-profiler-vtune.c b/mono/profiler/mono-profiler-vtune.c
index 3f071a108798834e9b64cbc978a537336940bb8b..3db0659c77549777b62e6b86fe53217c1495eea2 100644 (file)
--- a/mono/profiler/mono-profiler-vtune.c
+++ b/mono/profiler/mono-profiler-vtune.c
@@ -167,7 +167,7 @@ mono_profiler_startup (const char *desc)
        iJIT_IsProfilingActiveFlags flags = iJIT_IsProfilingActive();
        if (flags == iJIT_SAMPLING_ON)
        {
-               mono_profiler_install (NULL, codeanalyst_shutdown);
+               mono_profiler_install (NULL, MONO_PROFILER_VERSION, codeanalyst_shutdown);
                mono_profiler_install_jit_end (method_jit_result);
                mono_profiler_install_code_buffer_new (code_buffer_new);
                mono_profiler_set_events (MONO_PROFILE_JIT_COMPILATION);

diff --git a/mono/profiler/proflog.c b/mono/profiler/proflog.c
index d10c82a574d2923aa5d6da4b361af0cbe16aab4a..a43cb77aac92218b8fbb20890185706c8b6c510b 100644 (file)
--- a/mono/profiler/proflog.c
+++ b/mono/profiler/proflog.c
@@ -3284,7 +3284,7 @@ mono_profiler_startup (const char *desc)
                return;
        init_thread ();
 
-       mono_profiler_install (prof, log_shutdown);
+       mono_profiler_install (prof, MONO_PROFILER_VERSION, log_shutdown);
        mono_profiler_install_gc (gc_event, gc_resize);
        mono_profiler_install_allocation (gc_alloc);
        mono_profiler_install_gc_moves (gc_moves);