diff options
Diffstat (limited to 'src/corelib/thread/qfuture.qdoc')
| -rw-r--r-- | src/corelib/thread/qfuture.qdoc | 98 |
1 files changed, 82 insertions, 16 deletions
diff --git a/src/corelib/thread/qfuture.qdoc b/src/corelib/thread/qfuture.qdoc index 989ffa36c8..1519f20cf0 100644 --- a/src/corelib/thread/qfuture.qdoc +++ b/src/corelib/thread/qfuture.qdoc @@ -37,14 +37,17 @@ QFuture allows threads to be synchronized against one or more results which will be ready at a later point in time. The result can be of any type - that has a default constructor and a copy constructor. If a result is not - available at the time of calling the result(), resultAt(), or results() - functions, QFuture will wait until the result becomes available. You can - use the isResultReadyAt() function to determine if a result is ready or - not. For QFuture objects that report more than one result, the - resultCount() function returns the number of continuous results. This - means that it is always safe to iterate through the results from 0 to - resultCount(). + that has default, copy and possibly move constructors. If + a result is not available at the time of calling the result(), resultAt(), + results(), takeResult(), or takeResults() functions, QFuture + will wait until the result becomes available. You can use the isResultReadyAt() + function to determine if a result is ready or not. For QFuture objects that + report more than one result, the resultCount() function returns the number + of continuous results. This means that it is always safe to iterate through + the results from 0 to resultCount(). takeResult() and takeResults() + invalidate a future and any subsequent attempt to access result or results + from the future leads to undefined behavior. isValid() tells you if + results can be accessed. QFuture provides a \l{Java-style iterators}{Java-style iterator} (QFutureIterator) and an \l{STL-style iterators}{STL-style iterator} @@ -227,7 +230,7 @@ number of results stored might be different from this value, due to gaps in the result set. It is always safe to iterate through the results from 0 to resultCount(). - \sa result(), resultAt(), results() + \sa result(), resultAt(), results(), takeResult(), takeResults() */ /*! \fn template <typename T> int QFuture<T>::progressValue() const @@ -273,7 +276,10 @@ available, this function will block and wait for the result to become available. This is a convenience method for calling resultAt(0). - \sa resultAt(), results() + \note Calling result() leads to undefined behavior if isValid() + returns \c false for this QFuture. + + \sa resultAt(), results(), takeResult(), takeResults() */ /*! \fn template <typename T> T QFuture<T>::resultAt(int index) const @@ -282,7 +288,10 @@ immediately available, this function will block and wait for the result to become available. - \sa result(), results(), resultCount() + \note Calling resultAt() leads to undefined behavior if isValid() + returns \c false for this QFuture. + + \sa result(), results(), takeResult(), takeResults(), resultCount() */ /*! \fn template <typename T> bool QFuture<T>::isResultReadyAt(int index) const @@ -290,7 +299,10 @@ Returns \c true if the result at \a index is immediately available; otherwise returns \c false. - \sa resultAt(), resultCount() + \note Calling isResultReadyAt() leads to undefined behavior if isValid() + returns \c false for this QFuture. + + \sa resultAt(), resultCount(), takeResult(), takeResults() */ /*! \fn template <typename T> QFuture<T>::operator T() const @@ -300,15 +312,69 @@ available. This is a convenience method for calling result() or resultAt(0). - \sa result(), resultAt(), results() + \note Calling this function leads to undefined behavior if isValid() + returns \c false for this QFuture. + + \sa result(), resultAt(), results(), takeResult(), takeResults(), isValid() */ /*! \fn template <typename T> QList<T> QFuture<T>::results() const - Returns all results from the future. If the results are not immediately - available, this function will block and wait for them to become available. + Returns all results from the future. If the results are not immediately available, + this function will block and wait for them to become available. + + \note Calling results() leads to undefined behavior if isValid() + returns \c false for this QFuture. + + \sa result(), resultAt(), takeResult(), takeResults(), resultCount(), isValid() +*/ + +/*! \fn template <typename T> std::vector<T> QFuture<T>::takeResults() + + If isValid() returns \c false, calling this function leads to undefined behavior. + takeResults() takes all results from the QFuture object and invalidates it + (isValid() will return \c false for this future). If the results are + not immediately available, this function will block and wait for them to + become available. This function tries to use move semantics for the results + if available and falls back to copy construction if the type is not movable. + + \note QFuture in general allows sharing the results between different QFuture + objects (and potentially between different threads). takeResults() was introduced + to make QFuture also work with move-only types (like std::unique_ptr), so it + assumes that only one thread can move the results out of the future, and only + once. + + \sa takeResult(), result(), resultAt(), results(), resultCount(), isValid() +*/ + +/* \fn template <typename T> std::vector<T> QFuture<T>::takeResult() + + Call this function only if isValid() returns \c true, otherwise + the behavior is undefined. This function takes the first result from + the QFuture object, for convenience when only one result is expected. + If there are any other results, they are discarded after taking the + first one (if such behavior is undesired, use takeResults() instead). + If the result is not immediately available, this function will block and + wait for the result to become available. The QFuture will try to use move + semantics if possible, and will fall back to copy construction if the type + is not movable. After the result was taken, isValid() will evaluate + as \c false. + + \note QFuture in general allows sharing the results between different QFuture + objects (and potentially between different threads). takeResult() was introduced + to make QFuture also work with move-only types (like std::unique_ptr), so it + assumes that only one thread can move the results out of the future, and + do it only once. + + \sa takeResults(), result(), results(), resultAt(), isValid() +*/ + +/* \fn template <typename T> std::vector<T> QFuture<T>::isValid() const + + Returns true if a result or results can be accessed or taken from this + QFuture object. Returns false after the result was taken from the future. - \sa result(), resultAt(), resultCount() + \sa takeResults(), takeResult(), result(), results(), resultAt() */ /*! \fn template <typename T> QFuture<T>::const_iterator QFuture<T>::begin() const |