Improve error reporting by storing the last error message, uniform exception handling and helper functions

Author: tstenner

include/lsl/common.h

@@ -132,6 +132,8 @@ typedef enum {
 	lsl_internal_error = -4
 } lsl_error_code_t;
 
+/// Return an explanation for the last error
+extern LIBLSL_C_API const char *lsl_last_error(void);
 
 /**
  * LSL version the binary was compiled against

include/lsl_cpp.h

@@ -180,7 +180,9 @@ class stream_info {
 		double nominal_srate = IRREGULAR_RATE, channel_format_t channel_format = cf_float32,
 		const std::string &source_id = std::string())
 		: obj(lsl_create_streaminfo((name.c_str()), (type.c_str()), channel_count, nominal_srate,
-			  (lsl_channel_format_t)channel_format, (source_id.c_str()))) {}
+			  (lsl_channel_format_t)channel_format, (source_id.c_str()))) {
+		if (obj == nullptr) throw std::invalid_argument(lsl_last_error());
+	}
 	stream_info(lsl_streaminfo handle) : obj(handle) {}
 
 

src/common.cpp

@@ -12,7 +12,10 @@
 #pragma comment(lib, "winmm.lib")
 #endif
 
+char last_error[512];
+
 extern "C" {
+
 LIBLSL_C_API int32_t lsl_protocol_version() {
 	return lsl::api_config::get_instance()->use_protocol_version();
 }
@@ -28,6 +31,8 @@ LIBLSL_C_API double lsl_local_clock() {
 LIBLSL_C_API void lsl_destroy_string(char *s) {
 	if (s) free(s);
 }
+
+LIBLSL_C_API const char *lsl_last_error(void) { return last_error; }
 }
 
 // === implementation of misc functions ===

src/common.h

@@ -31,6 +31,8 @@ extern "C" {
 	"Please do not compile this with a lslboost version older than 1.45 because the library would otherwise not be protocol-compatible with builds using other versions."
 #endif
 
+extern char last_error[512];
+
 // the highest supported protocol version
 // * 100 is the original version, supported by library versions 1.00+
 // * 110 is an alternative protocol that improves throughput, supported by library versions 1.10+

src/lsl_c_api_helpers.hpp

@@ -0,0 +1,72 @@
+#pragma once
+
+#include "common.h"
+#include <cstdint>
+#include <cstring>
+
+/// Helper for LSL_CATCH_EXCEPTIONS
+#define _LSLCATCH(Exception, code)                                                                 \
+	catch (Exception & e) {                                                                        \
+		if (ec) *ec = code;                                                                        \
+		strncpy(last_error, e.what(), sizeof(last_error) - 1);                                     \
+	}
+
+/**
+ * C API exception helper.
+ *
+ * Inserts `catch()` statements for stl and liblsl exceptions and sets the
+ * variable pointed to by `ec` to the corresponding value from
+ * `lsl_error_code_t` and copies the error message to `last_error`.
+ *
+ * If you're trying to create a function `lsl_foobar_do_bar` that wraps the `FooBar`'s member
+ * function `do_bar`, this allows you to write
+ *
+ * ```
+ * function lsl_foobar_do_bar(lsl_foobar obj, int x, double y, int32_t *ec) {
+ *	try {
+ *		obj->do_bar(x, y);
+ *	} CATCH_LSL_EXCEPTIONS
+ * }
+ * ```
+ *
+ * instead of
+ *
+ * ```
+ * function lsl_foobar_do_bar(lsl_foobar obj, int x, double y, int32_t *ec) {
+ *	if(ec) *ec = lsl_no_error;
+ *	try {
+ *		return obj->do_bar(x, y);
+ *	}
+ *	catch(Ex1 &e) {
+ *		if(ec) *ec = lsl_error1;
+ *		strncpy(last_error, e.what(), sizeof(last_error-1);
+  *	}
+ *	catch(Ex2 &) {
+ *		if(ec) *ec = lsl_error2;
+ * 		strncpy(last_error, e.what(), sizeof(last_error-1);
+ *	}
+ *	// etc.
+ *	return 0;
+ * }
+ * ```
+ */
+#define LSL_CATCH_EXCEPTIONS                                                                \
+	_LSLCATCH(lsl::timeout_error, lsl_timeout_error)                                        \
+	_LSLCATCH(lsl::lost_error, lsl_lost_error)                                              \
+	_LSLCATCH(std::range_error, lsl_argument_error)                                         \
+	_LSLCATCH(std::invalid_argument, lsl_argument_error)                                    \
+	_LSLCATCH(std::exception, lsl_internal_error)
+
+/// add a dummy variable to capture the error code
+#define LSL_DEFAULT_EC int32_t dummy_ec = lsl_no_error, *ec = &dummy_ec
+
+/// Try to create a new object of type T and return a pointer to it
+/// or nullptr if an exception occured.
+template<class Type, typename... T> Type* create_object_noexcept(T&&... args) noexcept {
+	LSL_DEFAULT_EC;
+	try {
+		return new Type(std::forward<T>(args)...);
+	}
+	LSL_CATCH_EXCEPTIONS
+	return nullptr;
+}

src/lsl_inlet_c.cpp

@@ -1,3 +1,4 @@
+#include "lsl_c_api_helpers.hpp"
 #include "stream_inlet_impl.h"
 
 extern "C" {
@@ -9,20 +10,9 @@ using namespace lsl;
 
 LIBLSL_C_API lsl_inlet lsl_create_inlet(
 	lsl_streaminfo info, int32_t max_buflen, int32_t max_chunklen, int32_t recover) {
-	try {
-		stream_info_impl *infoimpl = info;
-		lsl_inlet result = new stream_inlet_impl(*infoimpl,
-			infoimpl->nominal_srate() ? (int)(infoimpl->nominal_srate() * max_buflen)
-									  : max_buflen * 100,
-			max_chunklen, recover != 0);
-		return result;
-	} catch (std::invalid_argument &e) {
-		LOG_F(WARNING, "Error during construction of a stream_inlet: %s", e.what());
-		return nullptr;
-	} catch (std::exception &e) {
-		LOG_F(ERROR, "Unexpected error in %s: %s", __func__, e.what());
-		return nullptr;
-	}
+	return create_object_noexcept<stream_inlet_impl>(*info,
+		info->nominal_srate() ? (int)(info->nominal_srate() * max_buflen) : max_buflen * 100,
+		max_chunklen, recover != 0);
 }
 
 LIBLSL_C_API void lsl_destroy_inlet(lsl_inlet in) {
@@ -32,18 +22,7 @@ LIBLSL_C_API void lsl_destroy_inlet(lsl_inlet in) {
 }
 
 LIBLSL_C_API lsl_streaminfo lsl_get_fullinfo(lsl_inlet in, double timeout, int32_t *ec) {
-	if (ec) *ec = lsl_no_error;
-	try {
-		return new stream_info_impl(in->info(timeout));
-	} catch (timeout_error &) {
-		if (ec) *ec = lsl_timeout_error;
-	} catch (lost_error &) {
-		if (ec) *ec = lsl_lost_error;
-	} catch (std::exception &e) {
-		LOG_F(ERROR, "Unexpected error in %s: %s", __func__, e.what());
-		if (ec) *ec = lsl_internal_error;
-	}
-	return nullptr;
+	return create_object_noexcept<stream_info_impl>(in->info(timeout));
 }
 
 LIBLSL_C_API void lsl_open_stream(lsl_inlet in, double timeout, int32_t *ec) {

src/lsl_outlet_c.cpp

@@ -1,3 +1,4 @@
+#include "lsl_c_api_helpers.hpp"
 #include "stream_outlet_impl.h"
 
 #pragma warning(disable : 4800)
@@ -12,16 +13,8 @@ using namespace lsl;
 // boilerplate wrapper code
 LIBLSL_C_API lsl_outlet lsl_create_outlet(
 	lsl_streaminfo info, int32_t chunk_size, int32_t max_buffered) {
-	try {
-		stream_info_impl *infoimpl = info;
-		lsl_outlet result = new stream_outlet_impl(*infoimpl, chunk_size,
-			infoimpl->nominal_srate() ? (int)(infoimpl->nominal_srate() * max_buffered)
-									  : max_buffered * 100);
-		return result;
-	} catch (std::exception &e) {
-		LOG_F(WARNING, "Unexpected error during construction of stream outlet: %s", e.what());
-		return nullptr;
-	}
+	return create_object_noexcept<stream_outlet_impl>(*info, chunk_size,
+		info->nominal_srate() ? (int)(info->nominal_srate() * max_buffered) : max_buffered * 100);
 }
 
 LIBLSL_C_API void lsl_destroy_outlet(lsl_outlet out) {
@@ -111,52 +104,20 @@ LIBLSL_C_API int32_t lsl_push_sample_ctp(
 }
 
 LIBLSL_C_API int32_t lsl_push_sample_v(lsl_outlet out, const void *data) {
-	try {
-		out->push_numeric_raw(data);
-		return lsl_no_error;
-	} catch (std::range_error &e) {
-		LOG_F(WARNING, "Error during push_sample: %s", e.what());
-		return lsl_argument_error;
-	} catch (std::invalid_argument &e) {
-		LOG_F(WARNING, "Error during push_sample: %s", e.what());
-		return lsl_argument_error;
-	} catch (std::exception &e) {
-		LOG_F(WARNING, "Unexpected error during push_sample: %s", e.what());
-		return lsl_internal_error;
-	}
+	return lsl_push_sample_vtp(out, data, 0.0, true);
 }
 
 LIBLSL_C_API int32_t lsl_push_sample_vt(lsl_outlet out, const void *data, double timestamp) {
-	try {
-		out->push_numeric_raw(data, timestamp);
-		return lsl_no_error;
-	} catch (std::range_error &e) {
-		LOG_F(WARNING, "Error during push_sample: %s", e.what());
-		return lsl_argument_error;
-	} catch (std::invalid_argument &e) {
-		LOG_F(WARNING, "Error during push_sample: %s", e.what());
-		return lsl_argument_error;
-	} catch (std::exception &e) {
-		LOG_F(WARNING, "Unexpected error during push_sample: %s", e.what());
-		return lsl_internal_error;
-	}
+	return lsl_push_sample_vtp(out, data, timestamp, true);
 }
 
 LIBLSL_C_API int32_t lsl_push_sample_vtp(
 	lsl_outlet out, const void *data, double timestamp, int32_t pushthrough) {
+	LSL_DEFAULT_EC;
 	try {
 		out->push_numeric_raw(data, timestamp, pushthrough != 0);
-		return lsl_no_error;
-	} catch (std::range_error &e) {
-		LOG_F(WARNING, "Error during push_sample: %s", e.what());
-		return lsl_argument_error;
-	} catch (std::invalid_argument &e) {
-		LOG_F(WARNING, "Error during push_sample: %s", e.what());
-		return lsl_argument_error;
-	} catch (std::exception &e) {
-		LOG_F(WARNING, "Unexpected error during push_sample: %s", e.what());
-		return lsl_internal_error;
-	}
+	} LSL_CATCH_EXCEPTIONS
+	return *ec;
 }
 
 LIBLSL_C_API int32_t lsl_push_sample_str(lsl_outlet out, const char **data) {
@@ -367,21 +328,14 @@ LIBLSL_C_API int32_t lsl_push_chunk_strt(
 
 LIBLSL_C_API int32_t lsl_push_chunk_strtp(lsl_outlet out, const char **data,
 	unsigned long data_elements, double timestamp, int32_t pushthrough) {
+	LSL_DEFAULT_EC;
 	try {
 		std::vector<std::string> tmp;
 		for (unsigned long k = 0; k < data_elements; k++) tmp.emplace_back(data[k]);
 		if (data_elements) out->push_chunk_multiplexed(&tmp[0], tmp.size(), timestamp, pushthrough);
-		return lsl_no_error;
-	} catch (std::range_error &e) {
-		LOG_F(WARNING, "Error during push_chunk: %s", e.what());
-		return lsl_argument_error;
-	} catch (std::invalid_argument &e) {
-		LOG_F(WARNING, "Error during push_chunk: %s", e.what());
-		return lsl_argument_error;
-	} catch (std::exception &e) {
-		LOG_F(WARNING, "Unexpected error during push_chunk: %s", e.what());
-		return lsl_internal_error;
 	}
+	LSL_CATCH_EXCEPTIONS
+	return *ec;
 }
 
 LIBLSL_C_API int32_t lsl_push_chunk_strtn(
@@ -391,23 +345,16 @@ LIBLSL_C_API int32_t lsl_push_chunk_strtn(
 
 LIBLSL_C_API int32_t lsl_push_chunk_strtnp(lsl_outlet out, const char **data,
 	unsigned long data_elements, const double *timestamps, int32_t pushthrough) {
+	LSL_DEFAULT_EC;
 	try {
 		if (data_elements) {
 			std::vector<std::string> tmp;
 			for (unsigned long k = 0; k < data_elements; k++) tmp.emplace_back(data[k]);
 			out->push_chunk_multiplexed_noexcept(&tmp[0], timestamps, data_elements, pushthrough);
 		}
-		return lsl_no_error;
-	} catch (std::range_error &e) {
-		LOG_F(WARNING, "Error during push_chunk: %s", e.what());
-		return lsl_argument_error;
-	} catch (std::invalid_argument &e) {
-		LOG_F(WARNING, "Error during push_chunk: %s", e.what());
-		return lsl_argument_error;
-	} catch (std::exception &e) {
-		LOG_F(WARNING, "Unexpected error during push_chunk: %s", e.what());
-		return lsl_internal_error;
 	}
+	LSL_CATCH_EXCEPTIONS
+	return *ec;
 }
 
 LIBLSL_C_API int32_t lsl_push_chunk_buf(
@@ -422,21 +369,14 @@ LIBLSL_C_API int32_t lsl_push_chunk_buft(lsl_outlet out, const char **data, cons
 
 LIBLSL_C_API int32_t lsl_push_chunk_buftp(lsl_outlet out, const char **data,
 	const uint32_t *lengths, unsigned long data_elements, double timestamp, int32_t pushthrough) {
+	LSL_DEFAULT_EC;
 	try {
 		std::vector<std::string> tmp;
 		for (unsigned long k = 0; k < data_elements; k++) tmp.emplace_back(data[k], lengths[k]);
 		if (data_elements) out->push_chunk_multiplexed(&tmp[0], tmp.size(), timestamp, pushthrough);
-		return lsl_no_error;
-	} catch (std::range_error &e) {
-		LOG_F(WARNING, "Error during push_chunk: %s", e.what());
-		return lsl_argument_error;
-	} catch (std::invalid_argument &e) {
-		LOG_F(WARNING, "Error during push_chunk: %s", e.what());
-		return lsl_argument_error;
-	} catch (std::exception &e) {
-		LOG_F(WARNING, "Unexpected error during push_chunk: %s", e.what());
-		return lsl_internal_error;
 	}
+	LSL_CATCH_EXCEPTIONS
+	return *ec;
 }
 
 LIBLSL_C_API int32_t lsl_push_chunk_buftn(lsl_outlet out, const char **data,
@@ -447,24 +387,17 @@ LIBLSL_C_API int32_t lsl_push_chunk_buftn(lsl_outlet out, const char **data,
 LIBLSL_C_API int32_t lsl_push_chunk_buftnp(lsl_outlet out, const char **data,
 	const uint32_t *lengths, unsigned long data_elements, const double *timestamps,
 	int32_t pushthrough) {
+	LSL_DEFAULT_EC;
 	try {
 		if (data_elements) {
 			std::vector<std::string> tmp;
 			for (unsigned long k = 0; k < data_elements; k++) tmp.emplace_back(data[k], lengths[k]);
 			out->push_chunk_multiplexed(
 				&tmp[0], timestamps, (std::size_t)data_elements, pushthrough);
 		}
-		return lsl_no_error;
-	} catch (std::range_error &e) {
-		LOG_F(WARNING, "Error during push_chunk: %s", e.what());
-		return lsl_argument_error;
-	} catch (std::invalid_argument &e) {
-		LOG_F(WARNING, "Error during push_chunk: %s", e.what());
-		return lsl_argument_error;
-	} catch (std::exception &e) {
-		LOG_F(WARNING, "Unexpected error during push_chunk: %s", e.what());
-		return lsl_internal_error;
 	}
+	LSL_CATCH_EXCEPTIONS
+	return *ec;
 }
 
 LIBLSL_C_API int32_t lsl_have_consumers(lsl_outlet out) {
@@ -486,11 +419,6 @@ LIBLSL_C_API int32_t lsl_wait_for_consumers(lsl_outlet out, double timeout) {
 }
 
 LIBLSL_C_API lsl_streaminfo lsl_get_info(lsl_outlet out) {
-	try {
-		return new stream_info_impl(out->info());
-	} catch (std::exception &e) {
-		LOG_F(WARNING, "Unexpected error in lsl_get_info: %s", e.what());
-		return nullptr;
-	}
+	return create_object_noexcept<stream_info_impl>(out->info());
 }
 }