scripts/tracetool/backend/__init__.py

   1 #!/usr/bin/env python
   2 # -*- coding: utf-8 -*-
   3
   4 """
   5 Backend management.
   6
   7
   8 Creating new backends
   9 ---------------------
  10
  11 A new backend named 'foo-bar' corresponds to Python module
  12 'tracetool/backend/foo_bar.py'.
  13
  14 A backend module should provide a docstring, whose first non-empty line will be
  15 considered its short description.
  16
  17 All backends must generate their contents through the 'tracetool.out' routine.
  18
  19
  20 Backend attributes
  21 ------------------
  22
  23 ========= ====================================================================
  24 Attribute Description
  25 ========= ====================================================================
  26 PUBLIC    If exists and is set to 'True', the backend is considered "public".
  27 ========= ====================================================================
  28
  29
  30 Backend functions
  31 -----------------
  32
  33 ======== =======================================================================
  34 Function Description
  35 ======== =======================================================================
  36 <format> Called to generate the format- and backend-specific code for each of
  37          the specified events. If the function does not exist, the backend is
  38          considered not compatible with the given format.
  39 ======== =======================================================================
  40 """
  41
  42 __author__     = "Lluís Vilanova <vilanova@ac.upc.edu>"
  43 __copyright__  = "Copyright 2012, Lluís Vilanova <vilanova@ac.upc.edu>"
  44 __license__    = "GPL version 2 or (at your option) any later version"
  45
  46 __maintainer__ = "Stefan Hajnoczi"
  47 __email__      = "stefanha@linux.vnet.ibm.com"
  48
  49
  50 import os
  51
  52 import tracetool
  53
  54
  55 def get_list(only_public = False):
  56     """Get a list of (name, description) pairs."""
  57     res = [("nop", "Tracing disabled.")]
  58     modnames = []
  59     for filename in os.listdir(tracetool.backend.__path__[0]):
  60         if filename.endswith('.py') and filename != '__init__.py':
  61             modnames.append(filename.rsplit('.', 1)[0])
  62     for modname in modnames:
  63         module = tracetool.try_import("tracetool.backend." + modname)
  64
  65         # just in case; should never fail unless non-module files are put there
  66         if not module[0]:
  67             continue
  68         module = module[1]
  69
  70         public = getattr(module, "PUBLIC", False)
  71         if only_public and not public:
  72             continue
  73
  74         doc = module.__doc__
  75         if doc is None:
  76             doc = ""
  77         doc = doc.strip().split("\n")[0]
  78
  79         name = modname.replace("_", "-")
  80         res.append((name, doc))
  81     return res
  82
  83
  84 def exists(name):
  85     """Return whether the given backend exists."""
  86     if len(name) == 0:
  87         return False
  88     if name == "nop":
  89         return True
  90     name = name.replace("-", "_")
  91     return tracetool.try_import("tracetool.backend." + name)[1]
  92
  93
  94 def compatible(backend, format):
  95     """Whether a backend is compatible with the given format."""
  96     if not exists(backend):
  97         raise ValueError("unknown backend: %s" % backend)
  98
  99     backend = backend.replace("-", "_")
 100     format = format.replace("-", "_")
 101
 102     if backend == "nop":
 103         return True
 104     else:
 105         func = tracetool.try_import("tracetool.backend." + backend,
 106                                     format, None)[1]
 107         return func is not None
 108
 109
 110 def _empty(events):
 111     pass
 112
 113 def generate(backend, format, events):
 114     """Generate the per-event output for the given (backend, format) pair."""
 115     if not compatible(backend, format):
 116         raise ValueError("backend '%s' not compatible with format '%s'" %
 117                          (backend, format))
 118
 119     backend = backend.replace("-", "_")
 120     format = format.replace("-", "_")
 121
 122     if backend == "nop":
 123         func = tracetool.try_import("tracetool.format." + format,
 124                                     "nop", _empty)[1]
 125     else:
 126         func = tracetool.try_import("tracetool.backend." + backend,
 127                                     format, None)[1]
 128
 129     func(events)