site_scons/site_tools/defer.py

   1 #!/usr/bin/python2.4
   2 # Copyright 2009, Google Inc.
   3 # All rights reserved.
   4 #
   5 # Redistribution and use in source and binary forms, with or without
   6 # modification, are permitted provided that the following conditions are
   7 # met:
   8 #
   9 #     * Redistributions of source code must retain the above copyright
  10 # notice, this list of conditions and the following disclaimer.
  11 #     * Redistributions in binary form must reproduce the above
  12 # copyright notice, this list of conditions and the following disclaimer
  13 # in the documentation and/or other materials provided with the
  14 # distribution.
  15 #     * Neither the name of Google Inc. nor the names of its
  16 # contributors may be used to endorse or promote products derived from
  17 # this software without specific prior written permission.
  18 #
  19 # THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  20 # "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  21 # LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  22 # A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  23 # OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  24 # SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  25 # LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  26 # DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  27 # THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  28 # (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  29 # OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  30
  31 """Defer tool for SCons."""
  32
  33
  34 import os
  35 import sys
  36 import types
  37 import SCons.Errors
  38
  39
  40 # Current group name being executed by ExecuteDefer().  Set to None outside
  41 # of ExecuteDefer().
  42 _execute_defer_context = None
  43
  44
  45 class DeferGroup:
  46   """Named list of functions to be deferred."""
  47   # If we derive DeferGroup from object, instances of it return type
  48   # <class 'defer.DeferGroup'>, which prevents SCons.Util.semi_deepcopy()
  49   # from calling its __semi_deepcopy__ function.
  50   # TODO: Make semi_deepcopy() capable of handling classes derived from
  51   # object.
  52
  53   def __init__(self):
  54     """Initialize deferred function object."""
  55     self.func_env_cwd = []
  56     self.after = set()
  57
  58   def __semi_deepcopy__(self):
  59     """Makes a semi-deep-copy of this object.
  60
  61     Returns:
  62       A semi-deep-copy of this object.
  63
  64     This means it copies the sets and lists contained by this object, but
  65     doesn't make copies of the function pointers and environments pointed to by
  66     those lists.
  67
  68     Needed so env.Clone() makes a copy of the defer list, so that functions
  69     and after-relationships subsequently added to the clone are not added to
  70     the parent.
  71     """
  72     c = DeferGroup()
  73     c.func_env_cwd = self.func_env_cwd[:]
  74     c.after = self.after.copy()
  75     return c
  76
  77
  78 def SetDeferRoot(self):
  79   """Sets the current environment as the root environment for defer.
  80
  81   Args:
  82     self: Current environment context.
  83
  84   Functions deferred by environments cloned from the root environment (that is,
  85   function deferred by children of the root environment) will be executed when
  86   ExecuteDefer() is called from the root environment.
  87
  88   Functions deferred by environments from which the root environment was cloned
  89   (that is, functions deferred by parents of the root environment) will be
  90   passed the root environment instead of the original parent environment.
  91   (Otherwise, they would have no way to determine the root environment.)
  92   """
  93   # Set the current environment as the root for holding defer groups
  94   self['_DEFER_ROOT_ENV'] = self
  95
  96   # Deferred functions this environment got from its parents will be run in the
  97   # new root context.
  98   for group in GetDeferGroups(self).values():
  99     new_list = [(func, self, cwd) for (func, env, cwd) in group.func_env_cwd]
 100     group.func_env_cwd = new_list
 101
 102
 103 def GetDeferRoot(self):
 104   """Returns the root environment for defer.
 105
 106   Args:
 107     self: Current environment context.
 108
 109   Returns:
 110     The root environment for defer.  If one of this environment's parents
 111     called SetDeferRoot(), returns that environment.  Otherwise returns the
 112     current environment.
 113   """
 114   return self.get('_DEFER_ROOT_ENV', self)
 115
 116
 117 def GetDeferGroups(env):
 118   """Returns the dict of defer groups from the root defer environment.
 119
 120   Args:
 121     env: Environment context.
 122
 123   Returns:
 124     The dict of defer groups from the root defer environment.
 125   """
 126   return env.GetDeferRoot()['_DEFER_GROUPS']
 127
 128
 129 def ExecuteDefer(self):
 130   """Executes deferred functions.
 131
 132   Args:
 133     self: Current environment context.
 134   """
 135   # Check for re-entrancy
 136   global _execute_defer_context
 137   if _execute_defer_context:
 138     raise SCons.Errors.UserError('Re-entrant call to ExecuteDefer().')
 139
 140   # Save directory, so SConscript functions can occur in the right subdirs
 141   oldcwd = os.getcwd()
 142
 143   # If defer root is set and isn't this environment, we're being called from a
 144   # sub-environment.  That's not where we should be called.
 145   if self.GetDeferRoot() != self:
 146     print ('Warning: Ignoring call to ExecuteDefer() from child of the '
 147            'environment passed to SetDeferRoot().')
 148     return
 149
 150   # Get list of defer groups from ourselves.
 151   defer_groups = GetDeferGroups(self)
 152
 153   # Loop through deferred functions
 154   try:
 155     while defer_groups:
 156       did_work = False
 157       for name, group in defer_groups.items():
 158         if group.after.intersection(defer_groups.keys()):
 159           continue        # Still have dependencies
 160
 161         # Set defer context
 162         _execute_defer_context = name
 163
 164         # Remove this group from the list of defer groups now, in case one of
 165         # the functions it calls adds back a function into that defer group.
 166         del defer_groups[name]
 167
 168         if group.func_env_cwd:
 169           # Run all the functions in our named group
 170           for func, env, cwd in group.func_env_cwd:
 171             os.chdir(cwd)
 172             func(env)
 173
 174         # The defer groups have been altered, so restart the search for
 175         # functions that can be executed.
 176         did_work = True
 177         break
 178
 179       if not did_work:
 180         errmsg = 'Error in ExecuteDefer: dependency cycle detected.\n'
 181         for name, group in defer_groups.items():
 182           errmsg += '   %s after: %s\n' % (name, group.after)
 183         raise SCons.Errors.UserError(errmsg)
 184   finally:
 185     # No longer in a defer context
 186     _execute_defer_context = None
 187
 188   # Restore directory
 189   os.chdir(oldcwd)
 190
 191
 192 def PrintDefer(self, print_functions=True):
 193   """Prints the current defer dependency graph.
 194
 195   Args:
 196     self: Environment in which PrintDefer() was called.
 197     print_functions: Print individual functions in defer groups.
 198   """
 199   # Get the defer dict
 200   # Get list of defer groups from ourselves.
 201   defer_groups = GetDeferGroups(self)
 202   dgkeys = defer_groups.keys()
 203   dgkeys.sort()
 204   for k in dgkeys:
 205     print ' +- %s' % k
 206     group = defer_groups[k]
 207     after = list(group.after)
 208     if after:
 209       print ' |  after'
 210       after.sort()
 211       for a in after:
 212         print ' |   +- %s' % a
 213     if print_functions and group.func_env_cwd:
 214       print '    functions'
 215       for func, env, cwd in group.func_env_cwd:
 216         print ' |   +- %s %s' % (func.__name__, cwd)
 217
 218
 219 def Defer(self, *args, **kwargs):
 220   """Adds a deferred function or modifies defer dependencies.
 221
 222   Args:
 223     self: Environment in which Defer() was called
 224     args: Positional arguments
 225     kwargs: Named arguments
 226
 227   The deferred function will be passed the environment used to call Defer(),
 228   and will be executed in the same working directory as the calling SConscript.
 229   (Exception: if this environment is cloned and the clone calls SetDeferRoot()
 230   and then ExecuteDefer(), the function will be passed the root environment,
 231   instead of the environment used to call Defer().)
 232
 233   All deferred functions run after all SConscripts.  Additional dependencies
 234   may be specified with the after= keyword.
 235
 236   Usage:
 237
 238     env.Defer(func)
 239       # Defer func() until after all SConscripts
 240
 241     env.Defer(func, after=otherfunc)
 242       # Defer func() until otherfunc() runs
 243
 244     env.Defer(func, 'bob')
 245       # Defer func() until after SConscripts, put in group 'bob'
 246
 247     env.Defer(func2, after='bob')
 248       # Defer func2() until after all funcs in 'bob' group have run
 249
 250     env.Defer(func3, 'sam')
 251       # Defer func3() until after SConscripts, put in group 'sam'
 252
 253     env.Defer('bob', after='sam')
 254       # Defer all functions in group 'bob' until after all functions in group
 255       # 'sam' have run.
 256
 257     env.Defer(func4, after=['bob', 'sam'])
 258       # Defer func4() until after all functions in groups 'bob' and 'sam' have
 259       # run.
 260   """
 261   # Get name of group to defer and/or the a function
 262   name = None
 263   func = None
 264   for a in args:
 265     if isinstance(a, str):
 266       name = a
 267     elif isinstance(a, types.FunctionType):
 268       func = a
 269   if func and not name:
 270     name = func.__name__
 271
 272   # TODO: Why not allow multiple functions?  Should be ok
 273
 274   # Get list of names and/or functions this function should defer until after
 275   after = []
 276   for a in self.Flatten(kwargs.get('after')):
 277     if isinstance(a, str):
 278       # TODO: Should check if '$' in a, and if so, subst() it and recurse into
 279       # it.
 280       after.append(a)
 281     elif isinstance(a, types.FunctionType):
 282       after.append(a.__name__)
 283     elif a is not None:
 284       # Deferring
 285       raise ValueError('Defer after=%r is not a function or name' % a)
 286
 287   # Find the deferred function
 288   defer_groups = GetDeferGroups(self)
 289   if name not in defer_groups:
 290     defer_groups[name] = DeferGroup()
 291   group = defer_groups[name]
 292
 293   # If we were given a function, also save environment and current directory
 294   if func:
 295     group.func_env_cwd.append((func, self, os.getcwd()))
 296
 297   # Add dependencies for the function
 298   group.after.update(after)
 299
 300   # If we are already inside a call to ExecuteDefer(), any functions which are
 301   # deferring until after the current function must also be deferred until
 302   # after this new function.  In short, this means that if b() defers until
 303   # after a() and a() calls Defer() to defer c(), then b() must also defer
 304   # until after c().
 305   if _execute_defer_context and name != _execute_defer_context:
 306     for other_name, other_group in GetDeferGroups(self).items():
 307       if other_name == name:
 308         continue        # Don't defer after ourselves
 309       if _execute_defer_context in other_group.after:
 310         other_group.after.add(name)
 311
 312
 313 def generate(env):
 314   # NOTE: SCons requires the use of this name, which fails gpylint.
 315   """SCons entry point for this tool."""
 316   env.Append(_DEFER_GROUPS={})
 317
 318   env.AddMethod(Defer)
 319   env.AddMethod(ExecuteDefer)
 320   env.AddMethod(GetDeferRoot)
 321   env.AddMethod(PrintDefer)
 322   env.AddMethod(SetDeferRoot)