src/main/java/org/apache/commons/lang3/time/StopWatch.java - commons-lang - Git at Google

 /*
  * Licensed to the Apache Software Foundation (ASF) under one or more
  * contributor license agreements.  See the NOTICE file distributed with
  * this work for additional information regarding copyright ownership.
  * The ASF licenses this file to You under the Apache License, Version 2.0
  * (the "License"); you may not use this file except in compliance with
  * the License.  You may obtain a copy of the License at
  *
  *      https://www.apache.org/licenses/LICENSE-2.0
  *
  * Unless required by applicable law or agreed to in writing, software
  * distributed under the License is distributed on an "AS IS" BASIS,
  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */

 package org.apache.commons.lang3.time;

 import java.time.Duration;
 import java.time.Instant;
 import java.util.ArrayList;
 import java.util.Collections;
 import java.util.List;
 import java.util.Objects;
 import java.util.concurrent.TimeUnit;
 import java.util.function.Supplier;

 import org.apache.commons.lang3.StringUtils;
 import org.apache.commons.lang3.function.FailableConsumer;
 import org.apache.commons.lang3.function.FailableRunnable;
 import org.apache.commons.lang3.function.FailableSupplier;
 import org.apache.commons.lang3.tuple.ImmutablePair;

 /**
  * {@link StopWatch} provides a convenient API for timings.
  *
  * <p>
  * To start the watch, call {@link #start()} or {@link StopWatch#createStarted()}. At this point you can:
  * </p>
  * <ul>
  * <li>{@link #split()} the watch to get the time whilst the watch continues in the background. {@link #unsplit()} will remove the effect of the split. At this
  * point, these three options are available again.</li>
  * <li>{@link #suspend()} the watch to pause it. {@link #resume()} allows the watch to continue. Any time between the suspend and resume will not be counted in
  * the total. At this point, these three options are available again.</li>
  * <li>{@link #stop()} the watch to complete the timing session.</li>
  * </ul>
  *
  * <p>
  * It is intended that the output methods {@link #toString()} and {@link #getTime()} should only be called after stop, split or suspend, however a suitable
  * result will be returned at other points.
  * </p>
  *
  * <p>
  * NOTE: As from v2.1, the methods protect against inappropriate calls. Thus you cannot now call stop before start, resume before suspend or unsplit before
  * split.
  * </p>
  *
  * <ol>
  * <li>{@link #split()}, {@link #suspend()}, or {@link #stop()} cannot be invoked twice</li>
  * <li>{@link #unsplit()} may only be called if the watch has been {@link #split()}</li>
  * <li>{@link #resume()} may only be called if the watch has been {@link #suspend()}</li>
  * <li>{@link #start()} cannot be called twice without calling {@link #reset()}</li>
  * </ol>
  *
  * <p>
  * This class is not thread-safe.
  * </p>
  *
  * @see DurationUtils#of(FailableRunnable)
  * @see DurationUtils#of(FailableConsumer)
  * @since 2.0
  */
 public class StopWatch {

     /**
      * Stores a split as a label and duration.
      *
      * @since 3.20.0
      */
     public static final class Split extends ImmutablePair<String, Duration> {

         /**
          * Constructs a Split object with label and duration.
          *
          * @param label Label for this split.
          * @param duration Duration for this split.
          */
         public Split(String label, Duration duration) {
             super(label, duration);
         }

         /**
          * Gets the duration of this split.
          *
          * @return The duration of this split.
          */
         public Duration getDuration() {
             return getRight();
         }

         /**
          * Gets the label of this split.
          *
          * @return The label of this split.
          */
         public String getLabel() {
             return getLeft();
         }

         /**
          * Converts this instance to a string.
          *
          * @return this instance to a string.
          */
         @Override
         public String toString() {
             return String.format("Split [%s, %s])", getLabel(), getDuration());
         }
     }

     /**
      * Enumeration type which indicates the split status of a StopWatch.
      */
     private enum SplitState {
         SPLIT, UNSPLIT
     }

     /**
      * Enumeration type which indicates the status of a StopWatch.
      */
     private enum State {

         RUNNING {
             @Override
             boolean isStarted() {
                 return true;
             }

             @Override
             boolean isStopped() {
                 return false;
             }

             @Override
             boolean isSuspended() {
                 return false;
             }
         },

         STOPPED {
             @Override
             boolean isStarted() {
                 return false;
             }

             @Override
             boolean isStopped() {
                 return true;
             }

             @Override
             boolean isSuspended() {
                 return false;
             }
         },

         SUSPENDED {
             @Override
             boolean isStarted() {
                 return true;
             }

             @Override
             boolean isStopped() {
                 return false;
             }

             @Override
             boolean isSuspended() {
                 return true;
             }
         },

         UNSTARTED {
             @Override
             boolean isStarted() {
                 return false;
             }

             @Override
             boolean isStopped() {
                 return true;
             }

             @Override
             boolean isSuspended() {
                 return false;
             }
         };

         /**
          * Tests whether this StopWatch is started. A suspended StopWatch is also started.
          *
          * @return boolean If this StopWatch is started.
          */
         abstract boolean isStarted();

         /**
          * Tests whether this StopWatch is stopped. A StopWatch which is not yet started and explicitly stopped is considered stopped.
          *
          * @return boolean If this StopWatch is stopped.
          */
         abstract boolean isStopped();

         /**
          * Tests whether this StopWatch is suspended.
          *
          * @return boolean If this StopWatch is suspended.
          */
         abstract boolean isSuspended();
     }

     private static final long NANO_2_MILLIS = 1_000_000L;

     /**
      * Creates a StopWatch.
      *
      * @return StopWatch a StopWatch.
      * @since 3.10
      */
     public static StopWatch create() {
         return new StopWatch();
     }

     /**
      * Creates and starts a StopWatch.
      *
      * @return StopWatch a started StopWatch.
      * @since 3.5
      */
     public static StopWatch createStarted() {
         final StopWatch sw = new StopWatch();
         sw.start();
         return sw;
     }

     /**
      * A message for string presentation.
      *
      * @since 3.10
      */
     private final String message;

     /**
      * The current running state of this StopWatch.
      */
     private State runningState = State.UNSTARTED;

     /**
      * Whether this StopWatch has a split time recorded.
      */
     private SplitState splitState = SplitState.UNSPLIT;

     /**
      * The start time in nanoseconds.
      *
      * This field can be removed once we move off of Java 8.
      */
     private long startTimeNanos;

     /**
      * The start Instant.
      * <p>
      * nanoTime is only for elapsed time so we need to also store the currentTimeMillis to maintain the old getStartTime API.
      * </p>
      * <p>
      * On Java 8, Instant has millisecond precision, later versions use nanoseconds.
      * </p>
      */
     private Instant startInstant;

     /**
      * The end Instant.
      * <p>
      * nanoTime is only for elapsed time so we need to also store the currentTimeMillis to maintain the old getStartTime API.
      * </p>
      * <p>
      * On Java 8, Instant has millisecond precision, later versions use nanoseconds.
      * </p>
      */
     private Instant stopInstant;

     /**
      * The stop time in nanoseconds.
      *
      * This field can be removed once we move off of Java 8.
      */
     private long stopTimeNanos;

     /**
      * The split list.
      */
     private final List<Split> splits = new ArrayList<>();

     /**
      * Constructs a new instance.
      */
     public StopWatch() {
         this(null);
     }

     /**
      * Constructs a new instance.
      *
      * @param message A message for string presentation.
      * @since 3.10
      */
     public StopWatch(final String message) {
         this.message = message;
     }

     /**
      * Formats the split time with {@link DurationFormatUtils#formatDurationHMS}.
      *
      * @return the split time formatted by {@link DurationFormatUtils#formatDurationHMS}.
      * @since 3.10
      */
     public String formatSplitTime() {
         return DurationFormatUtils.formatDurationHMS(getSplitDuration().toMillis());
     }

     /**
      * Formats the time formatted with {@link DurationFormatUtils#formatDurationHMS}.
      *
      * @return the time formatted by {@link DurationFormatUtils#formatDurationHMS}.
      * @since 3.10
      */
     public String formatTime() {
         return DurationFormatUtils.formatDurationHMS(getTime());
     }

     /**
      * Delegates to {@link Supplier#get()} while recording the duration of the call.
      *
      * @param <T>      the type of results supplied by this supplier.
      * @param supplier The supplier to {@link Supplier#get()}.
      * @return a result from the given Supplier.
      * @since 3.18.0
      */
     public <T> T get(final Supplier<T> supplier) {
         startResume();
         try {
             return supplier.get();
         } finally {
             suspend();
         }
     }

     /**
      * Gets the Duration on this StopWatch.
      *
      * <p>
      * This is either the Duration between the start and the moment this method is called, or the Duration between start and stop.
      * </p>
      *
      * @return the Duration.
      * @since 3.16.0
      */
     public Duration getDuration() {
         return Duration.ofNanos(getNanoTime());
     }

     /**
      * Gets the message for string presentation.
      *
      * @return the message for string presentation.
      * @since 3.10
      */
     public String getMessage() {
         return message;
     }

     /**
      * Gets the <em>elapsed</em> time in nanoseconds.
      *
      * <p>
      * This is either the time between the start and the moment this method is called, or the amount of time between start and stop.
      * </p>
      *
      * @return the <em>elapsed</em> time in nanoseconds.
      * @see System#nanoTime()
      * @since 3.0
      */
     public long getNanoTime() {
         switch (runningState) {
         case STOPPED:
         case SUSPENDED:
             return stopTimeNanos - startTimeNanos;
         case UNSTARTED:
             return 0;
         case RUNNING:
             return System.nanoTime() - startTimeNanos;
         default:
             break;
         }
         throw new IllegalStateException("Illegal running state has occurred.");
     }

     /**
      * Gets the split Duration on this StopWatch.
      *
      * <p>
      * This is the Duration between start and latest split.
      * </p>
      *
      * @return the split Duration.
      * @throws IllegalStateException if this StopWatch has not yet been split.
      * @since 3.16.0
      */
     public Duration getSplitDuration() {
         return Duration.ofNanos(getSplitNanoTime());
     }

     /**
      * Gets the split time in nanoseconds.
      *
      * <p>
      * This is the time between start and latest split.
      * </p>
      *
      * @return the split time in nanoseconds.
      * @throws IllegalStateException if this StopWatch has not yet been split.
      * @since 3.0
      */
     public long getSplitNanoTime() {
         if (splitState != SplitState.SPLIT) {
             throw new IllegalStateException("Stopwatch must be split to get the split time.");
         }
         return splits.get(splits.size() - 1).getRight().toNanos();
     }

     /**
      * Gets the split list.
      *
      * @return the list of splits.
      * @since 3.20.0
      */
     public List<Split> getSplits() {
         return Collections.unmodifiableList(splits);
     }

     /**
      * Gets the split time on this StopWatch.
      *
      * <p>
      * This is the time between start and latest split.
      * </p>
      *
      * @return the split time in milliseconds.
      * @throws IllegalStateException if this StopWatch has not yet been split.
      * @since 2.1
      * @deprecated Use {@link #getSplitDuration()}.
      */
     @Deprecated
     public long getSplitTime() {
         return nanosToMillis(getSplitNanoTime());
     }

     /**
      * Gets the Instant this StopWatch was started, between the current time and midnight, January 1, 1970 UTC.
      *
      * @return the Instant this StopWatch was started, between the current time and midnight, January 1, 1970 UTC.
      * @throws IllegalStateException if this StopWatch has not been started.
      * @since 3.16.0
      */
     public Instant getStartInstant() {
         if (runningState == State.UNSTARTED) {
             throw new IllegalStateException("Stopwatch has not been started");
         }
         return startInstant;
     }

     /**
      * Gets the time this StopWatch was started in milliseconds, between the current time and midnight, January 1, 1970 UTC.
      *
      * @return the time this StopWatch was started in milliseconds, between the current time and midnight, January 1, 1970 UTC.
      * @throws IllegalStateException if this StopWatch has not been started.
      * @since 2.4
      * @deprecated Use {@link #getStartInstant()}.
      */
     @Deprecated
     public long getStartTime() {
         return getStartInstant().toEpochMilli();
     }

     /**
      * Gets the Instant this StopWatch was stopped, between the current time and midnight, January 1, 1970 UTC.
      *
      * @return the Instant this StopWatch was stopped in milliseconds, between the current time and midnight, January 1, 1970 UTC.
      * @throws IllegalStateException if this StopWatch has not been started.
      * @since 3.16.0
      */
     public Instant getStopInstant() {
         if (runningState == State.UNSTARTED) {
             throw new IllegalStateException("Stopwatch has not been started");
         }
         return stopInstant;
     }

     /**
      * Gets the time this StopWatch was stopped in milliseconds, between the current time and midnight, January 1, 1970 UTC.
      *
      * @return the time this StopWatch was stopped in milliseconds, between the current time and midnight, January 1, 1970 UTC.
      * @throws IllegalStateException if this StopWatch has not been started.
      * @since 3.12.0
      * @deprecated Use {@link #getStopInstant()}.
      */
     @Deprecated
     public long getStopTime() {
         // stopTimeNanos stores System.nanoTime() for elapsed time
         final Instant stop = getStopInstant();
         return stop != null ? stop.toEpochMilli() : 0;
     }

     /**
      * Delegates to {@link FailableSupplier#get()} while recording the duration of the call.
      *
      * @param <T>      the type of results supplied by this supplier.
      * @param <E>      The kind of thrown exception or error.
      * @param supplier The supplier to {@link Supplier#get()}.
      * @return a result from the given Supplier.
      * @throws Throwable if the supplier fails.
      * @since 3.18.0
      */
     public <T, E extends Throwable> T getT(final FailableSupplier<T, E> supplier) throws Throwable {
         startResume();
         try {
             return supplier.get();
         } finally {
             suspend();
         }
     }

     /**
      * Gets the time on this StopWatch.
      *
      * <p>
      * This is either the time between the start and the moment this method is called, or the amount of time between start and stop.
      * </p>
      *
      * @return the time in milliseconds.
      * @see #getDuration()
      */
     public long getTime() {
         return nanosToMillis(getNanoTime());
     }

     /**
      * Gets the time in the specified TimeUnit.
      *
      * <p>
      * This is either the time between the start and the moment this method is called, or the amount of time between start and stop. The resulting time will be
      * expressed in the desired TimeUnit with any remainder rounded down. For example, if the specified unit is {@code TimeUnit.HOURS} and this StopWatch time
      * is 59 minutes, then the result returned will be {@code 0}.
      * </p>
      *
      * @param timeUnit the unit of time, not null.
      * @return the time in the specified TimeUnit, rounded down.
      * @since 3.5
      */
     public long getTime(final TimeUnit timeUnit) {
         return timeUnit.convert(getNanoTime(), TimeUnit.NANOSECONDS);
     }

     /**
      * Tests whether this StopWatch is started. A suspended StopWatch is also started watch.
      *
      * @return boolean If this StopWatch is started.
      * @since 3.2
      */
     public boolean isStarted() {
         return runningState.isStarted();
     }

     /**
      * Tests whether StopWatch is stopped. this StopWatch which's not yet started and explicitly stopped StopWatch is considered as stopped.
      *
      * @return boolean If this StopWatch is stopped.
      * @since 3.2
      */
     public boolean isStopped() {
         return runningState.isStopped();
     }

     /**
      * Tests whether this StopWatch is suspended.
      *
      * @return boolean If this StopWatch is suspended.
      * @since 3.2
      */
     public boolean isSuspended() {
         return runningState.isSuspended();
     }

     /**
      * Converts nanoseconds to milliseconds.
      *
      * @param nanos nanoseconds to convert.
      * @return milliseconds conversion result.
      */
     private long nanosToMillis(final long nanos) {
         return nanos / NANO_2_MILLIS;
     }

     /**
      * Resets this StopWatch. Stops it if need be.
      *
      * <p>
      * This method clears the internal values to allow the object to be reused.
      * </p>
      */
     public void reset() {
         runningState = State.UNSTARTED;
         splitState = SplitState.UNSPLIT;
         splits.clear();
     }

     /**
      * Resumes this StopWatch after a suspend.
      *
      * <p>
      * This method resumes the watch after it was suspended. The watch will not include time between the suspend and resume calls in the total time.
      * </p>
      *
      * @throws IllegalStateException if this StopWatch has not been suspended.
      */
     public void resume() {
         if (runningState != State.SUSPENDED) {
             throw new IllegalStateException("Stopwatch must be suspended to resume.");
         }
         startTimeNanos += System.nanoTime() - stopTimeNanos;
         runningState = State.RUNNING;
     }

     /**
      * Delegates to {@link Runnable#run()} while recording the duration of the call.
      *
      * @param runnable The runnable to {@link Runnable#run()}.
      * @since 3.18.0
      */
     public void run(final Runnable runnable) {
         startResume();
         try {
             runnable.run();
         } finally {
             suspend();
         }
     }

     /**
      * Delegates to {@link FailableRunnable#run()} while recording the duration of the call.
      *
      * @param <E>      The kind of {@link Throwable}.
      * @param runnable The runnable to {@link FailableRunnable#run()}.
      * @throws Throwable Thrown by {@link FailableRunnable#run()}.
      * @since 3.18.0
      */
     public <E extends Throwable> void runT(final FailableRunnable<E> runnable) throws Throwable {
         startResume();
         try {
             runnable.run();
         } finally {
             suspend();
         }
     }

     /**
      * Splits the time.
      *
      * <p>
      * This method sets the stop time of the watch to allow a time to be extracted. The start time is unaffected, enabling {@link #unsplit()} to continue the
      * timing from the original start point.
      * </p>
      *
      * @throws IllegalStateException if this StopWatch is not running.
      */
     public void split() {
         if (runningState != State.RUNNING) {
             throw new IllegalStateException("Stopwatch is not running.");
         }
         stopSet();
         splitState = SplitState.SPLIT;
         splits.add(new Split(String.valueOf(splits.size()), Duration.ofNanos(stopTimeNanos - startTimeNanos)));
     }

     /**
      * Splits the time with a label.
      *
      * <p>
      * This method sets the stop time of the watch to allow a time to be extracted. The start time is unaffected, enabling {@link #unsplit()} to continue the
      * timing from the original start point.
      * </p>
      *
      * @param label A message for string presentation.
      * @throws IllegalStateException if the StopWatch is not running.
      * @since 3.20.0
      */
     public void split(final String label) {
         if (runningState != State.RUNNING) {
             throw new IllegalStateException("Stopwatch is not running.");
         }
         stopSet();
         splitState = SplitState.SPLIT;
         splits.add(new Split(label, Duration.ofNanos(stopTimeNanos - startTimeNanos)));
     }

     /**
      * Starts this StopWatch.
      *
      * <p>
      * This method starts a new timing session, clearing any previous values.
      * </p>
      *
      * @throws IllegalStateException if this StopWatch is already running.
      */
     public void start() {
         if (runningState == State.STOPPED) {
             throw new IllegalStateException("Stopwatch must be reset before being restarted.");
         }
         if (runningState != State.UNSTARTED) {
             throw new IllegalStateException("Stopwatch already started.");
         }
         startTimeNanos = System.nanoTime();
         startInstant = Instant.now();
         runningState = State.RUNNING;
         splits.clear();
     }

     /**
      * Starts or resumes this StopWatch.
      */
     private void startResume() {
         if (isStopped()) {
             start();
         } else if (isSuspended()) {
             resume();
         }
     }

     /**
      * Stops this StopWatch.
      *
      * <p>
      * This method ends a new timing session, allowing the time to be retrieved.
      * </p>
      *
      * @throws IllegalStateException if this StopWatch is not running.
      */
     public void stop() {
         if (runningState != State.RUNNING && runningState != State.SUSPENDED) {
             throw new IllegalStateException("Stopwatch is not running.");
         }
         if (runningState == State.RUNNING) {
             stopSet();
         }
         runningState = State.STOPPED;
     }

     private void stopSet() {
         stopTimeNanos = System.nanoTime();
         stopInstant = Instant.now();
     }

     /**
      * Suspends this StopWatch for later resumption.
      *
      * <p>
      * This method suspends the watch until it is resumed. The watch will not include time between the suspend and resume calls in the total time.
      * </p>
      *
      * @throws IllegalStateException if this StopWatch is not currently running.
      */
     public void suspend() {
         if (runningState != State.RUNNING) {
             throw new IllegalStateException("Stopwatch must be running to suspend.");
         }
         stopSet();
         runningState = State.SUSPENDED;
     }

     /**
      * Gets a summary of the last split time that this StopWatch recorded as a string.
      *
      * <p>
      * The format used is ISO 8601-like, [<em>message</em> ]<em>hours</em>:<em>minutes</em>:<em>seconds</em>.<em>milliseconds</em>.
      * </p>
      *
      * @return the split time as a String.
      * @since 2.1
      * @since 3.10 Returns the prefix {@code "message "} if the message is set.
      */
     public String toSplitString() {
         final String msgStr = Objects.toString(message, StringUtils.EMPTY);
         final String formattedTime = formatSplitTime();
         return msgStr.isEmpty() ? formattedTime : msgStr + StringUtils.SPACE + formattedTime;
     }

     /**
      * Gets a summary of the time that this StopWatch recorded as a string.
      *
      * <p>
      * The format used is ISO 8601-like, [<em>message</em> ]<em>hours</em>:<em>minutes</em>:<em>seconds</em>.<em>milliseconds</em>.
      * </p>
      *
      * @return the time as a String.
      * @since 3.10 Returns the prefix {@code "message "} if the message is set.
      */
     @Override
     public String toString() {
         final String msgStr = Objects.toString(message, StringUtils.EMPTY);
         final String formattedTime = formatTime();
         return msgStr.isEmpty() ? formattedTime : msgStr + StringUtils.SPACE + formattedTime;
     }

     /**
      * Removes the split.
      *
      * <p>
      * This method clears the stop time. The start time is unaffected, enabling timing from the original start point to continue.
      * </p>
      *
      * @throws IllegalStateException if this StopWatch has not been split.
      */
     public void unsplit() {
         if (splitState != SplitState.SPLIT) {
             throw new IllegalStateException("Stopwatch has not been split.");
         }
         splitState = SplitState.UNSPLIT;
         splits.remove(splits.size() - 1);
     }
 }
	/*
	* Licensed to the Apache Software Foundation (ASF) under one or more
	* contributor license agreements. See the NOTICE file distributed with
	* this work for additional information regarding copyright ownership.
	* The ASF licenses this file to You under the Apache License, Version 2.0
	* (the "License"); you may not use this file except in compliance with
	* the License. You may obtain a copy of the License at
	*
	* https://www.apache.org/licenses/LICENSE-2.0
	*
	* Unless required by applicable law or agreed to in writing, software
	* distributed under the License is distributed on an "AS IS" BASIS,
	* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
	* See the License for the specific language governing permissions and
	* limitations under the License.
	*/

	package org.apache.commons.lang3.time;

	import java.time.Duration;
	import java.time.Instant;
	import java.util.ArrayList;
	import java.util.Collections;
	import java.util.List;
	import java.util.Objects;
	import java.util.concurrent.TimeUnit;
	import java.util.function.Supplier;

	import org.apache.commons.lang3.StringUtils;
	import org.apache.commons.lang3.function.FailableConsumer;
	import org.apache.commons.lang3.function.FailableRunnable;
	import org.apache.commons.lang3.function.FailableSupplier;
	import org.apache.commons.lang3.tuple.ImmutablePair;

	/**
	* {@link StopWatch} provides a convenient API for timings.
	*
	* <p>
	* To start the watch, call {@link #start()} or {@link StopWatch#createStarted()}. At this point you can:
	* </p>
	* <ul>
	* <li>{@link #split()} the watch to get the time whilst the watch continues in the background. {@link #unsplit()} will remove the effect of the split. At this
	* point, these three options are available again.</li>
	* <li>{@link #suspend()} the watch to pause it. {@link #resume()} allows the watch to continue. Any time between the suspend and resume will not be counted in
	* the total. At this point, these three options are available again.</li>
	* <li>{@link #stop()} the watch to complete the timing session.</li>
	* </ul>
	*
	* <p>
	* It is intended that the output methods {@link #toString()} and {@link #getTime()} should only be called after stop, split or suspend, however a suitable
	* result will be returned at other points.
	* </p>
	*
	* <p>
	* NOTE: As from v2.1, the methods protect against inappropriate calls. Thus you cannot now call stop before start, resume before suspend or unsplit before
	* split.
	* </p>
	*
	* <ol>
	* <li>{@link #split()}, {@link #suspend()}, or {@link #stop()} cannot be invoked twice</li>
	* <li>{@link #unsplit()} may only be called if the watch has been {@link #split()}</li>
	* <li>{@link #resume()} may only be called if the watch has been {@link #suspend()}</li>
	* <li>{@link #start()} cannot be called twice without calling {@link #reset()}</li>
	* </ol>
	*
	* <p>
	* This class is not thread-safe.
	* </p>
	*
	* @see DurationUtils#of(FailableRunnable)
	* @see DurationUtils#of(FailableConsumer)
	* @since 2.0
	*/
	public class StopWatch {

	/**
	* Stores a split as a label and duration.
	*
	* @since 3.20.0
	*/
	public static final class Split extends ImmutablePair<String, Duration> {

	/**
	* Constructs a Split object with label and duration.
	*
	* @param label Label for this split.
	* @param duration Duration for this split.
	*/
	public Split(String label, Duration duration) {
	super(label, duration);
	}

	/**
	* Gets the duration of this split.
	*
	* @return The duration of this split.
	*/
	public Duration getDuration() {
	return getRight();
	}

	/**
	* Gets the label of this split.
	*
	* @return The label of this split.
	*/
	public String getLabel() {
	return getLeft();
	}

	/**
	* Converts this instance to a string.
	*
	* @return this instance to a string.
	*/
	@Override
	public String toString() {
	return String.format("Split [%s, %s])", getLabel(), getDuration());
	}
	}

	/**
	* Enumeration type which indicates the split status of a StopWatch.
	*/
	private enum SplitState {
	SPLIT, UNSPLIT
	}

	/**
	* Enumeration type which indicates the status of a StopWatch.
	*/
	private enum State {

	RUNNING {
	@Override
	boolean isStarted() {
	return true;
	}

	@Override
	boolean isStopped() {
	return false;
	}

	@Override
	boolean isSuspended() {
	return false;
	}
	},

	STOPPED {
	@Override
	boolean isStarted() {
	return false;
	}

	@Override
	boolean isStopped() {
	return true;
	}

	@Override
	boolean isSuspended() {
	return false;
	}
	},

	SUSPENDED {
	@Override
	boolean isStarted() {
	return true;
	}

	@Override
	boolean isStopped() {
	return false;
	}

	@Override
	boolean isSuspended() {
	return true;
	}
	},

	UNSTARTED {
	@Override
	boolean isStarted() {
	return false;
	}

	@Override
	boolean isStopped() {
	return true;
	}

	@Override
	boolean isSuspended() {
	return false;
	}
	};

	/**
	* Tests whether this StopWatch is started. A suspended StopWatch is also started.
	*
	* @return boolean If this StopWatch is started.
	*/
	abstract boolean isStarted();

	/**
	* Tests whether this StopWatch is stopped. A StopWatch which is not yet started and explicitly stopped is considered stopped.
	*
	* @return boolean If this StopWatch is stopped.
	*/
	abstract boolean isStopped();

	/**
	* Tests whether this StopWatch is suspended.
	*
	* @return boolean If this StopWatch is suspended.
	*/
	abstract boolean isSuspended();
	}

	private static final long NANO_2_MILLIS = 1_000_000L;

	/**
	* Creates a StopWatch.
	*
	* @return StopWatch a StopWatch.
	* @since 3.10
	*/
	public static StopWatch create() {
	return new StopWatch();
	}

	/**
	* Creates and starts a StopWatch.
	*
	* @return StopWatch a started StopWatch.
	* @since 3.5
	*/
	public static StopWatch createStarted() {
	final StopWatch sw = new StopWatch();
	sw.start();
	return sw;
	}

	/**
	* A message for string presentation.
	*
	* @since 3.10
	*/
	private final String message;

	/**
	* The current running state of this StopWatch.
	*/
	private State runningState = State.UNSTARTED;

	/**
	* Whether this StopWatch has a split time recorded.
	*/
	private SplitState splitState = SplitState.UNSPLIT;

	/**
	* The start time in nanoseconds.
	*
	* This field can be removed once we move off of Java 8.
	*/
	private long startTimeNanos;

	/**
	* The start Instant.
	* <p>
	* nanoTime is only for elapsed time so we need to also store the currentTimeMillis to maintain the old getStartTime API.
	* </p>
	* <p>
	* On Java 8, Instant has millisecond precision, later versions use nanoseconds.
	* </p>
	*/
	private Instant startInstant;

	/**
	* The end Instant.
	* <p>
	* nanoTime is only for elapsed time so we need to also store the currentTimeMillis to maintain the old getStartTime API.
	* </p>
	* <p>
	* On Java 8, Instant has millisecond precision, later versions use nanoseconds.
	* </p>
	*/
	private Instant stopInstant;

	/**
	* The stop time in nanoseconds.
	*
	* This field can be removed once we move off of Java 8.
	*/
	private long stopTimeNanos;

	/**
	* The split list.
	*/
	private final List<Split> splits = new ArrayList<>();

	/**
	* Constructs a new instance.
	*/
	public StopWatch() {
	this(null);
	}

	/**
	* Constructs a new instance.
	*
	* @param message A message for string presentation.
	* @since 3.10
	*/
	public StopWatch(final String message) {
	this.message = message;
	}

	/**
	* Formats the split time with {@link DurationFormatUtils#formatDurationHMS}.
	*
	* @return the split time formatted by {@link DurationFormatUtils#formatDurationHMS}.
	* @since 3.10
	*/
	public String formatSplitTime() {
	return DurationFormatUtils.formatDurationHMS(getSplitDuration().toMillis());
	}

	/**
	* Formats the time formatted with {@link DurationFormatUtils#formatDurationHMS}.
	*
	* @return the time formatted by {@link DurationFormatUtils#formatDurationHMS}.
	* @since 3.10
	*/
	public String formatTime() {
	return DurationFormatUtils.formatDurationHMS(getTime());
	}

	/**
	* Delegates to {@link Supplier#get()} while recording the duration of the call.
	*
	* @param <T> the type of results supplied by this supplier.
	* @param supplier The supplier to {@link Supplier#get()}.
	* @return a result from the given Supplier.
	* @since 3.18.0
	*/
	public <T> T get(final Supplier<T> supplier) {
	startResume();
	try {
	return supplier.get();
	} finally {
	suspend();
	}
	}

	/**
	* Gets the Duration on this StopWatch.
	*
	* <p>
	* This is either the Duration between the start and the moment this method is called, or the Duration between start and stop.
	* </p>
	*
	* @return the Duration.
	* @since 3.16.0
	*/
	public Duration getDuration() {
	return Duration.ofNanos(getNanoTime());
	}

	/**
	* Gets the message for string presentation.
	*
	* @return the message for string presentation.
	* @since 3.10
	*/
	public String getMessage() {
	return message;
	}

	/**
	* Gets the <em>elapsed</em> time in nanoseconds.
	*
	* <p>
	* This is either the time between the start and the moment this method is called, or the amount of time between start and stop.
	* </p>
	*
	* @return the <em>elapsed</em> time in nanoseconds.
	* @see System#nanoTime()
	* @since 3.0
	*/
	public long getNanoTime() {
	switch (runningState) {
	case STOPPED:
	case SUSPENDED:
	return stopTimeNanos - startTimeNanos;
	case UNSTARTED:
	return 0;
	case RUNNING:
	return System.nanoTime() - startTimeNanos;
	default:
	break;
	}
	throw new IllegalStateException("Illegal running state has occurred.");
	}

	/**
	* Gets the split Duration on this StopWatch.
	*
	* <p>
	* This is the Duration between start and latest split.
	* </p>
	*
	* @return the split Duration.
	* @throws IllegalStateException if this StopWatch has not yet been split.
	* @since 3.16.0
	*/
	public Duration getSplitDuration() {
	return Duration.ofNanos(getSplitNanoTime());
	}

	/**
	* Gets the split time in nanoseconds.
	*
	* <p>
	* This is the time between start and latest split.
	* </p>
	*
	* @return the split time in nanoseconds.
	* @throws IllegalStateException if this StopWatch has not yet been split.
	* @since 3.0
	*/
	public long getSplitNanoTime() {
	if (splitState != SplitState.SPLIT) {
	throw new IllegalStateException("Stopwatch must be split to get the split time.");
	}
	return splits.get(splits.size() - 1).getRight().toNanos();
	}

	/**
	* Gets the split list.
	*
	* @return the list of splits.
	* @since 3.20.0
	*/
	public List<Split> getSplits() {
	return Collections.unmodifiableList(splits);
	}

	/**
	* Gets the split time on this StopWatch.
	*
	* <p>
	* This is the time between start and latest split.
	* </p>
	*
	* @return the split time in milliseconds.
	* @throws IllegalStateException if this StopWatch has not yet been split.
	* @since 2.1
	* @deprecated Use {@link #getSplitDuration()}.
	*/
	@Deprecated
	public long getSplitTime() {
	return nanosToMillis(getSplitNanoTime());
	}

	/**
	* Gets the Instant this StopWatch was started, between the current time and midnight, January 1, 1970 UTC.
	*
	* @return the Instant this StopWatch was started, between the current time and midnight, January 1, 1970 UTC.
	* @throws IllegalStateException if this StopWatch has not been started.
	* @since 3.16.0
	*/
	public Instant getStartInstant() {
	if (runningState == State.UNSTARTED) {
	throw new IllegalStateException("Stopwatch has not been started");
	}
	return startInstant;
	}

	/**
	* Gets the time this StopWatch was started in milliseconds, between the current time and midnight, January 1, 1970 UTC.
	*
	* @return the time this StopWatch was started in milliseconds, between the current time and midnight, January 1, 1970 UTC.
	* @throws IllegalStateException if this StopWatch has not been started.
	* @since 2.4
	* @deprecated Use {@link #getStartInstant()}.
	*/
	@Deprecated
	public long getStartTime() {
	return getStartInstant().toEpochMilli();
	}

	/**
	* Gets the Instant this StopWatch was stopped, between the current time and midnight, January 1, 1970 UTC.
	*
	* @return the Instant this StopWatch was stopped in milliseconds, between the current time and midnight, January 1, 1970 UTC.
	* @throws IllegalStateException if this StopWatch has not been started.
	* @since 3.16.0
	*/
	public Instant getStopInstant() {
	if (runningState == State.UNSTARTED) {
	throw new IllegalStateException("Stopwatch has not been started");
	}
	return stopInstant;
	}

	/**
	* Gets the time this StopWatch was stopped in milliseconds, between the current time and midnight, January 1, 1970 UTC.
	*
	* @return the time this StopWatch was stopped in milliseconds, between the current time and midnight, January 1, 1970 UTC.
	* @throws IllegalStateException if this StopWatch has not been started.
	* @since 3.12.0
	* @deprecated Use {@link #getStopInstant()}.
	*/
	@Deprecated
	public long getStopTime() {
	// stopTimeNanos stores System.nanoTime() for elapsed time
	final Instant stop = getStopInstant();
	return stop != null ? stop.toEpochMilli() : 0;
	}

	/**
	* Delegates to {@link FailableSupplier#get()} while recording the duration of the call.
	*
	* @param <T> the type of results supplied by this supplier.
	* @param <E> The kind of thrown exception or error.
	* @param supplier The supplier to {@link Supplier#get()}.
	* @return a result from the given Supplier.
	* @throws Throwable if the supplier fails.
	* @since 3.18.0
	*/
	public <T, E extends Throwable> T getT(final FailableSupplier<T, E> supplier) throws Throwable {
	startResume();
	try {
	return supplier.get();
	} finally {
	suspend();
	}
	}

	/**
	* Gets the time on this StopWatch.
	*
	* <p>
	* This is either the time between the start and the moment this method is called, or the amount of time between start and stop.
	* </p>
	*
	* @return the time in milliseconds.
	* @see #getDuration()
	*/
	public long getTime() {
	return nanosToMillis(getNanoTime());
	}

	/**
	* Gets the time in the specified TimeUnit.
	*
	* <p>
	* This is either the time between the start and the moment this method is called, or the amount of time between start and stop. The resulting time will be
	* expressed in the desired TimeUnit with any remainder rounded down. For example, if the specified unit is {@code TimeUnit.HOURS} and this StopWatch time
	* is 59 minutes, then the result returned will be {@code 0}.
	* </p>
	*
	* @param timeUnit the unit of time, not null.
	* @return the time in the specified TimeUnit, rounded down.
	* @since 3.5
	*/
	public long getTime(final TimeUnit timeUnit) {
	return timeUnit.convert(getNanoTime(), TimeUnit.NANOSECONDS);
	}

	/**
	* Tests whether this StopWatch is started. A suspended StopWatch is also started watch.
	*
	* @return boolean If this StopWatch is started.
	* @since 3.2
	*/
	public boolean isStarted() {
	return runningState.isStarted();
	}

	/**
	* Tests whether StopWatch is stopped. this StopWatch which's not yet started and explicitly stopped StopWatch is considered as stopped.
	*
	* @return boolean If this StopWatch is stopped.
	* @since 3.2
	*/
	public boolean isStopped() {
	return runningState.isStopped();
	}

	/**
	* Tests whether this StopWatch is suspended.
	*
	* @return boolean If this StopWatch is suspended.
	* @since 3.2
	*/
	public boolean isSuspended() {
	return runningState.isSuspended();
	}

	/**
	* Converts nanoseconds to milliseconds.
	*
	* @param nanos nanoseconds to convert.
	* @return milliseconds conversion result.
	*/
	private long nanosToMillis(final long nanos) {
	return nanos / NANO_2_MILLIS;
	}

	/**
	* Resets this StopWatch. Stops it if need be.
	*
	* <p>
	* This method clears the internal values to allow the object to be reused.
	* </p>
	*/
	public void reset() {
	runningState = State.UNSTARTED;
	splitState = SplitState.UNSPLIT;
	splits.clear();
	}

	/**
	* Resumes this StopWatch after a suspend.
	*
	* <p>
	* This method resumes the watch after it was suspended. The watch will not include time between the suspend and resume calls in the total time.
	* </p>
	*
	* @throws IllegalStateException if this StopWatch has not been suspended.
	*/
	public void resume() {
	if (runningState != State.SUSPENDED) {
	throw new IllegalStateException("Stopwatch must be suspended to resume.");
	}
	startTimeNanos += System.nanoTime() - stopTimeNanos;
	runningState = State.RUNNING;
	}

	/**
	* Delegates to {@link Runnable#run()} while recording the duration of the call.
	*
	* @param runnable The runnable to {@link Runnable#run()}.
	* @since 3.18.0
	*/
	public void run(final Runnable runnable) {
	startResume();
	try {
	runnable.run();
	} finally {
	suspend();
	}
	}

	/**
	* Delegates to {@link FailableRunnable#run()} while recording the duration of the call.
	*
	* @param <E> The kind of {@link Throwable}.
	* @param runnable The runnable to {@link FailableRunnable#run()}.
	* @throws Throwable Thrown by {@link FailableRunnable#run()}.
	* @since 3.18.0
	*/
	public <E extends Throwable> void runT(final FailableRunnable<E> runnable) throws Throwable {
	startResume();
	try {
	runnable.run();
	} finally {
	suspend();
	}
	}

	/**
	* Splits the time.
	*
	* <p>
	* This method sets the stop time of the watch to allow a time to be extracted. The start time is unaffected, enabling {@link #unsplit()} to continue the
	* timing from the original start point.
	* </p>
	*
	* @throws IllegalStateException if this StopWatch is not running.
	*/
	public void split() {
	if (runningState != State.RUNNING) {
	throw new IllegalStateException("Stopwatch is not running.");
	}
	stopSet();
	splitState = SplitState.SPLIT;
	splits.add(new Split(String.valueOf(splits.size()), Duration.ofNanos(stopTimeNanos - startTimeNanos)));
	}

	/**
	* Splits the time with a label.
	*
	* <p>
	* This method sets the stop time of the watch to allow a time to be extracted. The start time is unaffected, enabling {@link #unsplit()} to continue the
	* timing from the original start point.
	* </p>
	*
	* @param label A message for string presentation.
	* @throws IllegalStateException if the StopWatch is not running.
	* @since 3.20.0
	*/
	public void split(final String label) {
	if (runningState != State.RUNNING) {
	throw new IllegalStateException("Stopwatch is not running.");
	}
	stopSet();
	splitState = SplitState.SPLIT;
	splits.add(new Split(label, Duration.ofNanos(stopTimeNanos - startTimeNanos)));
	}

	/**
	* Starts this StopWatch.
	*
	* <p>
	* This method starts a new timing session, clearing any previous values.
	* </p>
	*
	* @throws IllegalStateException if this StopWatch is already running.
	*/
	public void start() {
	if (runningState == State.STOPPED) {
	throw new IllegalStateException("Stopwatch must be reset before being restarted.");
	}
	if (runningState != State.UNSTARTED) {
	throw new IllegalStateException("Stopwatch already started.");
	}
	startTimeNanos = System.nanoTime();
	startInstant = Instant.now();
	runningState = State.RUNNING;
	splits.clear();
	}

	/**
	* Starts or resumes this StopWatch.
	*/
	private void startResume() {
	if (isStopped()) {
	start();
	} else if (isSuspended()) {
	resume();
	}
	}

	/**
	* Stops this StopWatch.
	*
	* <p>
	* This method ends a new timing session, allowing the time to be retrieved.
	* </p>
	*
	* @throws IllegalStateException if this StopWatch is not running.
	*/
	public void stop() {
	if (runningState != State.RUNNING && runningState != State.SUSPENDED) {
	throw new IllegalStateException("Stopwatch is not running.");
	}
	if (runningState == State.RUNNING) {
	stopSet();
	}
	runningState = State.STOPPED;
	}

	private void stopSet() {
	stopTimeNanos = System.nanoTime();
	stopInstant = Instant.now();
	}

	/**
	* Suspends this StopWatch for later resumption.
	*
	* <p>
	* This method suspends the watch until it is resumed. The watch will not include time between the suspend and resume calls in the total time.
	* </p>
	*
	* @throws IllegalStateException if this StopWatch is not currently running.
	*/
	public void suspend() {
	if (runningState != State.RUNNING) {
	throw new IllegalStateException("Stopwatch must be running to suspend.");
	}
	stopSet();
	runningState = State.SUSPENDED;
	}

	/**
	* Gets a summary of the last split time that this StopWatch recorded as a string.
	*
	* <p>
	* The format used is ISO 8601-like, [<em>message</em> ]<em>hours</em>:<em>minutes</em>:<em>seconds</em>.<em>milliseconds</em>.
	* </p>
	*
	* @return the split time as a String.
	* @since 2.1
	* @since 3.10 Returns the prefix {@code "message "} if the message is set.
	*/
	public String toSplitString() {
	final String msgStr = Objects.toString(message, StringUtils.EMPTY);
	final String formattedTime = formatSplitTime();
	return msgStr.isEmpty() ? formattedTime : msgStr + StringUtils.SPACE + formattedTime;
	}

	/**
	* Gets a summary of the time that this StopWatch recorded as a string.
	*
	* <p>
	* The format used is ISO 8601-like, [<em>message</em> ]<em>hours</em>:<em>minutes</em>:<em>seconds</em>.<em>milliseconds</em>.
	* </p>
	*
	* @return the time as a String.
	* @since 3.10 Returns the prefix {@code "message "} if the message is set.
	*/
	@Override
	public String toString() {
	final String msgStr = Objects.toString(message, StringUtils.EMPTY);
	final String formattedTime = formatTime();
	return msgStr.isEmpty() ? formattedTime : msgStr + StringUtils.SPACE + formattedTime;
	}

	/**
	* Removes the split.
	*
	* <p>
	* This method clears the stop time. The start time is unaffected, enabling timing from the original start point to continue.
	* </p>
	*
	* @throws IllegalStateException if this StopWatch has not been split.
	*/
	public void unsplit() {
	if (splitState != SplitState.SPLIT) {
	throw new IllegalStateException("Stopwatch has not been split.");
	}
	splitState = SplitState.UNSPLIT;
	splits.remove(splits.size() - 1);
	}
	}