Implement `VOLK_strerror` #24

New issue

Open

opened 2026-06-24 14:27:00 +00:00 by scossu · 1 comment

scossu commented

2026-06-24 14:27:00 +00:00

Owner

Currently VOLK functions may either return a VOLK_rc type value which is a return code, or another type which is the actual data requested by the caller. In the latter case, it is hard to report precise errors: e.g., by of returning NULL where a new struct handle is expected, which can be detected as an error but does not tell the caller anything about what went wrong. For functions returning size_t, bool, etc. this is even less informative.

Some libraries such as LMDB have chosen to consistently return an rc, and use a pointer value in the function signature to yield new data. This is not practical for this project, as it would make implementation code much more cumbersome to write: e.g. one would have write something as common as

VOLK_Term *lit1 = VOLK_literal_new ("test", VOLK_iriref_new ("https://example.edu/mydatatype"));

thus instead:

VOLK_Term *lit1, *datatype;
VOLK_iriref_new ("https://example.edu/mydatatype", &datatype);
VOLK_literal_new ("test", datatype, &lit1);

As a compromise between being informative, consistent and easy to use, VOLK functions could be divided into two categories:

One that does not yield any data as variables, and return a VOLK_rc type (no change to the ones that already do so);
One that yields usable data, which return the prearranged type on success, and set a global VOLK_errno value on error (in this case the return value would be undefined and should not be used by the caller).

VOLK_strerror should use the same codes already in use.

This systems makes it easy to memorize which functions should be checked for rc, and which for strerror, and can yield precise information about the failure.

Currently VOLK functions may either return a `VOLK_rc` type value which is a return code, or another type which is the actual data requested by the caller. In the latter case, it is hard to report precise errors: e.g., by of returning NULL where a new struct handle is expected, which can be detected as an error but does not tell the caller anything about what went wrong. For functions returning `size_t`, `bool`, etc. this is even less informative. Some libraries such as LMDB have chosen to consistently return an rc, and use a pointer value in the function signature to yield new data. This is not practical for this project, as it would make implementation code much more cumbersome to write: e.g. one would have write something as common as ```c VOLK_Term *lit1 = VOLK_literal_new ("test", VOLK_iriref_new ("https://example.edu/mydatatype")); ``` thus instead: ```c VOLK_Term *lit1, *datatype; VOLK_iriref_new ("https://example.edu/mydatatype", &datatype); VOLK_literal_new ("test", datatype, &lit1); ``` As a compromise between being informative, consistent and easy to use, VOLK functions could be divided into two categories: - One that does not yield any data as variables, and return a `VOLK_rc` type (no change to the ones that already do so); - One that yields usable data, which return the prearranged type on success, and set a global `VOLK_errno` value on error (in this case the return value would be undefined and should not be used by the caller). `VOLK_strerror` should use the same codes already in use. This systems makes it easy to memorize which functions should be checked for rc, and which for strerror, and can yield precise information about the failure.

scossu added the

area/api

normal

feature

labels

2026-06-24 14:27:00 +00:00

scossu commented

2026-06-24 14:45:38 +00:00

Author

Owner

This feature requires two new set of macros in the RCCK, PRCCK, etc. family to check for VOLK_strerror instead of the function rc. To avoid the proliferation of these macros, which are already hard to memorize, some consolidation may be beneficial, e.g.:

Remove CALLOC_GUARD and MALLOC_GUARD (already inflexible) and replace their calls with malloc / calloc + NLRCCK or NLNL
[...]

This feature requires two new set of macros in the `RCCK`, `PRCCK`, etc. family to check for `VOLK_strerror` instead of the function rc. To avoid the proliferation of these macros, which are already hard to memorize, some consolidation may be beneficial, e.g.: - Remove `CALLOC_GUARD` and `MALLOC_GUARD` (already inflexible) and replace their calls with malloc / calloc + NLRCCK or NLNL - [...]