Instrumenter region name (#62)

It is now possible to name parts of the code, where the instrumenter was enabled or disabled.

Author: AndreasGocht

README.md

@@ -119,7 +119,53 @@ with scorep.instrumenter.enable():
     do_something()    
 ```
 
-or during startup with `--noinstrumenter`. Please be aware that the function calls override the Flag.
+or during startup with `--noinstrumenter`. The given function calls override this flag.
+
+The main idea is to reduce the instrumentation overhead for regions that are not of interest.
+Whenever the instrumenter is disabled, function enter or exits will not be trace.
+
+As an example:
+
+```
+import numpy as np
+
+[...]
+c = np.dot(a,b)
+[...]
+```
+
+You might not be interested, what happens during the import of numpy, but actually how long `dot` takes.
+If you change the code to
+
+```
+import numpy as np
+import scorep
+
+[...]
+with scorep.instrumenter.enable():
+    c = np.dot(a,b)
+[...]
+```
+and run the code with `python -m scorep --noinstrumenter run.py` only the call to np.dot and everything below will be instrumented.
+Please be aware, that user instrumentation, using scorep.user will always be recorded.
+
+
+With version 3.1 the bindings support the annotation of regions where the instrumenter was explicit enabled or disabled.
+You can now pass a `region_name` to `scorep.instrumenter.enable("enabled_region_name")` and `scorep.instrumenter.disable("disabled_region_name")`.
+This might be useful if you do something expensive, and just want to know how long it takes, but you do not care what happens exactly e.g.:
+
+```
+[...]
+def fun_calls(n):
+    if (n>0):
+        fun_calls(n-1)
+
+with scorep.instrumenter.disable("my_fun_calls"):
+    fun_calls(1000000)
+[...]
+```
+
+`my_fun_calls` will be present in the trace or profile but `fun_calls` will not.
 
 ## Overview about Flags
 

scorep/instrumenter.py

@@ -2,6 +2,9 @@
 import scorep.instrumenters.scorep_profile
 import scorep.instrumenters.scorep_trace
 
+import inspect
+import os
+
 global_instrumenter = None
 
 
@@ -55,24 +58,42 @@ class enable():
     """
     Context manager to enable tracing in a certain region:
     ```
-    with enable():
+    with enable(region_name=None):
         do stuff
     ```
     This overides --no-instrumenter (--nopython leagacy)
+    @param region_name: if a region name is given, the region the contextmanager is active will be marked in the trace or profile
     """
 
-    def __init__(self):
-        pass
+    def __init__(self, region_name=None):
+        self.region_name = region_name
 
     def __enter__(self):
         self.tracer_registered = scorep.instrumenter.get_instrumenter().get_registered()
         if not self.tracer_registered:
+            if self.region_name:
+                self.module_name = "user_instrumenter"
+                frame = inspect.currentframe().f_back
+                file_name = frame.f_globals.get('__file__', None)
+                line_number = frame.f_lineno
+                if file_name is not None:
+                    full_file_name = os.path.abspath(file_name)
+                else:
+                    full_file_name = "None"
+
+                scorep.instrumenter.get_instrumenter().region_begin(
+                    self.module_name, self.region_name, full_file_name, line_number)
+
             scorep.instrumenter.get_instrumenter().register()
 
     def __exit__(self, exc_type, exc_value, traceback):
         if not self.tracer_registered:
             scorep.instrumenter.get_instrumenter().unregister()
 
+            if self.region_name is not None:
+                scorep.instrumenter.get_instrumenter().region_end(
+                    self.module_name, self.region_name)
+
 
 class disable():
     """
@@ -82,16 +103,34 @@ class disable():
         do stuff
     ```
     This overides --no-instrumenter (--nopython leagacy)
+    @param region_name: if a region name is given, the region the contextmanager is active will be marked in the trace or profile
     """
 
-    def __init__(self):
-        pass
+    def __init__(self, region_name=None):
+        self.region_name = region_name
 
     def __enter__(self):
         self.tracer_registered = scorep.instrumenter.get_instrumenter().get_registered()
         if self.tracer_registered:
             scorep.instrumenter.get_instrumenter().unregister()
 
+            if self.region_name is not None:
+                self.module_name = "user_instrumenter"
+                frame = inspect.currentframe().f_back
+                file_name = frame.f_globals.get('__file__', None)
+                line_number = frame.f_lineno
+                if file_name is not None:
+                    full_file_name = os.path.abspath(file_name)
+                else:
+                    full_file_name = "None"
+
+                scorep.instrumenter.get_instrumenter().region_begin(
+                    self.module_name, self.region_name, full_file_name, line_number)
+
     def __exit__(self, exc_type, exc_value, traceback):
         if self.tracer_registered:
+            if self.region_name is not None:
+                scorep.instrumenter.get_instrumenter().region_end(
+                    self.module_name, self.region_name)
+
             scorep.instrumenter.get_instrumenter().register()