JobRunner.hpp

Go to the documentation of this file.

// SPDX-FileCopyrightText: 2026 Povl Filip Sonne-Frederiksen
//
// SPDX-License-Identifier: GPL-3.0-or-later
 
#pragma once
 
// In-process pipeline job runner for ONE project (#265, Phase 1).
//
// A FIFO queue of stage runs on a single worker thread, with a submit /
// status / cancel surface and per-job progress events. Since phase S2 of the
// ruxd multi-case spec it is a thin wrapper: a JobScheduler with one worker
// and one JobQueue (JobScheduler.hpp). Use the scheduler directly to run
// several projects' queues on one bounded worker pool — that is what ruxd
// does — and this class where one project is all there is (the Qt client,
// tests).
//
// PROGRESS: each job's stage reports through a core::ScopedProgressObserver
// installed on the worker thread for that job, chained to whatever global
// observer was installed (e.g. the rux CLI progress bar) — so progress is
// per-job even when several schedulers or workers run stages at once.
//
// THREAD SAFETY: every public member is safe to call from any thread. The
// ProjectDB instance used to execute a job is created and destroyed on the
// worker thread and never escapes it — ProjectDB itself is not thread-safe.
//
// WRITER EXCLUSION: the runner also owns the project's *writer lock* (see
// try_acquire_writer). The worker holds it for the whole execution of a stage,
// so anything else that wants to write to the same `.rux` — the GUI's editor
// endpoints, for instance — can take the same lock and be genuinely exclusive
// with the pipeline rather than merely hoping sqlite sorts it out.
 
#include "reusex/core/stages.hpp"
#include "reusex/pipeline/job_types.hpp"
#include "reusex/pipeline/stages.hpp"
 
#include <chrono>
#include <cstddef>
#include <cstdint>
#include <filesystem>
#include <functional>
#include <memory>
#include <mutex>
#include <optional>
#include <string>
#include <string_view>
#include <vector>
 
namespace reusex::pipeline {

struct JobRunnerOptions {
  size_t max_terminal_jobs = 256;
};

class JobRunner {
    public:
  explicit JobRunner(std::filesystem::path project,
                     StageExecutor executor = default_stage_executor());

  JobRunner(std::filesystem::path project, StageExecutor executor,
            JobRunnerOptions options);

  ~JobRunner();
 
  JobRunner(const JobRunner &) = delete;
  JobRunner &operator=(const JobRunner &) = delete;

  const std::filesystem::path &project() const noexcept;

  std::string submit(JobStage stage, std::string parameters = {});

  bool cancel(std::string_view id);

  std::optional<JobRecord> job(std::string_view id) const;

  std::vector<JobRecord> jobs() const;

  size_t queued_count() const;

  bool is_busy() const;

  void wait_idle();

  [[nodiscard]] WriterLease
  try_acquire_writer(std::chrono::milliseconds timeout);

  size_t add_listener(JobListener listener);

  void remove_listener(size_t token);
 
    private:
  class Impl;
  std::unique_ptr<Impl> impl_;
};
 
} // namespace reusex::pipeline