diff --git a/external/fv3gfs-util/fv3gfs/util/_timing.py b/external/fv3gfs-util/fv3gfs/util/_timing.py index ea03c20be..77035ab8c 100644 --- a/external/fv3gfs-util/fv3gfs/util/_timing.py +++ b/external/fv3gfs-util/fv3gfs/util/_timing.py @@ -5,12 +5,15 @@ class Timer: + """Class to accumulate timings for named operations.""" + def __init__(self): self._clock_starts = {} self._accumulated_time = {} self._enabled = True def start(self, name): + """Start timing a given named operation.""" if self._enabled: if name in self._clock_starts: raise ValueError(f"clock already started for '{name}'") @@ -18,6 +21,9 @@ def start(self, name): self._clock_starts[name] = time() def stop(self, name): + """Stop timing a given named operation, and add the time elapsed to + accumulated timing. + """ if self._enabled: if name not in self._accumulated_time: self._accumulated_time[name] = time() - self._clock_starts.pop(name) @@ -26,12 +32,31 @@ def stop(self, name): @contextlib.contextmanager def clock(self, name): + """Context manager to produce timings of operations. + + Args: + name: the name of the operation being timed + + Example: + The context manager times operations that happen within its context. The + following would time a time.sleep operation:: + + >>> import time + >>> from fv3gfs.util import Timer + >>> timer = Timer() + >>> with timer.clock("sleep"): + ... time.sleep(1) + ... + >>> timer.times + {'sleep': 1.0032463260000029} + """ self.start(name) yield self.stop(name) @property def times(self) -> Mapping[str, float]: + """accumulated timings for each operation name""" if len(self._clock_starts) > 0: warnings.warn( "Retrieved times while clocks are still going, " @@ -42,12 +67,15 @@ def times(self) -> Mapping[str, float]: return self._accumulated_time.copy() def reset(self): + """Remove all accumulated timings.""" self._accumulated_time.clear() def enable(self): + """Enable the Timer.""" self._enabled = True def disable(self): + """Disable the Timer.""" if len(self._clock_starts) > 0: raise RuntimeError( "Cannot disable timer while clocks are still going: " @@ -56,7 +84,8 @@ def disable(self): self._enabled = False @property - def enabled(self): + def enabled(self) -> bool: + """Indicates whether the timer is currently enabled.""" return self._enabled diff --git a/external/fv3gfs-util/fv3gfs/util/communicator.py b/external/fv3gfs-util/fv3gfs/util/communicator.py index 0859b405b..ac2afb023 100644 --- a/external/fv3gfs-util/fv3gfs/util/communicator.py +++ b/external/fv3gfs-util/fv3gfs/util/communicator.py @@ -277,6 +277,9 @@ def scatter_client(): class CubedSphereCommunicator(Communicator): """Performs communications within a cubed sphere""" + timer: Timer + partitioner: CubedSpherePartitioner + def __init__(self, comm, partitioner: CubedSpherePartitioner): """Initialize a CubedSphereCommunicator.