Repository navigation
Review use of exceptions #18
Description
Scott began a section on exceptions, which I have updated.
Scott also added some notes on errors in the GraphBLAS C API, which I have moved to below:
Notes on C API errors
Informational return values
SUCCESS: not necessary with exceptionsNO_VALUE: happens in extractElement() method when providing a transparent destination scalar and no stored value. Usinggrb::out_of_rangeexception. The justification for changing informational return with exception is the consistency with STL containerat()method behaviour.
API errors
UNINITIALIZED_OBJECT: not necessary with RAII philosophyNULL_POINTER: not necessary, no pointers used in C++ APIINVALID_VALUE:- used with incorrect enum values (not necessary in C++)
- used if a dimension is defined as 0 (like in vector or matrix construction or resize, (do we need this?)
- duplicate indices during build (do we need this?).
INVALID_INDEX: This is specifically for indices that are outside the defined dimensions (forsetElement(),extractElement(),removeElement()). Does this overload withNO_VALUE?DOMAIN_MISMATCH: not applicable in C++...if it compiles there is no mismatch.OUTPUT_NOT_EMPTY: was used when trying tobuildwith a container that is not empty....what should C++ do?NOT_IMPLEMENTED: ???
Execution Errors
PANIC- do we need this?OUT_OF_MEMORY: usingstd::bad_alloc... why notgrb::bad_alloc? Because allocators not part of GraphBLAS spec.INSUFFICIENT_SPACE: ???INVALID_OBJECT: The requires a discussion of exception quarantees. I.e. what is the state of an output object when an exception is thrown during an operation it was called with? This is also complicated by non-blocking mode which is deferred for now.INDEX_OUT_OF_BOUNDS:grb::out_of_range(This is overloaded use...for two different meanings)EMPTY_OBJECT: (only called in reduce to scalar...does C++ API side step this)
Metadata
Metadata
Assignees
Labels
No labels
Type
Projects
- Status
Activity
[-]Write section on exceptions, normalize names of exceptions[/-][+]Review use of exceptions[/+]mcmillan03 commentedon Jun 13, 2023
Exceptions and Error Handling section is currently under Algorithms
Are all
grb:: exceptionssubclassed fromstd::exception?...or we could consider subclassing fromstd::logic_errorandstd::runtime_errorclasses instead.std::logic_errorsubclass roughly corresponds to API errors- E.g., invalid args, domain, dimensions, out_of_range)
std::runtime_error subclass roughly corresponds to execution errors- E.g., panic, file_io, over/underflow, system_error
-
grb::api_errorsandgrb::execution_errors, OR-
grb::logic_errorsandgrb::runtime_errorsgrb::exceptionallows the user to separategrbspecific exceptions from others- I am not sure this is a necessary consideration, and we should consider the alternative of logic_error/runtime_error subclassing instead.
We need to be sure to review spec to make sure all possible
noexceptspecs are specified.All calls to Allocator::allocate may throw. Do we need to specify which exception(s)?
grb::matrixctorgrb::vectorctor (this constructor is not documented the same as matrix constructor)matrix::read_matrix(). Soon to be free function.grb::out_of_rangematrix::at(),vector::at()Is there a precedent out_of_range is not intuitive name for no stored element, it seems more appropriate name for indices that are outside of range of the dimensions. Perhaps consider grb::invalid_location exceptiongrb::matrix_io::file_error,grb::matrix_io::unsupported_file_formatmatrix_ioat all? Might prefergrb::file_io:: namespacegrb::invalid_argument- currently for dimension mismatch, Why not grb::invalid_dimensions