The GrB_PANIC error is an extreme error code. Lines 731-733 of the current draft states (emphasis added):
If a GraphBLAS method returns with a GrB_PANIC execution error, no guarantees can be made about
the state of any program data.
However, table 3.13 calls GrB_PANIC, "unknown internal error", which is not as extreme. Table 3.13 should define it as "Unrecoverable error".
There should be two error codes. GrB_PANIC should be reserved for totally unrecoverable errors. No GraphBLAS method should be required to return a GrB_PANIC.
There should be a new error code that is entirely implementation defined, say GrB_OTHER_ERROR, that means "implementation-defined error". If a library returns such an error, it must document what it means for that particular method.
I would use this GrB_OTHER_ERROR in several cases:
GrB_Matrix_serialize fails when calling an external compression library (LZ4 in my case). This method "shouldn't" fail because I pre-allocate the memory it uses, and I give it exactly the upper bound it asks me for. But if I'm wrong, it might fail anyway, and return an error code.
GrB_Matrix_build might be passed GrB_ALL for the indices. I return GrB_INVALID_VALUE currently.
My diagnostic "burble" might fail in printf, so if I get a printf error I return GrB_INVALID_VALUE. That doesn't fit but it's the best error code I can think of. Likewise, when GxB_print is called to pretty-print a matrix.
GrB_Descriptor_set tries to modify a built-in descriptor like GrB_DESC_S. The spec is silent on whether this is allowed. I don't allow it, and I return GrB_INVALID_VALUE if they do. That seems odd to me but it's the best error code I can think of.
GxB_Matrix_export_FullC (my method) is called on a matrix that does not have a full structure. I refuse to export the matrix because there is no definition of the value of an "implied zero" or "entry not in the structure". I return GrB_INVALID_VALUE but this seems very strange to me.
Microsoft Visual Studio does not support variable-length arrays allocated on the stack. I use these extensively for "scalar" temporaries when working with user-defined types. As a result, when this compiler is used, I limit user-defined types to an upper bound of 128 bytes. If GrB_Type_new is called with a sizeof(ctype) > 128, when SuiteSparse:GraphBLAS was compiled with MS Visual Studio, I return GrB_INVALID_VALUE.
There could be more such cases in the future. Rather than shoe-horning these error codes into existing and well-defined GrB error codes, it would be better to have a single error code, GrB_OTHER_ERROR, which is always implementation-defined. It can be used in different ways in different methods, and the library would be required to define its meaning when returned by any given GraphBLAS method.
The GrB_PANIC error is an extreme error code. Lines 731-733 of the current draft states (emphasis added):
However, table 3.13 calls GrB_PANIC, "unknown internal error", which is not as extreme. Table 3.13 should define it as "Unrecoverable error".
There should be two error codes. GrB_PANIC should be reserved for totally unrecoverable errors. No GraphBLAS method should be required to return a GrB_PANIC.
There should be a new error code that is entirely implementation defined, say GrB_OTHER_ERROR, that means "implementation-defined error". If a library returns such an error, it must document what it means for that particular method.
I would use this GrB_OTHER_ERROR in several cases:
There could be more such cases in the future. Rather than shoe-horning these error codes into existing and well-defined GrB error codes, it would be better to have a single error code, GrB_OTHER_ERROR, which is always implementation-defined. It can be used in different ways in different methods, and the library would be required to define its meaning when returned by any given GraphBLAS method.
See also #63.