From: Alex Rønne Petersen <alexrp@xamarin.com>
Date: Tue, 21 Apr 2015 02:43:46 +0000 (+0200)
Subject: [runtime] Introduce versioning of the profiler API.
X-Git-Url: http://wien.tomnetworks.com/gitweb/?a=commitdiff_plain;h=138ae5a07f7d6adba597c23c23b088c5e768f8b7;hp=cd10756a3c6cf7c9d54c8d01073a610a019e0c7a;p=mono.git

[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 6c99a60b788..e113e535a59 100644
--- 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 42e2f1f27dd..b0250d9bc97 100644
--- 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 cf1cc148e1b..18626489afc 100644
--- 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 a6d13a07316..3bfa23a77fd 100644
--- 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 ba614b4de7e..0aa878ab116 100644
--- 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 bc0dd2c1b65..926d6a8385d 100644
--- 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 3f071a10879..3db0659c775 100644
--- 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 d10c82a574d..a43cb77aac9 100644
--- 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);