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

A future wrapper that supports cancellation. More...

#include <cancellable_future.h>

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

Public Types
using	value_type = R

Public Member Functions
	cancellable_future (std::future< R > future, cancellation_token token)
	Construct a cancellable_future.
	~cancellable_future ()=default
	cancellable_future (const cancellable_future &)=delete
cancellable_future &	operator= (const cancellable_future &)=delete
	cancellable_future (cancellable_future &&) noexcept=default
cancellable_future &	operator= (cancellable_future &&) noexcept=default
auto	get () -> common::Result< R >
	Wait for and retrieve the result.
auto	get_for (std::chrono::milliseconds timeout) -> common::Result< std::optional< R > >
	Wait for the result with timeout.
auto	is_ready () const -> bool
	Check if the result is ready.
auto	is_cancelled () const -> bool
	Check if the operation was cancelled.
void	cancel ()
	Request cancellation of the operation.
auto	valid () const -> bool
	Check if the future is valid.
void	wait () const
	Wait for the result to become ready.
template<typename Rep , typename Period >
auto	wait_for (const std::chrono::duration< Rep, Period > &timeout) const -> std::future_status
	Wait for the result with timeout.
auto	get_token () const -> cancellation_token
	Get the cancellation token.

Private Attributes
std::future< R >	future_
cancellation_token	token_

Detailed Description

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

A future wrapper that supports cancellation.

Template Parameters

R	The result type of the future

This class wraps a std::future and a cancellation_token together, providing unified access to both the result and cancellation status.

Thread Safety

• All methods are thread-safe.
• The cancellation token can be shared across multiple contexts.

Usage Example

auto [future, token] = pool->submit_cancellable([] {
    // Long-running work
    return compute_result();
});
 
// Later, if we need to cancel:
future.cancel();
 
// Or wait with timeout:
if (auto result = future.get_for(std::chrono::seconds(5))) {
    process(*result);
} else {
    handle_timeout();
}

Definition at line 56 of file cancellable_future.h.

Member Typedef Documentation

value_type

template<typename R >

using kcenon::thread::cancellable_future< R >::value_type = R

Definition at line 58 of file cancellable_future.h.

Constructor & Destructor Documentation

cancellable_future() [1/3]

template<typename R >

kcenon::thread::cancellable_future< R >::cancellable_future ( std::future< R > future, cancellation_token token )

inline

Construct a cancellable_future.

Parameters

future	The underlying std::future
token	The cancellation token for this operation

Definition at line 66 of file cancellable_future.h.

        : future_(std::move(future))
        , token_(std::move(token))
    {}

~cancellable_future()

template<typename R >

kcenon::thread::cancellable_future< R >::~cancellable_future ( )

default

cancellable_future() [2/3]

template<typename R >

kcenon::thread::cancellable_future< R >::cancellable_future ( const cancellable_future< R > & )

delete

cancellable_future() [3/3]

template<typename R >

kcenon::thread::cancellable_future< R >::cancellable_future ( cancellable_future< R > && )

defaultnoexcept

Member Function Documentation

cancel()

template<typename R >

void kcenon::thread::cancellable_future< R >::cancel ( )

inline

Request cancellation of the operation.

This signals the associated job to stop. The job must cooperatively check its cancellation token for this to have effect.

Definition at line 162 of file cancellable_future.h.

                  {
        token_.cancel();
    }

References kcenon::thread::cancellation_token::cancel(), and kcenon::thread::cancellable_future< R >::token_.

Here is the call graph for this function:

get()

template<typename R >

auto kcenon::thread::cancellable_future< R >::get ( ) -> common::Result<R>

inlinenodiscard

Wait for and retrieve the result.

Returns

common::Result<R> containing the value on success, or an error if the operation was cancelled or threw an exception

This method blocks until the result is ready or the operation is cancelled.

Definition at line 91 of file cancellable_future.h.

                                                {
        if (token_.is_cancelled()) {
            return make_error_result<R>(error_code::operation_canceled);
        }
        try {
            return common::Result<R>::ok(future_.get());
        } catch (const std::exception& e) {
            return make_error_result<R>(error_code::job_execution_failed, e.what());
        } catch (...) {
            return make_error_result<R>(error_code::unknown_error, "Unknown exception in future");
        }
    }

References kcenon::thread::cancellation_token::is_cancelled(), kcenon::thread::job_execution_failed, kcenon::thread::make_error_result(), kcenon::thread::cancellable_future< R >::token_, and kcenon::thread::unknown_error.

Here is the call graph for this function:

get_for()

template<typename R >

auto kcenon::thread::cancellable_future< R >::get_for ( std::chrono::milliseconds timeout ) -> common::Result<std::optional<R>>

inlinenodiscard

Wait for the result with timeout.

Parameters

timeout

Maximum time to wait

Returns

common::Result<std::optional<R>> containing the value if ready, std::nullopt on timeout, or an error if cancelled/failed

This method waits up to the specified timeout for the result. Returns std::nullopt in the Result if the timeout expires.

Definition at line 114 of file cancellable_future.h.

    {
        if (token_.is_cancelled()) {
            return make_error_result<std::optional<R>>(error_code::operation_canceled);
        }
 
        auto status = future_.wait_for(timeout);
        if (status == std::future_status::ready) {
            try {
                return common::Result<std::optional<R>>::ok(future_.get());
            } catch (const std::exception& e) {
                return make_error_result<std::optional<R>>(
                    error_code::job_execution_failed, e.what());
            } catch (...) {
                return make_error_result<std::optional<R>>(
                    error_code::unknown_error, "Unknown exception in future");
            }
        }
        return common::Result<std::optional<R>>::ok(std::nullopt);
    }

References kcenon::thread::cancellable_future< R >::future_, kcenon::thread::cancellation_token::is_cancelled(), kcenon::thread::job_execution_failed, kcenon::thread::make_error_result(), kcenon::thread::operation_canceled, kcenon::thread::cancellable_future< R >::token_, and kcenon::thread::unknown_error.

Here is the call graph for this function:

get_token()

template<typename R >

auto kcenon::thread::cancellable_future< R >::get_token ( ) const -> cancellation_token

inlinenodiscard

Get the cancellation token.

Returns

A copy of the cancellation token

Definition at line 202 of file cancellable_future.h.

                                                               {
        return token_;
    }

References kcenon::thread::cancellable_future< R >::token_.

is_cancelled()

template<typename R >

auto kcenon::thread::cancellable_future< R >::is_cancelled ( ) const -> bool

inlinenodiscard

Check if the operation was cancelled.

Returns

true if cancellation was requested, false otherwise

Definition at line 151 of file cancellable_future.h.

                                                    {
        return token_.is_cancelled();
    }

References kcenon::thread::cancellation_token::is_cancelled(), and kcenon::thread::cancellable_future< R >::token_.

Here is the call graph for this function:

is_ready()

template<typename R >

auto kcenon::thread::cancellable_future< R >::is_ready ( ) const -> bool

inlinenodiscard

Check if the result is ready.

Returns

true if the result is available, false otherwise

Definition at line 141 of file cancellable_future.h.

                                                {
        return future_.wait_for(std::chrono::seconds(0)) ==
               std::future_status::ready;
    }

References kcenon::thread::cancellable_future< R >::future_.

operator=() [1/2]

template<typename R >

cancellable_future & kcenon::thread::cancellable_future< R >::operator= ( cancellable_future< R > && )

defaultnoexcept

operator=() [2/2]

template<typename R >

cancellable_future & kcenon::thread::cancellable_future< R >::operator= ( const cancellable_future< R > & )

delete

valid()

template<typename R >

auto kcenon::thread::cancellable_future< R >::valid ( ) const -> bool

inlinenodiscard

Check if the future is valid.

Returns

true if the future has a shared state, false otherwise

Definition at line 171 of file cancellable_future.h.

                                             {
        return future_.valid();
    }

References kcenon::thread::cancellable_future< R >::future_.

wait()

template<typename R >

void kcenon::thread::cancellable_future< R >::wait ( ) const

inline

Wait for the result to become ready.

Blocks until the result is available.

Definition at line 180 of file cancellable_future.h.

                      {
        future_.wait();
    }

References kcenon::thread::cancellable_future< R >::future_.

wait_for()

template<typename R >

template<typename Rep , typename Period >

auto kcenon::thread::cancellable_future< R >::wait_for ( const std::chrono::duration< Rep, Period > & timeout ) const -> std::future_status

inlinenodiscard

Wait for the result with timeout.

Parameters

timeout

Maximum time to wait

Returns

The future status after waiting

Definition at line 191 of file cancellable_future.h.

    {
        return future_.wait_for(timeout);
    }

References kcenon::thread::cancellable_future< R >::future_.

Member Data Documentation

future_

template<typename R >

std::future<R> kcenon::thread::cancellable_future< R >::future_

mutableprivate

Definition at line 207 of file cancellable_future.h.

Referenced by kcenon::thread::cancellable_future< R >::get_for(), kcenon::thread::cancellable_future< void >::get_for(), kcenon::thread::cancellable_future< R >::is_ready(), kcenon::thread::cancellable_future< void >::is_ready(), kcenon::thread::cancellable_future< R >::valid(), kcenon::thread::cancellable_future< void >::valid(), kcenon::thread::cancellable_future< R >::wait(), kcenon::thread::cancellable_future< void >::wait(), kcenon::thread::cancellable_future< R >::wait_for(), and kcenon::thread::cancellable_future< void >::wait_for().

token_

template<typename R >

cancellation_token kcenon::thread::cancellable_future< R >::token_

private

Definition at line 208 of file cancellable_future.h.

Referenced by kcenon::thread::cancellable_future< R >::cancel(), kcenon::thread::cancellable_future< void >::cancel(), kcenon::thread::cancellable_future< R >::get(), kcenon::thread::cancellable_future< void >::get(), kcenon::thread::cancellable_future< R >::get_for(), kcenon::thread::cancellable_future< void >::get_for(), kcenon::thread::cancellable_future< R >::get_token(), kcenon::thread::cancellable_future< void >::get_token(), kcenon::thread::cancellable_future< R >::is_cancelled(), and kcenon::thread::cancellable_future< void >::is_cancelled().

---

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

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