Skip to content

refactor(api): replace throw statements with Result<T> in public headers#675

Merged
kcenon merged 1 commit into
mainfrom
feat/issue-671-replace-throw-with-result-t
Apr 13, 2026
Merged

refactor(api): replace throw statements with Result<T> in public headers#675
kcenon merged 1 commit into
mainfrom
feat/issue-671-replace-throw-with-result-t

Conversation

@kcenon

@kcenon kcenon commented Apr 13, 2026

Copy link
Copy Markdown
Owner

What

Summary

Replace all throw statements in public API headers with common::Result<T> or common::VoidResult return types, ensuring consistent error handling before the v1.0 API freeze.

Change Type

  • Refactor (no functional changes in error behavior, but API signatures changed)

Affected Components

  • include/kcenon/thread/core/cancellation_token.h — throw_if_cancelled() → check_cancelled() returning VoidResult
  • include/kcenon/thread/core/enhanced_cancellation_token.h — same rename + cancellation_scope::check_cancelled() return type
  • include/kcenon/thread/core/cancellable_future.h — get() and get_for() return Result types
  • include/kcenon/thread/core/thread_pool_impl.h — submit_wait_any() returns Result<R>
  • include/kcenon/thread/core/thread_pool.h — declaration update
  • core/sync/include/cancellation_token.h — module build copy sync

Why

Related Issues

Motivation

  • Public API mixed exception-based and Result-based error handling inconsistently
  • error_handling.h provides comprehensive make_error_result<T>() infrastructure but it was not applied in all public methods
  • v1.0 API stability requires a single, predictable error handling pattern
  • Exceptions in threading libraries can cause undefined behavior at thread boundaries if uncaught

Where

Files Changed

Directory Files Type of Change
include/kcenon/thread/core/ 6 API signature changes
core/sync/include/ 1 Module build sync
src/core/ 1 Implementation update
tests/unit/ 3 Test assertions updated

API Changes

API Before After
cancellation_token::throw_if_cancelled() void (throws) Removed → check_cancelled() returns VoidResult
enhanced_cancellation_token::throw_if_cancelled() void (throws) Removed → check_cancelled() returns VoidResult
cancellation_scope::check_cancelled() void (throws) Returns VoidResult
cancellable_future<R>::get() R (throws) common::Result<R>
cancellable_future<R>::get_for() optional<R> (throws) common::Result<optional<R>>
cancellable_future<void>::get() void (throws) common::VoidResult
cancellable_future<void>::get_for() bool (throws) common::Result<bool>
thread_pool::submit_wait_any() R (throws) common::Result<R>

How

Implementation Details

  1. Each throw site mapped to appropriate error_code from error_handling.h
  2. Functions returning values changed to common::Result<T> wrapping both cancellation errors and future exceptions
  3. std::future::get() exceptions caught and converted to error_code::job_execution_failed
  4. All tests updated from EXPECT_THROW to EXPECT_TRUE(result.is_err()) pattern

Testing Done

  • Full build passes (debug preset)
  • 382/383 unit tests pass (1 pre-existing failure: LifecycleControllerTest.InitialStateIsCreated)
  • All modified tests verified with new Result-based assertions

Breaking Changes

  • throw_if_cancelled() renamed to check_cancelled() (both token types)
  • cancellable_future::get() return type changed from R to common::Result<R>
  • cancellable_future::get_for() return type changed
  • thread_pool::submit_wait_any() return type changed from R to common::Result<R>

Test Plan

  1. Build: cmake --preset debug && cmake --build build-debug
  2. Run tests: cd build-debug && ctest --output-on-failure
  3. Verify zero throw in public headers: grep -rn '\bthrow\b' include/kcenon/thread/core/

@kcenon
refactor(api): replace throw statements with Result<T> in public headers
a673863 
Migrate public API error handling from exceptions to Result<T> pattern
for v1.0 API stability. All throw statements in public headers are now
replaced with common::Result<T> or common::VoidResult returns.

Changes:
- cancellation_token: rename throw_if_cancelled() to check_cancelled()
  returning VoidResult
- enhanced_cancellation_token: same rename + update cancellation_scope
- cancellable_future<R>: get() returns Result<R>, get_for() returns
  Result<optional<R>>
- cancellable_future<void>: get() returns VoidResult, get_for() returns
  Result<bool>
- thread_pool::submit_wait_any(): returns Result<R> instead of throwing
  on empty input
- Update all affected tests to use Result-based assertions

Closes #671
@kcenon kcenon mentioned this pull request Apr 13, 2026
Closed
5 tasks
@github-actions

github-actions Bot commented Apr 13, 2026

Copy link
Copy Markdown
Contributor

📊 Performance Benchmark Results

Performance Benchmark Report

No benchmark data available.

ℹ️ No baseline reference available

This is the first benchmark run or baseline file is missing.

@kcenon kcenon merged commit 2b70ad1 into main Apr 13, 2026
27 checks passed
@kcenon kcenon deleted the feat/issue-671-replace-throw-with-result-t branch April 13, 2026 22:37
This was referenced Apr 15, 2026
Merged
Merged
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Replace throw statements with Result<T> in public API

1 participant

@kcenon