Repository navigation
Conversation
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.
This was referenced Oct 29, 2026
|
Codecov Report❌ Patch coverage is
📢 Thoughts on this report? Let us know! |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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) andrl_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 anenum classin the driver'sOptions; 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 throwsRandLAPACK::Error; what the numerics did is returned asRandLAPACK::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), andOptions::check_finiteis 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_bufferandutil::make_zeroed_buffer(std::unique_ptr<T[]>),util::checked_mul,util::GrowBuffer(grow-only;ensurefor scratch,growfor results that keep their prefix), a transitionalutil::MallocBufferfor outputs that callers still free withstd::free,WorkspaceSizeandMatrixView. UnderRandLAPACK_POISON_WORKSPACE, memory handed out uninitialized is filled with NaN, or-1for integers, which stays nonzero when LP64 builds narrow pivot arrays to 32 bits.RandLAPACK/rl_status.hh:enum class [[nodiscard]] Status,to_string, andRL_TEST_FAULT, which is the constantfalseunlessRandLAPACK_ENABLE_TEST_HOOKSis defined.test/define both macros;test/misc/test_memory.ccandtest/misc/test_status.cccover the helpers, including allocation failure. Under AddressSanitizer itsMallocBufferhalf runs (the test program setsallocator_may_return_null=1); theGrowBufferhalf is skipped there, since a failed throwingnewis an AddressSanitizer error.CONTRIBUTING.md,devnotes/idioms.mdanddocs/ARCHITECTURE.mdpoint 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.