docs: def pausable_restart_on_change(restart_map, stopstart=False,
                                 restart_functions=None):
      """A restart_on_change decorator that checks to see if the unit is
      paused. If it is paused then the decorated function doesn't fire.
  
      This is provided as a helper, as the @restart_on_change(...) decorator
      is in core.host, yet the openstack specific helpers are in this file
      (contrib.openstack.utils).  Thus, this needs to be an optional feature
      for openstack charms (or charms that wish to use the openstack
      pause/resume type features).
  
      It is used as follows:
  
          from contrib.openstack.utils import (
              pausable_restart_on_change as restart_on_change)
  
          @restart_on_change(restart_map, stopstart=<boolean>)
          def some_hook(...):
              pass
  
      see core.utils.restart_on_change() for more details.
  
      Note restart_map can be a callable, in which case, restart_map is only
      evaluated at runtime.  This means that it is lazy and the underlying
      function won't be called if the decorated function is never called.  Note,
      retains backwards compatibility for passing a non-callable dictionary.
  
      @param f: the function to decorate
      @param restart_map: (optionally callable, which then returns the
          restart_map) the restart map {conf_file: [services]}
      @param stopstart: DEFAULT false; whether to stop, start or just restart
      @returns decorator to use a restart_on_change with pausability
      """
      def wrap(f):
          # py27 compatible nonlocal variable.  When py3 only, replace with
          # nonlocal keyword
          __restart_map_cache = {'cache': None}
  
          @functools.wraps(f)
          def wrapped_f(*args, **kwargs):
              if is_unit_paused_set():
                  return f(*args, **kwargs)
              if __restart_map_cache['cache'] is None:
                  __restart_map_cache['cache'] = restart_map() \
                      if callable(restart_map) else restart_map
              # otherwise, normal restart_on_change functionality
              return restart_on_change_helper(
                  (lambda: f(*args, **kwargs)), __restart_map_cache['cache'],
                  stopstart, restart_functions)
          return wrapped_f
      return wrap