Create an interface class to describe and document the interface functions.

tools/isolate/trace_inputs.py

 #!/usr/bin/env python
 # coding=utf-8
 # Copyright (c) 2012 The Chromium Authors. All rights reserved.
 # Use of this source code is governed by a BSD-style license that can be
 # found in the LICENSE file.
 
 """Traces an executable and its child processes and extract the files accessed
 by them.
 
 The implementation uses OS-specific API. The native Kernel logger and the ETL
@@ skipping 203 matching lines @@
   """Cleans up a relative path. Converts any os.path.sep to '/' on Windows."""
   if x:
     x = x.rstrip(os.path.sep).replace(os.path.sep, '/')
   if x == '.':
     x = ''
   if x:
     x += '/'
   return x
 
 
-class Strace(object):
+class ApiBase(object):
+  @staticmethod
+  def clean_trace(logname):
+    """Deletes the old log."""
+    raise NotImplementedError()
+
+  @classmethod
+  def gen_trace(cls, cmd, cwd, logname, output):
+    """Runs the OS-specific trace program on an executable.
+
+    Since the logs are per pid, we need to log the list of the initial pid.
+    """
+    raise NotImplementedError(cls.__class__.__name__)
+
+  @classmethod
+  def parse_log(cls, filename, blacklist):
+    """Processes a trace log and returns the files opened and the files that do
+    not exist.
+
+    It does not track directories.
+
+    Most of the time, files that do not exist are temporary test files that
+    should be put in /tmp instead. See http://crbug.com/116251.
+
+    Returns a tuple (existing files, non existing files, nb_processes_created)
+    """
+    raise NotImplementedError(cls.__class__.__name__)
+
+
+class Strace(ApiBase):
   """strace implies linux."""
   IGNORED = (
     '/bin',
     '/dev',
     '/etc',
     '/lib',
     '/proc',
     '/sys',
     '/tmp',
     '/usr',
@@ skipping 240 matching lines @@
           filepath = unicode(filepath)
           if self.blacklist(filepath):
             return
           if os.path.isfile(filepath):
             self.files.add(filepath)
           else:
             self.non_existent.add(filepath)
 
   @staticmethod
   def clean_trace(logname):
-    """Deletes the old log."""
     if os.path.isfile(logname):
       os.remove(logname)
     # Also delete any pid specific file from previous traces.
     for i in glob.iglob(logname + '.*'):
       if i.rsplit('.', 1)[1].isdigit():
         os.remove(i)
 
   @classmethod
   def gen_trace(cls, cmd, cwd, logname, output):
     """Runs strace on an executable.
@@ skipping 21 matching lines @@
       json.dump(
           {
             'cwd': cwd,
             'pid': child.pid,
           },
           f)
     return child.returncode, out
 
   @classmethod
   def parse_log(cls, filename, blacklist):
-    """Processes a strace log and returns the files opened and the files that do
-    not exist.
-
-    It does not track directories.
-
-    Most of the time, files that do not exist are temporary test files that
-    should be put in /tmp instead. See http://crbug.com/116251.
-
-    Returns a tuple (existing files, non existing files, nb_processes_created)
-    """
     logging.info('parse_log(%s, %s)' % (filename, blacklist))
     with open(filename, 'r') as f:
       data = json.load(f)
     context = cls.Context(blacklist, data['cwd'])
     for pidfile in glob.iglob(filename + '.*'):
       pid = pidfile.rsplit('.', 1)[1]
       if pid.isdigit():
         pid = int(pid)
         # TODO(maruel): Load as utf-8
         for line in open(pidfile, 'rb'):
           context.on_line(pid, line)
     context.resolve()
     # Resolve any symlink we hit.
     return (
         set(os.path.realpath(f) for f in context.files),
         set(os.path.realpath(f) for f in context.non_existent),
         len(context.processes))
 
 
-class Dtrace(object):
+class Dtrace(ApiBase):
   """Uses DTrace framework through dtrace. Requires root access.
 
   Implies Mac OSX.
 
   dtruss can't be used because it has compatibility issues with python.
 
   Also, the pid->cwd handling needs to be done manually since OSX has no way to
   get the absolute path of the 'cwd' dtrace variable from the probe.
 
   Also, OSX doesn't populate curpsinfo->pr_psargs properly, see
@@ skipping 245 matching lines @@
           self.files.add(filepath)
         else:
           self.non_existent.add(filepath)
 
     @staticmethod
     def _handle_ignored(_ppid, pid, function, args, result):
       logging.debug('%d %s(%s) = %s' % (pid, function, args, result))
 
   @staticmethod
   def clean_trace(logname):
-    """Deletes the old log."""
     if os.path.isfile(logname):
       os.remove(logname)
 
   @classmethod
   def gen_trace(cls, cmd, cwd, logname, output):
-    """Runs dtrace on an executable."""
+    """Runs dtrace on an executable.
+
+    This dtruss is broken when it starts the process itself or when tracing
+    child processes, this code starts a wrapper process trace_child_process.py,
+    which waits for dtrace to start, then trace_child_process.py starts the
+    executable to trace.
+    """
     logging.info('gen_trace(%s, %s, %s, %s)' % (cmd, cwd, logname, output))
     logging.info('Running: %s' % cmd)
     signal = 'Go!'
     logging.debug('Our pid: %d' % os.getpid())
 
     # Part 1: start the child process.
     stdout = stderr = None
     if output:
       stdout = subprocess.PIPE
       stderr = subprocess.STDOUT
@@ skipping 52 matching lines @@
         cls._sort_log(logname)
     except KeyboardInterrupt:
       # Still sort when testing.
       cls._sort_log(logname)
       raise
 
     return dtrace.returncode or child.returncode, out
 
   @classmethod
   def parse_log(cls, filename, blacklist):
-    """Processes a dtrace log and returns the files opened and the files that do
-    not exist.
-
-    It does not track directories.
-
-    Most of the time, files that do not exist are temporary test files that
-    should be put in /tmp instead. See http://crbug.com/116251
-
-    Returns a tuple (existing files, non existing files, nb_processes_created)
-    """
     logging.info('parse_log(%s, %s)' % (filename, blacklist))
     context = cls.Context(blacklist)
     for line in open(filename, 'rb'):
       context.on_line(line)
     # Resolve any symlink we hit.
     return (
         set(os.path.realpath(f) for f in context.files),
         set(os.path.realpath(f) for f in context.non_existent),
         context.nb_processes)
 
   @staticmethod
   def _sort_log(logname):
     """Sorts the log back in order when each call occured.
 
     dtrace doesn't save the buffer in strict order since it keeps one buffer per
     CPU.
     """
     with open(logname, 'rb') as logfile:
       lines = [f for f in logfile.readlines() if f.strip()]
     lines = sorted(lines, key=lambda l: int(l.split(' ', 1)[0]))
     with open(logname, 'wb') as logfile:
       logfile.write(''.join(lines))
 
 
-class LogmanTrace(object):
+class LogmanTrace(ApiBase):
   """Uses the native Windows ETW based tracing functionality to trace a child
   process.
   """
   class Context(object):
     """Processes a ETW log line and keeps the list of existent and non
     existent files accessed.
 
     Ignores directories.
     """
 
@@ skipping 165 matching lines @@
           filename in self.files or
           filename in self.non_existent):
         return
       logging.debug('_handle_file(%s)' % filename)
       if os.path.isfile(filename):
         self.files.add(filename)
       else:
         self.non_existent.add(filename)
 
   def __init__(self):
+    super(LogmanTrace, self).__init__()
     # Most ignores need to be determined at runtime.
     self.IGNORED = set([os.path.dirname(sys.executable)])
     # Add many directories from environment variables.
     vars_to_ignore = (
       'APPDATA',
       'LOCALAPPDATA',
       'ProgramData',
       'ProgramFiles',
       'ProgramFiles(x86)',
       'ProgramW6432',
       'SystemRoot',
       'TEMP',
       'TMP',
     )
     for i in vars_to_ignore:
       if os.environ.get(i):
         self.IGNORED.add(os.environ[i])
 
     # Also add their short path name equivalents.
     for i in list(self.IGNORED):
       self.IGNORED.add(GetShortPathName(i))
 
     # Add this one last since it has no short path name equivalent.
     self.IGNORED.add('\\systemroot')
     self.IGNORED = tuple(sorted(self.IGNORED))
 
   @staticmethod
   def clean_trace(logname):
-    """Deletes the old log."""
     if os.path.isfile(logname):
       os.remove(logname)
     if os.path.isfile(logname + '.etl'):
       os.remove(logname + '.etl')
 
   @classmethod
   def gen_trace(cls, cmd, cwd, logname, output):
+    """Uses logman.exe to start and stop the NT Kernel Logger while the
+    executable to be traced is run.
+    """
     logging.info('gen_trace(%s, %s, %s, %s)' % (cmd, cwd, logname, output))
     # Use "logman -?" for help.
 
     etl = logname + '.etl'
 
     stdout = stderr = None
     if output:
       stdout = subprocess.PIPE
       stderr = subprocess.STDOUT
 
@@ skipping 67 matching lines @@
     else:
       assert False, logformat
     logging.debug('Running: %s' % cmd_convert)
     subprocess.check_call(
         cmd_convert, stdin=subprocess.PIPE, stdout=stdout, stderr=stderr)
 
     return child.returncode, out
 
   @classmethod
   def parse_log(cls, filename, blacklist):
-    """Processes a ETL log and returns the files opened and the files that do
-    not exist.
-
-    It does not track directories.
-
-    Most of the time, files that do not exist are temporary test files that
-    should be put in /tmp instead. See http://crbug.com/116251
-
-    Returns a tuple (existing files, non existing files, nb_processes_created)
-    """
     logging.info('parse_log(%s, %s)' % (filename, blacklist))
 
     # Auto-detect the log format
     with open(filename, 'rb') as f:
       hdr = f.read(2)
       assert len(hdr) == 2
       if hdr == '<E':
         # It starts with <Events>
         logformat = 'xml'
       elif hdr == '\xFF\xEF':
@@ skipping 363 matching lines @@
       os.path.abspath(options.log),
       args,
       options.root_dir,
       options.cwd,
       options.product_dir,
       options.force)
 
 
 if __name__ == '__main__':
   sys.exit(main())