tasks.hpp

Go to the documentation of this file.

#pragma once
 
/// @file userver/testsuite/tasks.hpp
/// @brief @copybrief testsuite::TestsuiteTasks
 
#include <atomic>
#include <functional>
#include <memory>
#include <string>
#include <unordered_map>
 
#include <userver/components/component_fwd.hpp>
#include <userver/concurrent/variable.hpp>
#include <userver/engine/task/task_with_result.hpp>
 
USERVER_NAMESPACE_BEGIN
 
namespace testsuite {
 
class TaskNotFound final : public std::runtime_error {
  using std::runtime_error::runtime_error;
};
 
class TaskAlreadyRunning final : public std::runtime_error {
  using std::runtime_error::runtime_error;
};
 
// clang-format off
 
/// @brief Testsuite tasks support
///
/// A testsuite task is a function that can be called from testsuite by its name.
/// Only one task with the same name can be run simultaneously.
///
 
// clang-format on
class TestsuiteTasks final {
 public:
  /// Task function type
  using TaskCallback = std::function<void()>;
 
  explicit TestsuiteTasks(bool is_enabled);
  ~TestsuiteTasks();
 
  /// @brief Are testsuite tasks enabled or not
  ///
  /// It is recommended to register tasks only for testsuite environment. Use
  /// this method to test weather or not you are running under testsuite:
  /// @code
  /// if (testsuite_tasks.IsEnabled()) {
  ///   // testsuite code goes here...
  /// } else {
  ///   // production code goes here...
  /// }
  /// @endcode
  bool IsEnabled() const { return is_enabled_; }
 
  /// @brief Register new task
  /// @param name Task name
  /// @param callback Testsuite task callback function
  /// @throws std::runtime_error When task with `name` is already registered.
  void RegisterTask(const std::string& name, TaskCallback callback);
 
  /// @brief Unregister task
  /// @param name Task name
  /// @throws std::runtime_error When task `name` is not known.
  void UnregisterTask(const std::string& name);
 
  /// @brief Run task by name and waits for it to finish
  /// @param name Task name
  /// @throws TaskAlreadyRunning When task `name` is already running.
  void RunTask(const std::string& name);
 
  /// @brief Asynchronously starts the task
  /// @param name Task name
  /// @returns Task id
  /// @throws TaskAlreadyRunning When task `name` is already running.
  std::string SpawnTask(const std::string& name);
 
  /// @brief Stop previously spawned task
  /// @param task_id Task id returned by `SpawnTask()`
  /// @throws TaskNotFound When task `task_id` is not known.
  void StopSpawnedTask(const std::string& task_id);
 
  /// @brief Checks that there are no running tasks left.
  ///
  /// Must be called on service shutdown. Aborts process when there are tasks
  /// running.
  void CheckNoRunningTasks() noexcept;
 
  /// @brief Returns list of registered task names
  std::vector<std::string> GetTaskNames() const;
 
 private:
  struct Entry {
    std::atomic<bool> running_flag{false};
    TaskCallback callback;
  };
 
  struct SpawnedTask {
    std::atomic<bool> busy_flag{false};
    std::string name;
    engine::TaskWithResult<void> task;
  };
 
  std::shared_ptr<Entry> GetEntryFor(const std::string& name);
  std::shared_ptr<SpawnedTask> GetSpawnedFor(const std::string& task_id);
 
  const bool is_enabled_;
 
  using TasksMap = std::unordered_map<std::string, std::shared_ptr<Entry>>;
  concurrent::Variable<TasksMap> tasks_;
 
  using SpawnedMap =
      std::unordered_map<std::string, std::shared_ptr<SpawnedTask>>;
  concurrent::Variable<SpawnedMap> spawned_;
};
 
/// @brief Get reference to TestsuiteTasks instance
/// @param component_context
TestsuiteTasks& GetTestsuiteTasks(
    const components::ComponentContext& component_context);
 
}  // namespace testsuite
 
USERVER_NAMESPACE_END