kcenon::thread::dag_job_builder Class Reference

Fluent builder for creating dag_job instances. More...

#include <dag_job_builder.h>

Collaboration diagram for kcenon::thread::dag_job_builder:

Public Member Functions
	dag_job_builder (const std::string &name="dag_job")
	Constructs a new builder with an optional job name.
	dag_job_builder (dag_job_builder &&) noexcept=default
	Move constructor.
auto	operator= (dag_job_builder &&) noexcept -> dag_job_builder &=default
	Move assignment operator.
	dag_job_builder (const dag_job_builder &)=delete
	Copy constructor (deleted - use move semantics)
auto	operator= (const dag_job_builder &) -> dag_job_builder &=delete
	Copy assignment operator (deleted - use move semantics)
	~dag_job_builder ()=default
	Destructor.
auto	work (std::function< common::VoidResult()> callable) -> dag_job_builder &
	Sets the work function to execute.
template<typename T >
auto	work_with_result (std::function< common::Result< T >()> callable) -> dag_job_builder &
	Sets the work function with result.
template<typename T >
auto	returns () -> dag_job_builder &
	Specifies the result type for the job.
auto	depends_on (job_id dependency) -> dag_job_builder &
	Adds a single dependency.
auto	depends_on (std::initializer_list< job_id > dependencies) -> dag_job_builder &
	Adds multiple dependencies from initializer list.
auto	depends_on (const std::vector< job_id > &dependencies) -> dag_job_builder &
	Adds multiple dependencies from vector.
auto	on_failure (std::function< common::VoidResult()> fallback) -> dag_job_builder &
	Sets the fallback function for failure recovery.
auto	is_valid () const -> bool
	Validates the builder configuration.
auto	get_validation_error () const -> std::optional< std::string >
	Gets the validation error message.
auto	build () -> std::unique_ptr< dag_job >
	Builds and returns the configured dag_job.
auto	reset () -> dag_job_builder &
	Resets the builder to its initial state.

Private Attributes
std::string	name_
std::function< common::VoidResult()>	work_func_
std::function< common::VoidResult(dag_job &)>	work_with_result_func_
std::function< common::VoidResult()>	fallback_func_
std::vector< job_id >	dependencies_
bool	has_return_type_ {false}

Detailed Description

Fluent builder for creating dag_job instances.

The dag_job_builder provides a convenient way to construct dag_job objects with dependencies, work functions, and other properties using a fluent API.

Design Pattern

This class implements the Builder pattern with method chaining (fluent interface). Each setter method returns a reference to the builder, allowing calls to be chained.

Thread Safety

• The builder itself is not thread-safe
• The built dag_job follows dag_job's thread-safety guarantees

Usage Example

auto job = dag_job_builder("process_data")
    .depends_on(fetch_job_id)
    .work([]() -> common::VoidResult {
        process_data();
        return common::ok();
    })
    .on_failure([]() -> common::VoidResult {
        log_failure();
        return common::ok();
    })
    .build();

Definition at line 56 of file dag_job_builder.h.

Constructor & Destructor Documentation

dag_job_builder() [1/3]

kcenon::thread::dag_job_builder::dag_job_builder ( const std::string & name = "dag_job" )

explicit

Constructs a new builder with an optional job name.

Parameters

name	Human-readable name for the job (default: "dag_job")

Definition at line 10 of file dag_job_builder.cpp.

    : name_(name)
{
}

dag_job_builder() [2/3]

kcenon::thread::dag_job_builder::dag_job_builder ( dag_job_builder && )

defaultnoexcept

Move constructor.

dag_job_builder() [3/3]

kcenon::thread::dag_job_builder::dag_job_builder ( const dag_job_builder & )

delete

Copy constructor (deleted - use move semantics)

~dag_job_builder()

kcenon::thread::dag_job_builder::~dag_job_builder ( )

default

Destructor.

Member Function Documentation

build()

auto kcenon::thread::dag_job_builder::build ( ) -> std::unique_ptr<dag_job>

nodiscard

Builds and returns the configured dag_job.

Returns

A unique_ptr to the built dag_job, or nullptr if validation fails

Validates the configuration before building. If validation fails, returns nullptr. Use is_valid() to check before building, or get_validation_error() to get the error message.

After calling build(), the builder is reset and can be reused.

Definition at line 74 of file dag_job_builder.cpp.

{
    // Validate configuration
    if (!is_valid())
    {
        return nullptr;
    }
 
    auto job = std::make_unique<dag_job>(name_);
 
    // Set dependencies
    job->add_dependencies(dependencies_);
 
    // Set work function
    if (work_with_result_func_)
    {
        // Capture the work_with_result function and create a wrapper
        auto result_func = std::move(work_with_result_func_);
        job->set_work([j = job.get(), func = std::move(result_func)]() -> common::VoidResult {
            return func(*j);
        });
    }
    else if (work_func_)
    {
        job->set_work(std::move(work_func_));
    }
 
    // Set fallback function
    if (fallback_func_)
    {
        job->set_fallback(std::move(fallback_func_));
    }
 
    // Reset builder for reuse (keep name)
    reset();
 
    return job;
}

depends_on() [1/3]

auto kcenon::thread::dag_job_builder::depends_on

(

const std::vector< job_id > &

dependencies

)

-> dag_job_builder&

Adds multiple dependencies from vector.

Parameters

dependencies

Vector of job IDs to depend on

Returns

Reference to this builder for chaining

Definition at line 42 of file dag_job_builder.cpp.

{
    for (const auto& dep : dependencies)
    {
        if (dep != INVALID_JOB_ID)
        {
            dependencies_.push_back(dep);
        }
    }
    return *this;
}

References kcenon::thread::INVALID_JOB_ID.

depends_on() [2/3]

auto kcenon::thread::dag_job_builder::depends_on

(

job_id

dependency

)

-> dag_job_builder&

Adds a single dependency.

Parameters

dependency

The job ID to depend on

Returns

Reference to this builder for chaining

Definition at line 21 of file dag_job_builder.cpp.

{
    if (dependency != INVALID_JOB_ID)
    {
        dependencies_.push_back(dependency);
    }
    return *this;
}

References kcenon::thread::INVALID_JOB_ID.

depends_on() [3/3]

auto kcenon::thread::dag_job_builder::depends_on

(

std::initializer_list< job_id >

dependencies

)

-> dag_job_builder&

Adds multiple dependencies from initializer list.

Parameters

dependencies

List of job IDs to depend on

Returns

Reference to this builder for chaining

Definition at line 30 of file dag_job_builder.cpp.

{
    for (const auto& dep : dependencies)
    {
        if (dep != INVALID_JOB_ID)
        {
            dependencies_.push_back(dep);
        }
    }
    return *this;
}

References kcenon::thread::INVALID_JOB_ID.

get_validation_error()

auto kcenon::thread::dag_job_builder::get_validation_error ( ) const -> std::optional<std::string>

nodiscard

Gets the validation error message.

Returns

Error message if invalid, std::nullopt if valid

Definition at line 65 of file dag_job_builder.cpp.

{
    if (!work_func_ && !work_with_result_func_)
    {
        return "No work function specified. Use work() or work_with_result() before build().";
    }
    return std::nullopt;
}

References work_func_, and work_with_result_func_.

is_valid()

auto kcenon::thread::dag_job_builder::is_valid ( ) const -> bool

nodiscard

Validates the builder configuration.

Returns

true if the configuration is valid

Checks that:

• A work function is set (either work() or work_with_result())
• Dependencies do not contain INVALID_JOB_ID

Definition at line 60 of file dag_job_builder.cpp.

{
    return work_func_ != nullptr || work_with_result_func_ != nullptr;
}

References work_func_, and work_with_result_func_.

on_failure()

auto kcenon::thread::dag_job_builder::on_failure

(

std::function< common::VoidResult()>

fallback

)

-> dag_job_builder&

Sets the fallback function for failure recovery.

Parameters

fallback

The function to execute on failure

Returns

Reference to this builder for chaining

The fallback function is called when the main work function fails and the DAG scheduler is configured with dag_failure_policy::fallback.

Definition at line 54 of file dag_job_builder.cpp.

{
    fallback_func_ = std::move(fallback);
    return *this;
}

References kcenon::thread::fallback.

operator=() [1/2]

auto kcenon::thread::dag_job_builder::operator= ( const dag_job_builder & ) -> dag_job_builder &=delete

delete

Copy assignment operator (deleted - use move semantics)

operator=() [2/2]

auto kcenon::thread::dag_job_builder::operator= ( dag_job_builder && ) -> dag_job_builder &=default

defaultnoexcept

Move assignment operator.

reset()

auto kcenon::thread::dag_job_builder::reset

(

)

-> dag_job_builder&

Resets the builder to its initial state.

Returns

Reference to this builder for chaining

Clears all configured settings (work function, dependencies, fallback) while preserving the job name. This allows the builder to be reused for creating multiple jobs.

Definition at line 113 of file dag_job_builder.cpp.

{
    work_func_ = nullptr;
    work_with_result_func_ = nullptr;
    fallback_func_ = nullptr;
    dependencies_.clear();
    has_return_type_ = false;
    return *this;
}

returns()

template<typename T >

auto kcenon::thread::dag_job_builder::returns ( ) -> dag_job_builder&

inline

Specifies the result type for the job.

Template Parameters

T	The result type

Returns

Reference to this builder for chaining

This method is used in combination with work() when the work function will set the result manually via the job's set_result() method.

Note

This is a marker method that documents intent. The actual result type is determined at runtime when set_result() is called.

Usage Example

auto job = dag_job_builder("compute")
    .returns<int>()
    .work([&scheduler, dep_id]() -> common::VoidResult {
        // Result type is specified by returns<int>()
        return common::ok();
    })
    .build();

Definition at line 148 of file dag_job_builder.h.

        {
            has_return_type_ = true;
            return *this;
        }

References has_return_type_.

work()

auto kcenon::thread::dag_job_builder::work

(

std::function< common::VoidResult()>

callable

)

-> dag_job_builder&

Sets the work function to execute.

Parameters

callable

The function to execute

Returns

Reference to this builder for chaining

The callable should return common::VoidResult:

• common::ok() on success
• common::VoidResult(error_info) on failure

Definition at line 15 of file dag_job_builder.cpp.

{
    work_func_ = std::move(callable);
    return *this;
}

work_with_result()

template<typename T >

auto kcenon::thread::dag_job_builder::work_with_result ( std::function< common::Result< T >()> callable ) -> dag_job_builder&

inline

Sets the work function with result.

Template Parameters

T	The result type

Parameters

callable

The function to execute

Returns

Reference to this builder for chaining

The result will be stored in the job and can be retrieved by dependent jobs.

Definition at line 111 of file dag_job_builder.h.

        {
            work_with_result_func_ = [func = std::move(callable)](dag_job& job) -> common::VoidResult {
                auto result = func();
                if (result.is_ok())
                {
                    job.set_result(result.value());
                    return common::ok();
                }
                return common::VoidResult(result.error());
            };
            return *this;
        }

References kcenon::thread::result< T >::is_ok(), kcenon::thread::result< T >::value(), and work_with_result_func_.

Here is the call graph for this function:

Member Data Documentation

dependencies_

std::vector<job_id> kcenon::thread::dag_job_builder::dependencies_

private

Definition at line 228 of file dag_job_builder.h.

fallback_func_

std::function<common::VoidResult()> kcenon::thread::dag_job_builder::fallback_func_

private

Definition at line 227 of file dag_job_builder.h.

has_return_type_

bool kcenon::thread::dag_job_builder::has_return_type_ {false}

private

Definition at line 229 of file dag_job_builder.h.

{false};

Referenced by returns().

name_

std::string kcenon::thread::dag_job_builder::name_

private

Definition at line 224 of file dag_job_builder.h.

work_func_

std::function<common::VoidResult()> kcenon::thread::dag_job_builder::work_func_

private

Definition at line 225 of file dag_job_builder.h.

Referenced by get_validation_error(), and is_valid().

work_with_result_func_

std::function<common::VoidResult(dag_job&)> kcenon::thread::dag_job_builder::work_with_result_func_

private

Definition at line 226 of file dag_job_builder.h.

Referenced by get_validation_error(), is_valid(), and work_with_result().

---

The documentation for this class was generated from the following files:

• include/kcenon/thread/dag/dag_job_builder.h
• src/dag/dag_job_builder.cpp