From 045e417eff0a0efabd15d22361af7e6dff5f44f4 Mon Sep 17 00:00:00 2001 From: Marc Mutz Date: Sun, 3 Apr 2016 13:02:47 +0200 Subject: [doc] QElapsedTimer: mention more clearly which functions cause undefined behavior Change-Id: Ic7ab0d81689e2cc78f39f5f32beaea74ca10ce38 Reviewed-by: Giuseppe D'Angelo Reviewed-by: Friedemann Kleint Reviewed-by: Olivier Goffart (Woboq GmbH) Reviewed-by: Thiago Macieira --- src/corelib/tools/qelapsedtimer_generic.cpp | 22 ++++++++++++++-------- 1 file changed, 14 insertions(+), 8 deletions(-) (limited to 'src/corelib/tools') diff --git a/src/corelib/tools/qelapsedtimer_generic.cpp b/src/corelib/tools/qelapsedtimer_generic.cpp index 210d372e15..8679aec810 100644 --- a/src/corelib/tools/qelapsedtimer_generic.cpp +++ b/src/corelib/tools/qelapsedtimer_generic.cpp @@ -79,7 +79,8 @@ void QElapsedTimer::start() Q_DECL_NOTHROW and then starting the timer again with start(), but it does so in one single operation, avoiding the need to obtain the clock value twice. - Restarting the timer makes it valid again. + Calling this function on a QElapsedTimer that is invalid + results in undefined behavior. The following example illustrates how to use this function to calibrate a parameter to a slow operation (for example, an iteration count) so that @@ -87,7 +88,7 @@ void QElapsedTimer::start() Q_DECL_NOTHROW \snippet qelapsedtimer/main.cpp 3 - \sa start(), invalidate(), elapsed() + \sa start(), invalidate(), elapsed(), isValid() */ qint64 QElapsedTimer::restart() Q_DECL_NOTHROW { @@ -100,8 +101,10 @@ qint64 QElapsedTimer::restart() Q_DECL_NOTHROW /*! \since 4.8 Returns the number of nanoseconds since this QElapsedTimer was last - started. Calling this function in a QElapsedTimer that was invalidated - will result in undefined results. + started. + + Calling this function on a QElapsedTimer that is invalid + results in undefined behavior. On platforms that do not provide nanosecond resolution, the value returned will be the best estimate available. @@ -115,10 +118,12 @@ qint64 QElapsedTimer::nsecsElapsed() const Q_DECL_NOTHROW /*! Returns the number of milliseconds since this QElapsedTimer was last - started. Calling this function in a QElapsedTimer that was invalidated - will result in undefined results. + started. - \sa start(), restart(), hasExpired(), invalidate() + Calling this function on a QElapsedTimer that is invalid + results in undefined behavior. + + \sa start(), restart(), hasExpired(), isValid(), invalidate() */ qint64 QElapsedTimer::elapsed() const Q_DECL_NOTHROW { @@ -166,7 +171,8 @@ qint64 QElapsedTimer::msecsTo(const QElapsedTimer &other) const Q_DECL_NOTHROW \a other was started before this object, the returned value will be negative. If it was started later, the returned value will be positive. - The return value is undefined if this object or \a other were invalidated. + Calling this function on or with a QElapsedTimer that is invalid + results in undefined behavior. \sa msecsTo(), elapsed() */ -- cgit v1.2.3