Add error handling for Binsparse matrix IO functions.

BenBrock · BenBrock · commit b37c626c86ef · 2025-08-18T21:33:33.000-07:00
diff --git a/README.md b/README.md
@@ -18,7 +18,8 @@ This library provides a C interface for reading and writing binsparse matrices.
 #include <binsparse/binsparse.h>
 
 int main(int argc, char** argv) {
-  bsp_matrix_t mat = bsp_read_matrix("chesapeake.bsp.hdf5");
+  bsp_matrix_t mat;
+  bsp_read_matrix(&mat, "chesapeake.bsp.hdf5", NULL);
 
   if (mat.format == BSP_COO) {
     float* values = mat.values.data;
@@ -33,6 +34,7 @@ int main(int argc, char** argv) {
            bsp_get_matrix_format_string(mat.format));
   }
 
+  bsp_destroy_matrix_t(&mat);
   return 0;
 }
 ```
diff --git a/examples/benchmark_read.c b/examples/benchmark_read.c
@@ -79,7 +79,8 @@ int main(int argc, char** argv) {
 
   // If running warm cache experiments, read once to warm cache.
   if (!cold_cache) {
-    bsp_matrix_t mat = bsp_read_matrix(file_name, NULL);
+    bsp_matrix_t mat;
+    BSP_CHECK(bsp_read_matrix(&mat, file_name, NULL));
     bsp_destroy_matrix_t(&mat);
   }
 
@@ -88,7 +89,8 @@ int main(int argc, char** argv) {
       flush_cache();
     }
     double begin = gettime();
-    bsp_matrix_t mat = bsp_read_matrix(file_name, NULL);
+    bsp_matrix_t mat;
+    BSP_CHECK(bsp_read_matrix(&mat, file_name, NULL));
     double end = gettime();
     durations[i] = end - begin;
     nbytes = bsp_matrix_nbytes(mat);
diff --git a/examples/benchmark_read_parallel.c b/examples/benchmark_read_parallel.c
@@ -82,7 +82,8 @@ int main(int argc, char** argv) {
 
   // If running warm cache experiments, read once to warm cache.
   if (!cold_cache) {
-    bsp_matrix_t mat = bsp_read_matrix_parallel(file_name, NULL, num_threads);
+    bsp_matrix_t mat;
+    BSP_CHECK(bsp_read_matrix_parallel(&mat, file_name, NULL, num_threads));
     bsp_destroy_matrix_t(&mat);
   }
 
@@ -92,7 +93,8 @@ int main(int argc, char** argv) {
     }
     fflush(stdout);
     double begin = gettime();
-    bsp_matrix_t mat = bsp_read_matrix_parallel(file_name, NULL, num_threads);
+    bsp_matrix_t mat;
+    BSP_CHECK(bsp_read_matrix_parallel(&mat, file_name, NULL, num_threads));
     double end = gettime();
     durations[i] = end - begin;
     nbytes = bsp_matrix_nbytes(mat);
diff --git a/examples/benchmark_write.c b/examples/benchmark_write.c
@@ -97,7 +97,8 @@ int main(int argc, char** argv) {
 
   double durations[num_trials];
 
-  bsp_matrix_t mat = bsp_read_matrix(file_name, NULL);
+  bsp_matrix_t mat;
+  BSP_CHECK(bsp_read_matrix(&mat, file_name, NULL));
   size_t nbytes = bsp_matrix_nbytes(mat);
 
   char output_filename[2048];
@@ -124,7 +125,8 @@ int main(int argc, char** argv) {
     printf("Writing to file %s\n", output_filename);
 
     double begin = gettime();
-    bsp_write_matrix(output_filename, mat, NULL, NULL, compression_level);
+    BSP_CHECK(
+        bsp_write_matrix(output_filename, mat, NULL, NULL, compression_level));
 
     if (flush_each_write) {
       flush_writes();
diff --git a/examples/bsp2mtx.c b/examples/bsp2mtx.c
@@ -19,8 +19,9 @@ int main(int argc, char** argv) {
   char* output_fname = argv[2];
 
   printf(" === Reading file... ===\n");
-  bsp_matrix_t matrix = bsp_read_matrix(input_fname, NULL);
-  printf(" === Done writing. ===\n");
+  bsp_matrix_t matrix;
+  BSP_CHECK(bsp_read_matrix(&matrix, input_fname, NULL));
+  printf(" === Done reading. ===\n");
   if (matrix.format != BSP_COO) {
     matrix = bsp_convert_matrix(matrix, BSP_COO);
   }
diff --git a/examples/check_equivalence.c b/examples/check_equivalence.c
@@ -110,8 +110,9 @@ int main(int argc, char** argv) {
   printf("Matrix 2: %s and %s\n", info2.fname,
          (info2.dataset == NULL) ? "root" : info2.dataset);
 
-  bsp_matrix_t matrix1 = bsp_read_matrix(info1.fname, info1.dataset);
-  bsp_matrix_t matrix2 = bsp_read_matrix(info2.fname, info2.dataset);
+  bsp_matrix_t matrix1, matrix2;
+  BSP_CHECK(bsp_read_matrix(&matrix1, info1.fname, info1.dataset));
+  BSP_CHECK(bsp_read_matrix(&matrix2, info2.fname, info2.dataset));
 
   bool perform_suitesparse_declamping = true;
   if (perform_suitesparse_declamping &&
diff --git a/examples/check_equivalence_parallel.c b/examples/check_equivalence_parallel.c
@@ -117,9 +117,10 @@ int main(int argc, char** argv) {
 
   fflush(stdout);
 
-  bsp_matrix_t matrix1 = bsp_read_matrix(info1.fname, info1.dataset);
-  bsp_matrix_t matrix2 =
-      bsp_read_matrix_parallel(info2.fname, info2.dataset, num_threads);
+  bsp_matrix_t matrix1, matrix2;
+  BSP_CHECK(bsp_read_matrix(&matrix1, info1.fname, info1.dataset));
+  BSP_CHECK(bsp_read_matrix_parallel(&matrix2, info2.fname, info2.dataset,
+                                     num_threads));
 
   bool perform_suitesparse_declamping = true;
   if (perform_suitesparse_declamping &&
diff --git a/examples/mtx2bsp.c b/examples/mtx2bsp.c
@@ -163,8 +163,8 @@ int main(int argc, char** argv) {
 
   printf(" === Writing to %s... ===\n", output_fname);
   begin = gettime();
-  bsp_write_matrix(output_fname, matrix, group_name, user_json,
-                   compression_level);
+  BSP_CHECK(bsp_write_matrix(output_fname, matrix, group_name, user_json,
+                             compression_level));
   end = gettime();
   duration = end - begin;
   printf("%lf seconds writing Binsparse file...\n", duration);
diff --git a/examples/simple_matrix_read.c b/examples/simple_matrix_read.c
@@ -9,7 +9,8 @@
 int main(int argc, char** argv) {
   const char* file_name = "test.hdf5";
 
-  bsp_matrix_t mat = bsp_read_matrix(file_name, NULL);
+  bsp_matrix_t mat;
+  BSP_CHECK(bsp_read_matrix(&mat, file_name, NULL));
 
   if (mat.format == BSP_COO) {
     float* values = (float*) mat.values.data;
diff --git a/examples/simple_matrix_write.c b/examples/simple_matrix_write.c
@@ -21,7 +21,7 @@ int main(int argc, char** argv) {
     printf("%d, %d: %f\n", rowind[i], colind[i], values[i]);
   }
 
-  bsp_write_matrix("test.hdf5", mat, NULL, NULL, 9);
+  BSP_CHECK(bsp_write_matrix("test.hdf5", mat, NULL, NULL, 9));
 
   return 0;
 }
diff --git a/examples/simple_read.c b/examples/simple_read.c
@@ -12,12 +12,7 @@ int main(int argc, char** argv) {
   hid_t f = H5Fopen(file_name, H5F_ACC_RDWR, H5P_DEFAULT);
 
   bsp_array_t array;
-  bsp_error_t error = bsp_read_array(&array, f, "test");
-  if (error != BSP_SUCCESS) {
-    printf("Error reading array: %s\n", bsp_get_error_string(error));
-    H5Fclose(f);
-    return 1;
-  }
+  BSP_CHECK(bsp_read_array(&array, f, "test"));
 
   int* values = (int*) array.data;
 
diff --git a/include/binsparse/error.h b/include/binsparse/error.h
@@ -6,6 +6,9 @@
 
 #pragma once
 
+#include <stdio.h>
+#include <stdlib.h>
+
 typedef enum bsp_error_t {
   BSP_SUCCESS = 0,
 
@@ -60,3 +63,21 @@ static inline const char* bsp_get_error_string(bsp_error_t error) {
     return "Unknown error";
   }
 }
+
+/**
+ * BSP_CHECK macro - checks if a bsp_error_t is BSP_SUCCESS.
+ * If not, prints file, line number, and error message, then aborts.
+ *
+ * Usage: BSP_CHECK(bsp_read_matrix(&matrix, "file.hdf5", NULL));
+ *
+ * @param call The function call that returns a bsp_error_t
+ */
+#define BSP_CHECK(call)                                                        \
+  do {                                                                         \
+    bsp_error_t _bsp_error = (call);                                           \
+    if (_bsp_error != BSP_SUCCESS) {                                           \
+      fprintf(stderr, "BSP Error at %s:%d: %s\n", __FILE__, __LINE__,          \
+              bsp_get_error_string(_bsp_error));                               \
+      abort();                                                                 \
+    }                                                                          \
+  } while (0)
diff --git a/include/binsparse/read_matrix.h b/include/binsparse/read_matrix.h
@@ -15,22 +15,26 @@ extern "C" {
 #include <hdf5.h>
 
 #if __STDC_VERSION__ >= 201112L
-bsp_matrix_t bsp_read_matrix_from_group_parallel(hid_t f, int num_threads);
+bsp_error_t bsp_read_matrix_from_group_parallel(bsp_matrix_t* matrix, hid_t f,
+                                                int num_threads);
 #endif
 
-bsp_matrix_t bsp_read_matrix_from_group(hid_t f);
-bsp_matrix_t bsp_read_matrix_from_group_allocator(hid_t f,
-                                                  bsp_allocator_t allocator);
+bsp_error_t bsp_read_matrix_from_group(bsp_matrix_t* matrix, hid_t f);
+bsp_error_t bsp_read_matrix_from_group_allocator(bsp_matrix_t* matrix, hid_t f,
+                                                 bsp_allocator_t allocator);
 #endif
 
 #if __STDC_VERSION__ >= 201112L
-bsp_matrix_t bsp_read_matrix_parallel(const char* file_name, const char* group,
-                                      int num_threads);
+bsp_error_t bsp_read_matrix_parallel(bsp_matrix_t* matrix,
+                                     const char* file_name, const char* group,
+                                     int num_threads);
 #endif
 
-bsp_matrix_t bsp_read_matrix(const char* file_name, const char* group);
-bsp_matrix_t bsp_read_matrix_allocator(const char* file_name, const char* group,
-                                       bsp_allocator_t allocator);
+bsp_error_t bsp_read_matrix(bsp_matrix_t* matrix, const char* file_name,
+                            const char* group);
+bsp_error_t bsp_read_matrix_allocator(bsp_matrix_t* matrix,
+                                      const char* file_name, const char* group,
+                                      bsp_allocator_t allocator);
 
 #ifdef __cplusplus
 }
diff --git a/src/read_matrix.c b/src/read_matrix.c

Original file line number	Diff line number	Diff line change
`@@ -18,7 +18,8 @@ This library provides a C interface for reading and writing binsparse matrices.`
`18`	`18`	`#include <binsparse/binsparse.h>`
`19`	`19`
`20`	`20`	`int main(int argc, char** argv) {`
`21`		`- bsp_matrix_t mat = bsp_read_matrix("chesapeake.bsp.hdf5");`
	`21`	`+ bsp_matrix_t mat;`
	`22`	`+ bsp_read_matrix(&mat, "chesapeake.bsp.hdf5", NULL);`
`22`	`23`
`23`	`24`	`if (mat.format == BSP_COO) {`
`24`	`25`	`float* values = mat.values.data;`
`@@ -33,6 +34,7 @@ int main(int argc, char** argv) {`
`33`	`34`	`bsp_get_matrix_format_string(mat.format));`
`34`	`35`	`}`
`35`	`36`
	`37`	`+ bsp_destroy_matrix_t(&mat);`
`36`	`38`	`return 0;`
`37`	`39`	`}`
`38`	`40`	```
Original file line number	Diff line number	Diff line change
`@@ -21,7 +21,7 @@ int main(int argc, char** argv) {`
`21`	`21`	`printf("%d, %d: %f\n", rowind[i], colind[i], values[i]);`
`22`	`22`	`}`
`23`	`23`
`24`		`- bsp_write_matrix("test.hdf5", mat, NULL, NULL, 9);`
	`24`	`+ BSP_CHECK(bsp_write_matrix("test.hdf5", mat, NULL, NULL, 9));`
`25`	`25`
`26`	`26`	`return 0;`
`27`	`27`	`}`