From 7cb11f66cf1745ab84cd2c59a7b4c7999a91d7fa Mon Sep 17 00:00:00 2001 From: Marc Bonnici Date: Fri, 27 Apr 2018 10:57:49 +0100 Subject: [PATCH] doc: add building of instrument method map --- doc/Makefile | 2 +- ...od_map.py => build_instrument_method_map.py} | 6 +++--- doc/source/conf.py | 2 ++ .../developer_reference/writing_extensions.rst | 12 ++++++++---- doc/source/instrument_method_map.template | 17 +++++++++++++++++ 5 files changed, 31 insertions(+), 8 deletions(-) rename doc/{build_instrumentation_method_map.py => build_instrument_method_map.py} (91%) mode change 100755 => 100644 create mode 100644 doc/source/instrument_method_map.template diff --git a/doc/Makefile b/doc/Makefile index 191c4997..6b44bbcb 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -51,7 +51,7 @@ clean: rm -rf $(BUILDDIR)/* rm -rf source/api/* rm -rf source/plugins/* - rm -rf source/instrumentation_method_map.rst + rm -rf source/developer_reference/instrument_method_map.rst coverage: $(SPHINXBUILD) -b coverage $(ALLSPHINXOPTS) $(BUILDDIR)/coverage diff --git a/doc/build_instrumentation_method_map.py b/doc/build_instrument_method_map.py old mode 100755 new mode 100644 similarity index 91% rename from doc/build_instrumentation_method_map.py rename to doc/build_instrument_method_map.py index 2bbd42dd..974824f7 --- a/doc/build_instrumentation_method_map.py +++ b/doc/build_instrument_method_map.py @@ -18,14 +18,14 @@ import sys import string from copy import copy -from wa.framework.instrumentation import SIGNAL_MAP, Priority +from wa.framework.instrument import SIGNAL_MAP, Priority from wa.utils.doc import format_simple_table CONVINIENCE_ALIASES = ['initialize', 'setup', 'start', 'stop', 'process_workload_result', 'update_result', 'teardown', 'finalize'] -OUTPUT_TEMPLATE_FILE = os.path.join(os.path.dirname(__file__), 'source', 'instrumentation_method_map.template') +OUTPUT_TEMPLATE_FILE = os.path.join(os.path.dirname(__file__), 'source', 'instrument_method_map.template') def escape_trailing_underscore(value): @@ -33,7 +33,7 @@ def escape_trailing_underscore(value): return value[:-1] + '\_' -def generate_instrumentation_method_map(outfile): +def generate_instrument_method_map(outfile): signal_table = format_simple_table([(k, v) for k, v in SIGNAL_MAP.iteritems()], headers=['method name', 'signal'], align='<<') priority_table = format_simple_table(zip(Priority.names, Priority.values), diff --git a/doc/source/conf.py b/doc/source/conf.py index 52386faf..cc36b5a9 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -33,6 +33,7 @@ from build_plugin_docs import (generate_plugin_documentation, generate_run_config_documentation, generate_meta_config_documentation, generate_target_documentation) +from build_instrument_method_map import generate_instrument_method_map # If extensions (or modules to document with autodoc) are in another directory, # add these directories to sys.path here. If the directory is relative to the @@ -322,6 +323,7 @@ def setup(app): generate_target_documentation('plugins') generate_run_config_documentation('run_config') generate_meta_config_documentation('run_config') + generate_instrument_method_map(os.path.join('developer_reference', 'instrument_method_map.rst')) app.add_object_type('confval', 'confval', objname='configuration value', indextemplate='pair: %s; configuration value') diff --git a/doc/source/developer_reference/writing_extensions.rst b/doc/source/developer_reference/writing_extensions.rst index 4eab8d58..69181d3f 100644 --- a/doc/source/developer_reference/writing_extensions.rst +++ b/doc/source/developer_reference/writing_extensions.rst @@ -714,10 +714,11 @@ hooked up to the supported signals. Once a signal is broadcasted, the corresponding registered method is invoked. Each method in Instrument must take two arguments, which are self and context. -Supported signals can be found in the :ref:`Signals Documentation -` To make implementations easier and common, the basic -steps to add new instrument is similar to the steps to add new workload and an -example can be found :ref:`here `. +Supported method and their corresponding signals can be found in the +:ref:`Signals Documentation ` To make implementations +easier and common, the basic steps to add new instrument is similar to the steps +to add new workload and an example can be found +:ref:`here `. .. _instrument-api: @@ -871,6 +872,9 @@ Below is a simple instrument that measures the execution time of a workload:: execution_time = self.end_time - self.start_time context.add_metric('execution_time', execution_time, 'seconds') + +.. include:: developer_reference/instrument_method_map.rst + .. _adding-an-output-processor: Adding an Output processor diff --git a/doc/source/instrument_method_map.template b/doc/source/instrument_method_map.template new file mode 100644 index 00000000..6dd36696 --- /dev/null +++ b/doc/source/instrument_method_map.template @@ -0,0 +1,17 @@ +.. _instruments_method_map: + +Instrumentation Signal-Method Mapping +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Instrument methods get automatically hooked up to signals based on their names. Mostly, the method +name correponds to the name of the signal, however there are a few convienience aliases defined +(listed first) to make easier to relate instrumenation code to the workload execution model. + +$signal_names + +The methods above may be decorated with on the listed decorators to set the priority of the +Instrument method realive to other callbacks registered for the signal (within the same priority +level, callbacks are invoked in the order they were registered). The table below shows the mapping +of the decorator to the corresponding priority: + +$priority_prefixes