Fluent builder for creating and configuring jobs with composition. More...

#include <job_builder.h>

Collaboration diagram for kcenon::thread::job_builder:

Classes
class	built_job
	Internal job implementation created by the builder. More...

Public Member Functions
	job_builder ()=default
	Default constructor.

auto	name (const std::string &name) -> job_builder &
	Sets the job name.

auto	work (std::function< common::VoidResult()> work_fn) -> job_builder &
	Sets the work function for the job.

auto	work_with_data (const std::vector< uint8_t > &data, std::function< common::VoidResult(const std::vector< uint8_t > &)> work_fn) -> job_builder &
	Sets the work function with data parameter.

auto	cancellation (const cancellation_token &token) -> job_builder &
	Sets a cancellation token for cooperative cancellation.

auto	on_complete (std::function< void(common::VoidResult)> callback) -> job_builder &
	Sets a completion callback.

auto	on_error (std::function< void(const common::error_info &)> callback) -> job_builder &
	Sets an error callback.

auto	priority (job_priority prio) -> job_builder &
	Sets the job priority.

auto	retry (const retry_policy &policy) -> job_builder &
	Sets the retry policy.

auto	timeout (std::chrono::milliseconds timeout) -> job_builder &
	Sets the execution timeout.

template<typename JobType , typename... Args>
auto	from (Args &&... args) -> job_builder &

auto	build () -> std::unique_ptr< job >
	Builds and returns the configured job.

auto	build_shared () -> std::shared_ptr< job >
	Builds and returns the configured job as a shared pointer.

Private Attributes
std::string	name_

std::vector< uint8_t >	data_

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

std::function< common::VoidResult(const std::vector< uint8_t > &)>	data_work_fn_

cancellation_token	cancellation_token_

bool	has_cancellation_ {false}

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

std::function< void(const common::error_info &)>	on_error_

job_priority	priority_ {job_priority::normal}

bool	has_priority_ {false}

retry_policy	retry_policy_

bool	has_retry_ {false}

std::chrono::milliseconds	timeout_ {0}

bool	has_timeout_ {false}

std::function< std::unique_ptr< job >()>	custom_job_factory_

bool	use_custom_job_ {false}

Detailed Description

Fluent builder for creating and configuring jobs with composition.

The job_builder class provides a clean, fluent interface for creating jobs with various behaviors composed together.

Design Philosophy

Instead of inheritance-based specialization:

// Old way (inheritance)

class my_cancellable_callback_job : public callback_job { ... };

kcenon::thread::callback_job

A specialized job class that encapsulates user-defined callbacks.

Definition callback_job.h:44

Use composition via the builder:

// New way (composition)
auto job = job_builder()
    .name("my_job")
    .work([](){ return common::ok(); })
    .cancellation(token)
    .on_complete([](auto result){ ... })
    .build();

Thread Safety

The builder itself is not thread-safe during construction
The resulting job is safe to submit to any queue
Callbacks are invoked on the worker thread

Usage Examples

Basic Job

auto job = job_builder()
    .name("simple_job")
    .work([]{ std::cout << "Hello\n"; return common::ok(); })
    .build();

Job with Retry and Callback

auto job = job_builder()
    .name("network_request")
    .work([]{ return fetch_data(); })
    .retry(retry_policy::exponential_backoff(3))
    .on_error([](const auto& err) {
        log_error("Failed: {}", err.message);
    })
    .build();

Custom Job Type with Builder

class MyJob : public job {
public:
    MyJob(int value) : job("my_job"), value_(value) {}
    auto do_work() -> common::VoidResult override { ... }
private:
    int value_;
};
 
auto job = job_builder()
    .from<MyJob>(42)  // Creates MyJob with constructor arg 42
    .priority(job_priority::high)
    .timeout(std::chrono::seconds(30))
    .build();

Definition at line 97 of file job_builder.h.

Constructor & Destructor Documentation

◆ job_builder()

kcenon::thread::job_builder::job_builder ( )

default

Default constructor.

Examples: /home/runner/work/thread_system/thread_system/include/kcenon/thread/core/job_builder.h.

Member Function Documentation

◆ build()

auto kcenon::thread::job_builder::build ( ) -> std::unique_ptr<job>

inlinenodiscard

Builds and returns the configured job.

Returns: Unique pointer to the constructed job

Note: If no work function is set and no custom job type is used, the job's do_work() will return an error.

Examples: /home/runner/work/thread_system/thread_system/include/kcenon/thread/core/job_builder.h.

Definition at line 271 of file job_builder.h.

        {
            std::unique_ptr<job> result;
 
            if (use_custom_job_ && custom_job_factory_)
            {
                result = custom_job_factory_();
            }
            else
            {
                result = std::make_unique<built_job>(
                    name_.empty() ? "builder_job" : name_,
                    data_,
                    std::move(work_fn_),
                    std::move(data_work_fn_)
                );
            }
 
            // Apply composition
            if (has_cancellation_)
            {
                result->with_cancellation(cancellation_token_);
            }
            if (on_complete_)
            {
                result->with_on_complete(std::move(on_complete_));
            }
            if (on_error_)
            {
                result->with_on_error(std::move(on_error_));
            }
            if (has_priority_)
            {
                result->with_priority(priority_);
            }
            if (has_retry_)
            {
                result->with_retry(retry_policy_);
            }
            if (has_timeout_)
            {
                result->with_timeout(timeout_);
            }
 
            return result;
        }

References cancellation_token_, custom_job_factory_, data_, data_work_fn_, has_cancellation_, has_priority_, has_retry_, has_timeout_, name_, on_complete_, on_error_, priority_, retry_policy_, timeout_, use_custom_job_, and work_fn_.

Referenced by build_shared().

Here is the caller graph for this function:

◆ build_shared()

auto kcenon::thread::job_builder::build_shared ( ) -> std::shared_ptr<job>

inlinenodiscard

Builds and returns the configured job as a shared pointer.

Returns: Shared pointer to the constructed job

Examples: /home/runner/work/thread_system/thread_system/include/kcenon/thread/core/job_builder.h.

Definition at line 323 of file job_builder.h.

        {
            return build();
        }

References build().

Here is the call graph for this function:

◆ cancellation()

auto kcenon::thread::job_builder::cancellation ( const cancellation_token & token ) -> job_builder&

inline

Sets a cancellation token for cooperative cancellation.

Parameters

token Cancellation token to use

Returns: Reference to this builder for chaining

Examples: /home/runner/work/thread_system/thread_system/include/kcenon/thread/core/job_builder.h.

Definition at line 153 of file job_builder.h.

        {
            cancellation_token_ = token;
            has_cancellation_ = true;
            return *this;
        }

References cancellation_token_, and has_cancellation_.

◆ from()

template<typename JobType , typename... Args>

auto kcenon::thread::job_builder::from ( Args &&... args ) -> job_builder&

inline

Examples: /home/runner/work/thread_system/thread_system/include/kcenon/thread/core/job_builder.h.

Definition at line 248 of file job_builder.h.

        {
            static_assert(std::is_base_of_v<job, JobType>,
                "JobType must be derived from kcenon::thread::job");
 
            custom_job_factory_ = [args = std::make_tuple(std::forward<Args>(args)...)]() mutable
            {
                return std::apply([](auto&&... a) {
                    return std::make_unique<JobType>(std::forward<decltype(a)>(a)...);
                }, std::move(args));
            };
            use_custom_job_ = true;
            return *this;
        }

References custom_job_factory_, and use_custom_job_.

◆ name()

auto kcenon::thread::job_builder::name ( const std::string & name ) -> job_builder&

inline

Sets the job name.

Parameters

name	Descriptive name for the job

Returns: Reference to this builder for chaining

Examples: /home/runner/work/thread_system/thread_system/include/kcenon/thread/core/job_builder.h.

Definition at line 110 of file job_builder.h.

        {
            name_ = name;
            return *this;
        }

References name(), and name_.

Referenced by name().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ on_complete()

auto kcenon::thread::job_builder::on_complete ( std::function< void(common::VoidResult)> callback ) -> job_builder&

inline

Sets a completion callback.

Parameters

callback Function called when job completes (success or failure)

Returns: Reference to this builder for chaining

Examples: /home/runner/work/thread_system/thread_system/include/kcenon/thread/core/job_builder.h.

Definition at line 166 of file job_builder.h.

        {
            on_complete_ = std::move(callback);
            return *this;
        }

References kcenon::thread::callback, and on_complete_.

◆ on_error()

auto kcenon::thread::job_builder::on_error ( std::function< void(const common::error_info &)> callback ) -> job_builder&

inline

Sets an error callback.

Parameters

callback Function called only when job fails

Returns: Reference to this builder for chaining

Examples: /home/runner/work/thread_system/thread_system/include/kcenon/thread/core/job_builder.h.

Definition at line 178 of file job_builder.h.

        {
            on_error_ = std::move(callback);
            return *this;
        }

References kcenon::thread::callback, and on_error_.

◆ priority()

auto kcenon::thread::job_builder::priority ( job_priority prio ) -> job_builder&

inline

Sets the job priority.

Parameters

prio	Priority level for scheduling

Returns: Reference to this builder for chaining

Definition at line 190 of file job_builder.h.

        {
            priority_ = prio;
            has_priority_ = true;
            return *this;
        }

References has_priority_, and priority_.

◆ retry()

auto kcenon::thread::job_builder::retry ( const retry_policy & policy ) -> job_builder&

inline

Sets the retry policy.

Parameters

policy Retry behavior configuration

Returns: Reference to this builder for chaining

Definition at line 203 of file job_builder.h.

        {
            retry_policy_ = policy;
            has_retry_ = true;
            return *this;
        }

References has_retry_, and retry_policy_.

◆ timeout()

auto kcenon::thread::job_builder::timeout ( std::chrono::milliseconds timeout ) -> job_builder&

inline

Sets the execution timeout.

Parameters

timeout Maximum execution time allowed

Returns: Reference to this builder for chaining

Examples: /home/runner/work/thread_system/thread_system/include/kcenon/thread/core/job_builder.h.

Definition at line 216 of file job_builder.h.

        {
            timeout_ = timeout;
            has_timeout_ = true;
            return *this;
        }

References has_timeout_, timeout(), and timeout_.

Referenced by timeout().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ work()

auto kcenon::thread::job_builder::work ( std::function< common::VoidResult()> work_fn ) -> job_builder&

inline

Sets the work function for the job.

Parameters

work_fn Function that performs the job's work

Returns: Reference to this builder for chaining

Note: The work function should return common::ok() on success or common::error_info on failure.

Examples: /home/runner/work/thread_system/thread_system/include/kcenon/thread/core/job_builder.h.

Definition at line 125 of file job_builder.h.

        {
            work_fn_ = std::move(work_fn);
            return *this;
        }

References work_fn_.

◆ work_with_data()

auto kcenon::thread::job_builder::work_with_data	(	const std::vector< uint8_t > &	data,
		std::function< common::VoidResult(const std::vector< uint8_t > &)>	work_fn ) -> job_builder&

inline

Sets the work function with data parameter.

Parameters

data	Binary data to pass to the work function
work_fn	Function that processes the data

Returns: Reference to this builder for chaining

Examples: /home/runner/work/thread_system/thread_system/include/kcenon/thread/core/job_builder.h.

Definition at line 138 of file job_builder.h.

        {
            data_ = data;
            data_work_fn_ = std::move(work_fn);
            return *this;
        }

References data_, and data_work_fn_.

Member Data Documentation

◆ cancellation_token_

cancellation_token kcenon::thread::job_builder::cancellation_token_

private

Examples: /home/runner/work/thread_system/thread_system/include/kcenon/thread/core/job_builder.h.

Definition at line 400 of file job_builder.h.

Referenced by build(), and cancellation().

◆ custom_job_factory_

std::function<std::unique_ptr<job>()> kcenon::thread::job_builder::custom_job_factory_

private

Examples: /home/runner/work/thread_system/thread_system/include/kcenon/thread/core/job_builder.h.

Definition at line 415 of file job_builder.h.

Referenced by build(), and from().

◆ data_

std::vector<uint8_t> kcenon::thread::job_builder::data_

private

Examples: /home/runner/work/thread_system/thread_system/include/kcenon/thread/core/job_builder.h.

Definition at line 396 of file job_builder.h.

Referenced by build(), and work_with_data().

◆ data_work_fn_

std::function<common::VoidResult(const std::vector<uint8_t>&)> kcenon::thread::job_builder::data_work_fn_

private

Examples: /home/runner/work/thread_system/thread_system/include/kcenon/thread/core/job_builder.h.

Definition at line 398 of file job_builder.h.

Referenced by build(), and work_with_data().

◆ has_cancellation_

bool kcenon::thread::job_builder::has_cancellation_ {false}

private

Examples: /home/runner/work/thread_system/thread_system/include/kcenon/thread/core/job_builder.h.

Definition at line 401 of file job_builder.h.

401{false};

Referenced by build(), and cancellation().

◆ has_priority_

bool kcenon::thread::job_builder::has_priority_ {false}

private

Examples: /home/runner/work/thread_system/thread_system/include/kcenon/thread/core/job_builder.h.

Definition at line 407 of file job_builder.h.

407{false};

Referenced by build(), and priority().

◆ has_retry_

bool kcenon::thread::job_builder::has_retry_ {false}

private

Examples: /home/runner/work/thread_system/thread_system/include/kcenon/thread/core/job_builder.h.

Definition at line 410 of file job_builder.h.

410{false};

Referenced by build(), and retry().

◆ has_timeout_

bool kcenon::thread::job_builder::has_timeout_ {false}

private

Examples: /home/runner/work/thread_system/thread_system/include/kcenon/thread/core/job_builder.h.

Definition at line 413 of file job_builder.h.

413{false};

Referenced by build(), and timeout().

◆ name_

std::string kcenon::thread::job_builder::name_

private

Examples: /home/runner/work/thread_system/thread_system/include/kcenon/thread/core/job_builder.h.

Definition at line 395 of file job_builder.h.

Referenced by build(), and name().

◆ on_complete_

std::function<void(common::VoidResult)> kcenon::thread::job_builder::on_complete_

private

Examples: /home/runner/work/thread_system/thread_system/include/kcenon/thread/core/job_builder.h.

Definition at line 403 of file job_builder.h.

Referenced by build(), and on_complete().

◆ on_error_

std::function<void(const common::error_info&)> kcenon::thread::job_builder::on_error_

private

Examples: /home/runner/work/thread_system/thread_system/include/kcenon/thread/core/job_builder.h.

Definition at line 404 of file job_builder.h.

Referenced by build(), and on_error().

◆ priority_

job_priority kcenon::thread::job_builder::priority_ {job_priority::normal}

private

Examples: /home/runner/work/thread_system/thread_system/include/kcenon/thread/core/job_builder.h.

Definition at line 406 of file job_builder.h.

406{job_priority::normal};

kcenon::thread::job_priority::normal

@ normal

Normal priority, default for most jobs.

Referenced by build(), and priority().

◆ retry_policy_

retry_policy kcenon::thread::job_builder::retry_policy_

private

Examples: /home/runner/work/thread_system/thread_system/include/kcenon/thread/core/job_builder.h.

Definition at line 409 of file job_builder.h.

Referenced by build(), and retry().

◆ timeout_

std::chrono::milliseconds kcenon::thread::job_builder::timeout_ {0}

private

Examples: /home/runner/work/thread_system/thread_system/include/kcenon/thread/core/job_builder.h.

Definition at line 412 of file job_builder.h.

412{0};

Referenced by build(), and timeout().

◆ use_custom_job_

bool kcenon::thread::job_builder::use_custom_job_ {false}

private

Examples: /home/runner/work/thread_system/thread_system/include/kcenon/thread/core/job_builder.h.

Definition at line 416 of file job_builder.h.

416{false};

Referenced by build(), and from().

◆ work_fn_

std::function<common::VoidResult()> kcenon::thread::job_builder::work_fn_

private

Examples: /home/runner/work/thread_system/thread_system/include/kcenon/thread/core/job_builder.h.

Definition at line 397 of file job_builder.h.

Referenced by build(), and work().

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

include/kcenon/thread/core/job_builder.h

Classes

Public Member Functions

Private Attributes

Detailed Description

Design Philosophy

Thread Safety

Usage Examples

Basic Job

Job with Retry and Callback

Custom Job Type with Builder

Constructor & Destructor Documentation

◆ job_builder()

Member Function Documentation

◆ build()

◆ build_shared()

◆ cancellation()

◆ from()

◆ name()

◆ on_complete()

◆ on_error()

◆ priority()

◆ retry()

◆ timeout()

◆ work()

◆ work_with_data()

Member Data Documentation

◆ cancellation_token_

◆ custom_job_factory_

◆ data_

◆ data_work_fn_

◆ has_cancellation_

◆ has_priority_

◆ has_retry_

◆ has_timeout_

◆ name_

◆ on_complete_

◆ on_error_

◆ priority_

◆ retry_policy_

◆ timeout_

◆ use_custom_job_

◆ work_fn_