Skip to content

Library-wide conventions, with their memory and status headers - #268

Open
mmelnich wants to merge 2 commits into
sweep/coveragefrom
sweep/foundations
Open

mmelnich wants to merge 2 commits into
sweep/coveragefrom
sweep/foundations

Conversation

@mmelnich

Copy link
Copy Markdown
Contributor

Summary

Writes down the library-wide design that #40, #133, #183 and #186 converge on, in docs/CONVENTIONS.md, and adds the two small headers it rests on: rl_memory.hh (RAII buffers, grow-only workspace) and rl_status.hh (the numerical-outcome enum and a test-only fault hook). No existing routine changes here; routines move to the conventions one family at a time in later PRs, so this is the place to agree on the design.

The design in one paragraph: a driver object is a cuSOLVER-style handle holding its options, a grow-only workspace it reuses across calls, the results whose size depends on the rank reached, and info() about the last call. A choice among RandLAPACK's own implementations of a step is an enum class in the driver's Options; what the user brings (the operator, kernel oracles, preconditioners, callbacks) is a concept-constrained template parameter; there are no virtual strategy objects. All memory is RAII-owned, so failure paths need no cleanup code. A violated contract throws RandLAPACK::Error; what the numerics did is returned as RandLAPACK::Status, never discarded, with NaN and Inf reported rather than turned into a finite answer.

Two choices in the document deserve a specific look before routines move to it: results whose size depends on the rank reached are owned by the driver (cuSOLVER would have the caller allocate them at the maximum rank, which brings back dense-scale storage when callers pass k = min(m, n) as a bound), and Options::check_finite is on by default (one extra pass over a dense input, against at least one pass of sketching).

Changes

  • docs/CONVENTIONS.md: configuration (enums, templates, data), memory, workspace, results, dense and operator entry points, errors and numerical outcomes, NaN and Inf, GPU code, tests.
  • RandLAPACK/rl_memory.hh: util::make_buffer and util::make_zeroed_buffer (std::unique_ptr<T[]>), util::checked_mul, util::GrowBuffer (grow-only; ensure for scratch, grow for results that keep their prefix), a transitional util::MallocBuffer for outputs that callers still free with std::free, WorkspaceSize and MatrixView. Under RandLAPACK_POISON_WORKSPACE, memory handed out uninitialized is filled with NaN, or -1 for integers, which stays nonzero when LP64 builds narrow pivot arrays to 32 bits.
  • RandLAPACK/rl_status.hh: enum class [[nodiscard]] Status, to_string, and RL_TEST_FAULT, which is the constant false unless RandLAPACK_ENABLE_TEST_HOOKS is defined.
  • Tests: the test programs in test/ define both macros; test/misc/test_memory.cc and test/misc/test_status.cc cover the helpers, including allocation failure. Under AddressSanitizer its MallocBuffer half runs (the test program sets allocator_may_return_null=1); the GrowBuffer half is skipped there, since a failed throwing new is an AddressSanitizer error.
  • Docs: CONTRIBUTING.md, devnotes/idioms.md and docs/ARCHITECTURE.md point to the new document.

Stacked on #266 (coverage), whose CI section and instantiation file the new document references.

Part of #40, #133, #183 and #186.

docs/CONVENTIONS.md writes down the design that the open issues on
std::vector, workspace buffers, strategy objects and failure handling
converge on: a driver object is a cuSOLVER-style handle (options,
grow-only workspace, owned rank-adaptive results, info()); enums choose
among RandLAPACK's own implementations while concept-constrained
templates take what the user brings; RAII owns all memory; contract
violations throw RandLAPACK::Error and numerical outcomes return a
Status. Routines move to it one family at a time.

- RandLAPACK/rl_memory.hh: make_buffer and make_zeroed_buffer
  (unique_ptr<T[]>), checked_mul, GrowBuffer (grow-only, ensure for
  scratch, grow for results that keep their prefix), a transitional
  MallocBuffer for outputs callers still free with std::free,
  and, in namespace RandLAPACK, WorkspaceSize and MatrixView. Under
  RandLAPACK_POISON_WORKSPACE, memory handed out uninitialized is filled
  with NaN, or -1 for integers (nonzero after LP64 narrowing).
- RandLAPACK/rl_status.hh: enum class [[nodiscard]] Status, to_string,
  and RL_TEST_FAULT, a fault hook that is the constant false unless
  RandLAPACK_ENABLE_TEST_HOOKS is defined.
- The test programs in test/ define both macros; test_memory.cc and
  test_status.cc cover the helpers. The allocation-failure test runs under
  AddressSanitizer for MallocBuffer (the program sets
  allocator_may_return_null=1); the GrowBuffer half is skipped there,
  since a failed throwing new is an AddressSanitizer error.
- CONTRIBUTING.md, devnotes/idioms.md and docs/ARCHITECTURE.md point to
  the new document.

Verified locally (GCC 15.2, oneMKL ILP64, CUDA 13.3) on the coverage PR:
Debug, 577 of 579 tests passed, 2 skipped (thread-cap tests);
AddressSanitizer, the full suite passed except test_memory.cc's
allocation-failure test, which passes after the change above; Release
with CUDA, the 635 tests outside the exclusive label passed.
@codecov-commenter

Copy link
Copy Markdown

⚠️ Please install the 'codecov app svg image' to ensure uploads and comments are reliably processed by Codecov.

Codecov Report

❌ Patch coverage is 83.95062% with 13 lines in your changes missing coverage. Please review.

Files with missing lines Patch % Lines
RandLAPACK/rl_memory.hh 84.28% 3 Missing and 8 partials ⚠️
RandLAPACK/rl_status.hh 81.81% 1 Missing and 1 partial ⚠️

📢 Thoughts on this report? Let us know!

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.

2 participants