kcenon::thread::future_job< R > Class Template Reference

A job that wraps a callable and provides a future for its result. More...

#include <future_job.h>

Inheritance diagram for kcenon::thread::future_job< R >:

Collaboration diagram for kcenon::thread::future_job< R >:

Public Member Functions
template<typename F , typename = std::enable_if_t<std::is_invocable_r_v<R, F>>>
	future_job (F &&callable, const std::string &name="future_job")
	Constructs a future_job from a callable.
auto	get_future () -> std::future< R >
	Get the future associated with this job.
Public Member Functions inherited from kcenon::thread::job
auto	get_job_id () const -> std::uint64_t
	Gets the unique ID of this job.
auto	get_enqueue_time () const -> std::chrono::steady_clock::time_point
	Gets the time when this job was created (enqueued).
	job (const std::string &name="job")
	Constructs a new job with an optional human-readable name.
	job (const std::vector< uint8_t > &data, const std::string &name="data_job")
	Constructs a new job with associated raw byte data and a name.
virtual	~job (void)
	Virtual destructor for the job class to allow proper cleanup in derived classes.
auto	get_name (void) const -> std::string
	Retrieves the name of this job.
virtual auto	set_cancellation_token (const cancellation_token &token) -> void
	Sets a cancellation token that can be used to cancel the job.
virtual auto	get_cancellation_token () const -> cancellation_token
	Gets the cancellation token associated with this job.
virtual auto	set_job_queue (const std::shared_ptr< job_queue > &job_queue) -> void
	Associates this job with a specific job_queue.
virtual auto	get_job_queue (void) const -> std::shared_ptr< job_queue >
	Retrieves the job_queue associated with this job, if any.
virtual auto	to_string (void) const -> std::string
	Provides a string representation of the job for logging or debugging.
auto	with_on_complete (std::function< void(common::VoidResult)> callback) -> job &
	Attaches a completion callback to this job.
auto	with_on_error (std::function< void(const common::error_info &)> callback) -> job &
	Attaches an error callback to this job.
auto	with_priority (job_priority priority) -> job &
	Sets the priority level for this job.
auto	with_cancellation (const cancellation_token &token) -> job &
	Attaches a cancellation token to this job via composition.
auto	with_retry (const retry_policy &policy) -> job &
	Attaches a retry policy to this job.
auto	with_timeout (std::chrono::milliseconds timeout) -> job &
	Sets a timeout for job execution.
auto	get_priority () const -> job_priority
	Gets the priority level of this job.
auto	get_retry_policy () const -> std::optional< retry_policy >
	Gets the retry policy of this job.
auto	get_timeout () const -> std::optional< std::chrono::milliseconds >
	Gets the timeout duration for this job.
auto	has_explicit_cancellation () const -> bool
	Checks if this job has an explicit cancellation set via composition.
auto	has_components () const -> bool
	Checks if this job has any composed components.

Protected Member Functions
auto	do_work () -> common::VoidResult override
	Executes the callable and sets the promise value.
Protected Member Functions inherited from kcenon::thread::job
auto	invoke_callbacks (const common::VoidResult &result) -> void
	Invokes the completion callbacks if they are set.

Private Attributes
std::function< R()>	callable_
std::shared_ptr< std::promise< R > >	promise_

Additional Inherited Members
Protected Attributes inherited from kcenon::thread::job
std::string	name_
	The descriptive name of the job, used primarily for identification and logging.
std::vector< uint8_t >	data_
	An optional container of raw byte data that may be used by the job.
std::weak_ptr< job_queue >	job_queue_
	A weak reference to the job_queue that currently manages this job.
cancellation_token	cancellation_token_
	The cancellation token associated with this job.

Detailed Description

template<typename R>
class kcenon::thread::future_job< R >

A job that wraps a callable and provides a future for its result.

Template Parameters

R	The return type of the callable

Used internally by thread_pool::submit() to provide std::future-based async result retrieval. Prefer using thread_pool::submit() directly rather than creating future_job instances manually.

Thread Safety

• The promise is stored in a shared_ptr to ensure safe access from both the job execution context and the caller context.
• The future can be retrieved before or after job execution.

Exception Handling

• Any exception thrown by the callable is captured and stored in the promise, to be rethrown when get() is called on the future.

Definition at line 45 of file future_job.h.

Constructor & Destructor Documentation

future_job()

template<typename R >

template<typename F , typename = std::enable_if_t<std::is_invocable_r_v<R, F>>>

kcenon::thread::future_job< R >::future_job ( F && callable, const std::string & name = "future_job< R >" )

inlineexplicit

Constructs a future_job from a callable.

Template Parameters

F	Callable type (function, lambda, functor, etc.)

Parameters

callable	The function to execute
name	Optional name for the job (default: "future_job")

Note

The callable must be invocable with no arguments and return R.

Definition at line 58 of file future_job.h.

        : job(name)
        , callable_(std::forward<F>(callable))
        , promise_(std::make_shared<std::promise<R>>())
    {}

Member Function Documentation

do_work()

template<typename R >

auto kcenon::thread::future_job< R >::do_work ( void ) -> common::VoidResult

inlinenodiscardoverrideprotectedvirtual

Executes the callable and sets the promise value.

Returns

common::VoidResult indicating success or failure

This method is called by the worker thread. It:

1. Checks if cancellation was requested
2. Invokes the callable
3. Sets the promise value (or exception if one was thrown)

Reimplemented from kcenon::thread::job.

Definition at line 87 of file future_job.h.

                                                              {
        // Check for cancellation before starting
        if (cancellation_token_.is_cancelled()) {
            promise_->set_exception(
                std::make_exception_ptr(
                    std::runtime_error("Job cancelled before execution")
                )
            );
            return make_error_result(error_code::operation_canceled);
        }
 
        try {
            if constexpr (std::is_void_v<R>) {
                callable_();
                promise_->set_value();
            } else {
                promise_->set_value(callable_());
            }
        } catch (...) {
            promise_->set_exception(std::current_exception());
            return make_error_result(
                error_code::job_execution_failed,
                "Exception thrown during job execution"
            );
        }
 
        return common::ok();
    }

References kcenon::thread::future_job< R >::callable_, kcenon::thread::job::cancellation_token_, kcenon::thread::cancellation_token::is_cancelled(), kcenon::thread::job_execution_failed, kcenon::thread::make_error_result(), kcenon::thread::operation_canceled, and kcenon::thread::future_job< R >::promise_.

Here is the call graph for this function:

get_future()

template<typename R >

auto kcenon::thread::future_job< R >::get_future ( ) -> std::future<R>

inlinenodiscard

Get the future associated with this job.

Returns

A std::future that will hold the result of the callable

Note

This method should be called before the job is executed. The future remains valid after the job is moved.

Definition at line 72 of file future_job.h.

                                                    {
        return promise_->get_future();
    }

References kcenon::thread::future_job< R >::promise_.

Member Data Documentation

callable_

template<typename R >

std::function<R()> kcenon::thread::future_job< R >::callable_

private

Definition at line 117 of file future_job.h.

Referenced by kcenon::thread::future_job< R >::do_work().

promise_

template<typename R >

std::shared_ptr<std::promise<R> > kcenon::thread::future_job< R >::promise_

private

Definition at line 118 of file future_job.h.

Referenced by kcenon::thread::future_job< R >::do_work(), and kcenon::thread::future_job< R >::get_future().

---

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

• include/kcenon/thread/core/future_job.h