Add section on timer range checking to docs. and add PolledTimer::checkTime() method.

Author: mikee47

Sming/Core/PolledTimer.h

@@ -114,32 +114,50 @@ class Timer : public NanoTime::TimeSource<Clock, unit_, TimeType>
 	 * @param interval Time to expire after last call to start()
 	 */
 	template <uint64_t timeInterval> __forceinline void IRAM_ATTR reset()
+	{
+		auto ticks = checkTime<timeInterval>();
+		resetTicks(ticks);
+	}
+
+	/**
+	 * @brief Check the given time interval is valid and return the corresponding tick count
+	 * @tparam timeInterval
+	 * @retval uint32_t
+	 * @note If time interval is invalid fails compilation
+	 */
+	template <uint64_t timeInterval> constexpr uint32_t checkTime()
 	{
 		auto time = this->template timeConst<timeInterval>();
 		time.check();
 		constexpr auto ticks = time.ticks();
 		static_assert(ticks < maxInterval(), "Polled time interval too long");
-		resetTicks(ticks);
+		return ticks;
 	}
 
 	/**
 	 * @brief Start the timer with a new expiry interval
 	 * @param interval Time to expire after last call to start()
+	 * @retval bool true on success, false on failure
+	 * @see See `resetTicks()`
 	 */
-	__forceinline void IRAM_ATTR reset(const TimeType& timeInterval)
+	__forceinline bool IRAM_ATTR reset(const TimeType& timeInterval)
 	{
-		resetTicks(this->template timeToTicks(timeInterval));
+		return resetTicks(this->template timeToTicks(timeInterval));
 	}
 
 	/**
 	 * @brief Start the timer with a new expiry interval
 	 * @param interval Clock ticks to expire after last call to start()
+	 * @retval bool true on success, false if interval is out of range
+	 * @note If time interval is 0, timer will expire immediately, and if it
+	 * exceeds the maximum interval the timer will never expire.
 	 */
-	__forceinline void IRAM_ATTR resetTicks(const TimeType& interval)
+	__forceinline bool IRAM_ATTR resetTicks(const TimeType& interval)
 	{
 		start();
 		this->interval = interval;
-		neverExpires = (interval >= Clock::maxTicks());
+		neverExpires = (interval > maxInterval());
+		return !neverExpires;
 	}
 
 	/**

docs/source/information/timers.rst

@@ -102,6 +102,50 @@ Here's the output from the :source:`BenchmarkPolledTimer <tests/HostTests/app/te
    Using micros(), managed 145441 iterations, average loop time = 688ns (55 CPU cycles)
    Using PolledTimer, managed 266653 iterations, average loop time = 375ns (30 CPU cycles)
 
+Timer range
+-----------
+
+The maximum interval for a timer varies depending on the clock source and the selected prescaler.
+The count may be further restricted by hardware. For example, Timer1 only provides a 23-bit count
+which means with a /16 prescaler (the default for HardwareTimer) it overflows after only 1.67 seconds.
+
+It's therefore important to check that timers are being used within their valid range. There are generally
+two ways to do this:
+
+Runtime checks
+   This means checking function/method return values and acting accordingly.
+   This often gets omitted because it can lead to cluttered code, which then leads to undiagnosed
+   bugs creeping in which can be very difficult to track down later on.
+
+   With a polled timer, you'd use one of these methods to set the time interval::
+
+      bool reset(const TimeType& timeInterval);
+      bool resetTicks(const TimeType& interval);
+
+   They both return true on success.
+
+Static checks
+   These checks are performed during code compilation, so if a check fails the code won't compile.
+   In regular 'C' code you'd do this using #if statements, but C++ offers a much better way using
+   `static_assert <https://en.cppreference.com/w/cpp/language/static_assert>`__.
+
+   To reset a polled timer and incorporate a static check, use this method::   
+
+      template <uint64_t timeInterval> void reset();
+
+   Note that timeInterval cannot be a variable (even if it's *const*) as the compiler must be
+   able to determine its value. It must therefore be *constexpr compatible*.
+
+You can use static checking to pre-validate the range for a timer before using it::
+
+   timer.checkTime<10>();
+   timer.checkTime<10000>();
+
+This will throw a compile-time error if the timer is not capable of using intervals in the
+range 10 - 10000 microseconds (or whichever time unit you've selected). It doesn't add any
+code to the application. If the code compiles, then you can be confident that the timer
+will function as expected and you don't need to check return values.
+
 Clocks
 ------
 
@@ -111,12 +155,12 @@ also consider the CPU cycle counter to have a selectable prescaler of 1 or 2, de
 whether it's running at 80MHz or 160MHz.
 
 A *Clock* definition is a class template which allows us to query timer properties and perform time
-conversions for a specific timer configuration. These definitions can be found in `Platform/Clocks.h`.
+conversions for a specific timer configuration. These definitions can be found in :source:`Sming/Platform/Clocks.h`.
 
 .. note:: A Clock is a purely virtual construct and does not provide any means to configure the hardware,
    although it does provide the *ticks()* method to obtain the current timer value.
 
-Clocks are made more useful by *TimeSource*, a generic class template defined in *NanoTime.h*.
+Clocks are made more useful by *TimeSource*, a generic class template defined in :source:`Sming/Core/NanoTime.h`.
 This provides methods to convert between time values and tick values for a specific time unit.
 
 Let's say we want a microsecond source using Timer2::
@@ -146,4 +190,4 @@ For debugging purposes you can print a description::
 
    Serial.println(t2source.toString()); // "Timer2Clock/5MHz/32-bit/microseconds"
 
-See *NanoTime.h* for further details.
+See :source:`Sming/Core/NanoTime.h` for further details.