task_result.h

Go to the documentation of this file.

// -----------------------------------------------------------------------------
//
// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception OR LGPL-2.1-or-later
// Copyright (C) 2023 - 2024 by the deal.II authors
//
// This file is part of the deal.II library.
//
// Detailed license information governing the source code and contributions
// can be found in LICENSE.md and CONTRIBUTING.md at the top level directory.
//
// -----------------------------------------------------------------------------
 
#ifndef dealii_task_result_h
#define dealii_task_result_h
 
 
#include <deal.II/base/config.h>
 
#include <deal.II/base/exceptions.h>
#include <deal.II/base/thread_management.h>
 
#include <atomic>
#include <mutex>
#include <optional>
 
DEAL_II_NAMESPACE_OPEN
 
namespace Threads
{
  template <typename T>
  class TaskResult
  {
  public:
    TaskResult()
      : result_is_available(false)
    {}
 
    TaskResult(const Task<T> &task)
      : result_is_available(false)
      , task(task)
    {
      // It is conceivable that the task has already finished if we
      // come to this point, but that is not important to us here:
      // we will simply find out once someone calls get()
    }
 
    TaskResult(const TaskResult<T> &) = delete;
 
    TaskResult(TaskResult<T> &&other) noexcept DEAL_II_CXX20_REQUIRES(
      std::is_move_constructible_v<T> &&std::is_move_assignable_v<T>);
 
    ~TaskResult();
 
    TaskResult &
    operator=(const TaskResult &) = delete;
 
    TaskResult &
    operator=(TaskResult &&other) noexcept DEAL_II_CXX20_REQUIRES(
      std::is_move_constructible_v<T> &&std::is_move_assignable_v<T>);
 
    void
    operator=(const Task<T> &t);
 
    template <typename Callable>
    void
    try_emplace_task(const Callable &creator) const
      DEAL_II_CXX20_REQUIRES((std::is_invocable_r_v<T, Callable>));
 
    void
    emplace_object(const T &t)
      DEAL_II_CXX20_REQUIRES((std::is_copy_constructible_v<T> ||
                              std::is_copy_assignable_v<T>));
 
    void
    emplace_object(T &&t)
      DEAL_II_CXX20_REQUIRES((std::is_copy_constructible_v<T> ||
                              std::is_copy_assignable_v<T>));
 
    void
    clear();
 
    void
    join() const;
 
    const T &
    value() const;
 
    bool
    empty() const;
 
  private:
    mutable std::atomic<bool> result_is_available;
 
    mutable std::optional<Task<T>> task;
 
    mutable std::optional<T> task_result;
 
    mutable std::mutex mutex;
  };
 
 
  // ------------------------------- inline functions --------------------------
 
#ifndef DOXYGEN
 
  template <typename T>
  inline TaskResult<T>::TaskResult(TaskResult<T> &&other) noexcept
    DEAL_II_CXX20_REQUIRES(
      std::is_move_constructible_v<T> &&std::is_move_assignable_v<T>)
  {
    // First lock the other object, then move the members of the other
    // object and reset it. Note that we do not have to wait for
    // the other object's task to finish (nor should we).
    std::scoped_lock lock(other.mutex);
 
    result_is_available       = other.result_is_available.load();
    other.result_is_available = false;
 
    task = std::move(other.task);
    other.task.reset();
 
    task_result = std::move(other.task_result);
    other.task_result.reset();
  }
 
 
 
  template <typename T>
  inline TaskResult<T>::~TaskResult()
  {
    // Ensure that there is no currently running task. As
    // documented, we consider this an error. Since clear()
    // also checks for this error, we can just defer to that function:
    clear();
  }
 
 
 
  template <typename T>
  inline void
  TaskResult<T>::operator=(const Task<T> &t)
  {
    // First ensure that there is no currently running task. As
    // documented, we consider this an error.  Since clear()
    // also checks for this error, we can just defer to that function:
    clear();
 
    // Having established that there is no previous task still running,
    // set the current task as the one we're waiting for:
    {
      std::scoped_lock lock(mutex);
      task = t;
    }
  }
 
 
  template <typename T>
  inline TaskResult<T> &
  TaskResult<T>::operator=(TaskResult<T> &&other) noexcept
    DEAL_II_CXX20_REQUIRES(
      std::is_move_constructible_v<T> &&std::is_move_assignable_v<T>)
  {
    // First clear the current object before we put new content into it:
    clear();
 
    // Then lock the other object and move the members of the other
    // object, and finally reset it. Note that we do not have to wait for
    // the other object's task to finish (nor should we): We may simply
    // inherit the other object's task.
    std::scoped_lock lock(other.mutex);
 
    result_is_available       = other.result_is_available.load();
    other.result_is_available = false;
 
    task = std::move(other.task);
    other.task.reset();
 
    task_result = std::move(other.task_result);
    other.task_result.reset();
 
    return *this;
  }
 
 
 
  template <typename T>
  template <typename Callable>
  void
  TaskResult<T>::try_emplace_task(const Callable &creator) const
    DEAL_II_CXX20_REQUIRES((std::is_invocable_r_v<T, Callable>))
  {
    // If the result is already available, simply return.
    if (result_is_available)
      return;
 
    // If the result was not available above, we need to go under a lock
    // to check that perhaps it has appeared in the meantime. We again use
    // the double-checking pattern:
    {
      std::scoped_lock lock(mutex);
      if (result_is_available)
        return;
      else
        // If there is no result, but there is a task, some other thread has
        // emplaced it in the meantime and we can simply return
        if (task.has_value())
          return;
        else
          // If there is no task object, emplace one:
          task = Threads::new_task(creator);
    }
  }
 
 
 
  template <typename T>
  inline void
  TaskResult<T>::emplace_object(const T &t)
    DEAL_II_CXX20_REQUIRES((std::is_copy_constructible_v<T> ||
                            std::is_copy_assignable_v<T>))
  {
    clear();
    task_result         = t;
    result_is_available = true;
  }
 
 
  template <typename T>
  inline void
  TaskResult<T>::emplace_object(T &&t)
    DEAL_II_CXX20_REQUIRES((std::is_copy_constructible_v<T> ||
                            std::is_copy_assignable_v<T>))
  {
    clear();
    task_result         = std::move(t);
    result_is_available = true;
  }
 
 
  template <typename T>
  inline void
  TaskResult<T>::clear()
  {
    std::scoped_lock lock(mutex);
 
    if (result_is_available)
      {
        // First make clear that the result is no longer available, then
        // reset the object:
        result_is_available = false;
        task_result.reset();
      }
    else
      Assert(task.has_value() == false,
             ExcMessage("You cannot destroy a TaskResult object "
                        "while it is still waiting for its associated task "
                        "to finish. See the documentation of this class' "
                        "destructor for more information."));
  }
 
 
 
  template <typename T>
  inline void
  TaskResult<T>::join() const
  {
    Assert(empty() == false,
           ExcMessage("You can't join a TaskResult object that has not "
                      "been associated with a task."));
 
    // If we have waited before, then return immediately:
    if (result_is_available)
      return;
    else
      // If we have not waited, wait now. We need to use the double-checking
      // pattern to ensure that if two threads get to this place at the same
      // time, one returns right away while the other does the work. Note
      // that this happens under the lock, so only one thread gets to be in
      // this code block at the same time:
      {
        std::scoped_lock lock(mutex);
        if (result_is_available)
          return;
        else
          {
            // The object is not empty and it has not received its result yet.
            // So it must have a task object:
            Assert(task.has_value(), ExcInternalError());
 
            task.value().join();
            task_result = std::move(task.value().return_value());
            task.reset();
 
            result_is_available = true;
          }
      }
  }
 
 
 
  template <typename T>
  inline bool
  TaskResult<T>::empty() const
  {
    // If we have waited for a task to complete, then the object is not empty:
    if (result_is_available)
      return false;
    // Otherwise, if result_is_available has not been set, but we have a task
    // associated (i.e., the task is still running, or at least we haven't
    // waited for it to complete), then the object is also not empty:
    else if (task.has_value())
      return false;
    else
      // If when we asked above we had not joined a task, and if there was
      // no task currently associated with the object, then one of two cases
      // could have happened: either, there never was a task, and the object
      // is consequently empty. Or there was a task and somewhere between the
      // checks above and now, join() has flipped the state to
      // result_is_available==true and task.has_value()==false. We can
      // check that, but only under a lock.
      {
        std::scoped_lock lock(mutex);
        if (result_is_available)
          return false;
        else
          // We know from getting into the above 'else that no task was
          // associated with this object at the time. This cannot have
          // changed since then in a way that is thread-safe (i.e., by
          // way of other 'const' functions), so if the result is still
          // not available, then the object must necessarily be empty:
          return true;
      }
  }
 
 
 
  template <typename T>
  inline const T &
  TaskResult<T>::value() const
  {
    Assert(empty() == false,
           ExcMessage(
             "You can't ask for the result of a TaskResult object that "
             "has not been associated with a task."));
 
    if (!result_is_available)
      join();
    return task_result.value();
  }
 
#endif
 
} // namespace Threads
 
 
DEAL_II_NAMESPACE_CLOSE
#endif