Skip to content

Consolidate buffering layer - C++20 Module preparation (#309)#314

Merged
kcenon merged 6 commits into
mainfrom
refactor/consolidate-buffering-layer-309
Jan 3, 2026
Merged

Consolidate buffering layer - C++20 Module preparation (#309)#314
kcenon merged 6 commits into
mainfrom
refactor/consolidate-buffering-layer-309

Conversation

@kcenon

@kcenon kcenon commented Jan 3, 2026

Copy link
Copy Markdown
Owner

Summary

  • Extract common buffer utilities to detail namespace for code reuse
  • Mark internal buffer APIs with @internal doxygen tags
  • Clarify public vs internal API boundary in documentation

Changes

1. Common Utilities Extraction (time_series_buffer.h)

  • detail::calculate_percentile(): Shared percentile calculation
  • detail::ring_buffer_index(): Common ring buffer indexing logic
  • detail::calculate_basic_statistics(): Unified statistics computation
  • Both time_series_buffer<T> and load_average_history now use these utilities

2. Internal API Markers

Added @internal doxygen tags to mark implementation details:

  • src/utils/ring_buffer.h
  • src/utils/buffering_strategy.h
  • src/utils/buffer_manager.h

3. Documentation Updates

  • ARCHITECTURE.md / ARCHITECTURE_KO.md: Distinguish Public vs Internal APIs
  • PROJECT_STRUCTURE.md: Document src/utils/ internal files

Sub-Issues Created

This PR creates the foundation for further consolidation work:

Test Plan

  • All 26 time series buffer tests pass
  • Library builds successfully
  • CI pipeline passes

Related

Closes #309
Part of C++20 Module Migration Epic (kcenon/common_system#256)

kcenon added 3 commits January 3, 2026 11:43
- Extract calculate_percentile to detail namespace for reuse
- Extract ring_buffer_index helper for consistent buffer indexing
- Extract calculate_basic_statistics for common statistics computation
- Refactor time_series_buffer to use detail utilities
- Refactor load_average_history to use detail utilities

This reduces code duplication between time_series_buffer and
load_average_history classes, following Kent Beck's "No Duplication"
principle as part of C++20 module preparation.

Part of #309
Add @internal doxygen tags to internal buffer implementation files:
- ring_buffer.h
- buffering_strategy.h
- buffer_manager.h

This clarifies the public vs internal API boundary for C++20 module
preparation and helps developers understand which APIs are stable.

Part of #309
Update architecture documentation to distinguish between:
- Public API: time_series_buffer, thread_local_buffer
- Internal API (@internal): buffer_manager, ring_buffer, buffering_strategy

Also add src/utils internal files to PROJECT_STRUCTURE.md to document
the internal buffer implementation layer.

Part of #309
@kcenon

kcenon commented Jan 3, 2026

Copy link
Copy Markdown
Owner Author

CI Status Note

The Windows MSVC build failure is unrelated to this PR. The error is:

warning C4996: 'kcenon::common::is_error': Use result.is_err() instead. Will be removed in v2.0.0.

This is a pre-existing issue in thread_system_adapter.h:99 where deprecated is_error() API is used, and -WX (warnings as errors) is enabled.

Summary of CI Results

  • Linux/macOS builds: All passing
  • Sanitizers: All passing (Address, Thread, Undefined)
  • Static analysis: All passing (Clang-Tidy, Cppcheck)
  • Windows MSVC: Pre-existing deprecation warning treated as error

The Windows issue should be tracked separately and is not related to the buffering layer consolidation work.

kcenon added 3 commits January 3, 2026 12:16
… member methods

Replace deprecated kcenon::common helper functions with Result member methods
to fix MSVC build warning treated as error (C4996):
- is_error(result) -> result.is_err()
- is_ok(result) -> result.is_ok()
- get_value(result) -> result.value()
- get_error(result) -> result.error()

Affected files:
- thread_system_adapter.h
- common_monitor_adapter.h
- common_system_adapter.h
Update examples to use Result member methods instead of deprecated
helper functions for consistency with the codebase:
- result.is_ok() instead of is_ok(result)
- result.is_err() instead of is_error(result)
- result.value() instead of get_value(result)
- result.error() instead of get_error(result)

Also fix bool conversion: if(result) -> if(result.is_ok())
Document the deprecated common_system helper function replacement that
fixes the MSVC build error (C4996 warning treated as error).
@kcenon kcenon merged commit 87f401d into main Jan 3, 2026
21 checks passed
@kcenon kcenon deleted the refactor/consolidate-buffering-layer-309 branch January 3, 2026 03:29
kcenon added a commit that referenced this pull request Apr 13, 2026
* refactor(utils): extract common buffer utilities to detail namespace

- Extract calculate_percentile to detail namespace for reuse
- Extract ring_buffer_index helper for consistent buffer indexing
- Extract calculate_basic_statistics for common statistics computation
- Refactor time_series_buffer to use detail utilities
- Refactor load_average_history to use detail utilities

This reduces code duplication between time_series_buffer and
load_average_history classes, following Kent Beck's "No Duplication"
principle as part of C++20 module preparation.

Part of #309

* docs(utils): mark internal buffer APIs with @internal tag

Add @internal doxygen tags to internal buffer implementation files:
- ring_buffer.h
- buffering_strategy.h
- buffer_manager.h

This clarifies the public vs internal API boundary for C++20 module
preparation and helps developers understand which APIs are stable.

Part of #309

* docs: clarify public vs internal buffer APIs

Update architecture documentation to distinguish between:
- Public API: time_series_buffer, thread_local_buffer
- Internal API (@internal): buffer_manager, ring_buffer, buffering_strategy

Also add src/utils internal files to PROJECT_STRUCTURE.md to document
the internal buffer implementation layer.

Part of #309

* fix(adapters): replace deprecated common_system helper functions with member methods

Replace deprecated kcenon::common helper functions with Result member methods
to fix MSVC build warning treated as error (C4996):
- is_error(result) -> result.is_err()
- is_ok(result) -> result.is_ok()
- get_value(result) -> result.value()
- get_error(result) -> result.error()

Affected files:
- thread_system_adapter.h
- common_monitor_adapter.h
- common_system_adapter.h

* refactor(examples): update Result pattern usage to modern API

Update examples to use Result member methods instead of deprecated
helper functions for consistency with the codebase:
- result.is_ok() instead of is_ok(result)
- result.is_err() instead of is_error(result)
- result.value() instead of get_value(result)
- result.error() instead of get_error(result)

Also fix bool conversion: if(result) -> if(result.is_ok())

* docs(changelog): add MSVC build fix entry

Document the deprecated common_system helper function replacement that
fixes the MSVC build error (C4996 warning treated as error).
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[REFACTOR] Consolidate buffering layer - C++20 Module preparation

1 participant