✨ ztdc_thrd_ignore_all_attrs_errors and ztdc_thrd_stop_on_attr_error functions for use!

ThePhD · ThePhD · commit d10a2e022616 · 2025-07-02T21:56:28.000-04:00
diff --git a/documentation/source/api.rst b/documentation/source/api.rst
@@ -57,11 +57,15 @@ There's only a limited number of APIs to document, as the rest is covered by the
 
 
 
-``ztdc_thrd_attr_err_func_t`` function type
--------------------------------------------
+``ztdc_thrd_attr_err_func_t`` function type and functions
+---------------------------------------------------------
 
 .. doxygentypedef:: ztdc_thrd_attr_err_func_t
 
+.. doxygenfunction:: ztdc_thrd_ignore_all_attr_errors
+
+.. doxygenfunction:: ztdc_thrd_stop_on_attr_error
+
 
 
 ``ztdc_thrd_create_attrs_err`` function
diff --git a/examples/source/custom_attribute_arbitrary_fail.c b/examples/source/custom_attribute_arbitrary_fail.c
@@ -77,7 +77,7 @@ inline static int thread_main(void* arg) {
 	                   // attribute function `thread_custom_on_origin_attr`.
 }
 
-inline static int thread_attr_passthrough(const ztdc_thrd_attr_kind* kind, int err, void* userdata) {
+inline static int thread_attr_check_error(const ztdc_thrd_attr_kind* kind, int err, void* userdata) {
 	(void)kind;
 	(void)userdata;
 
@@ -111,7 +111,7 @@ int main(void) {
 	};
 
 	int create_err0 = ztdc_thrd_create_attrs_err(
-	     &t0, thread_main, NULL, ztdc_c_array_size(attrs), attrs, thread_attr_passthrough, NULL);
+	     &t0, thread_main, NULL, ztdc_c_array_size(attrs), attrs, thread_attr_check_error, NULL);
 	// creation error is always identical to whatever the error function returns, if necessary
 	ZTD_ASSERT(create_err0 == thrd_timedout);
 	ZTD_ASSERT(accumulator == EXPECTED_ACCUMULATION_VALUE);
diff --git a/examples/source/custom_attribute_guaranteed_order.c b/examples/source/custom_attribute_guaranteed_order.c
@@ -96,7 +96,7 @@ int main(void) {
 	};
 
 	int create_err0 = ztdc_thrd_create_attrs_err(
-	     &t0, thread_main, &accumulator, ztdc_c_array_size(attrs), attrs, thread_attr_passthrough, NULL);
+	     &t0, thread_main, &accumulator, ztdc_c_array_size(attrs), attrs, ztdc_thrd_stop_on_attr_error, NULL);
 	ZTD_ASSERT(create_err0 == thrd_success);
 
 	int res0 = 0;
diff --git a/examples/source/custom_attribute_name.c b/examples/source/custom_attribute_name.c
@@ -48,12 +48,13 @@
 
 enum { EXPECTED_MARKER_VALUE = 32 };
 
-inline static int thrd_custom_name(thrd_t t, ztdc_thrd_native_handle_t t_handle, ztdc_thrd_id_t t_id, void* userdata) {
+inline static int thread_custom_name_attr(
+     thrd_t t, ztdc_thrd_native_handle_t t_handle, ztdc_thrd_id_t t_id, void* userdata) {
 	(void)t;
 	(void)t_handle;
 	(void)t_id;
 	int custom_marker = *((const int*)userdata);
-	printf("thrd_custom_name called with custom maker: %d\n", custom_marker);
+	printf("thread_custom_name_attr called with custom marker: %d\n", custom_marker);
 	if (custom_marker != EXPECTED_MARKER_VALUE) {
 		return thrd_error;
 	}
@@ -85,7 +86,7 @@ int main(void) {
 
 	const ztdc_thrd_attr_custom_on_new custom_attr = {
 		.kind     = ztdc_thrd_attr_kind_custom_on_new,
-		.func     = thrd_custom_name,
+		.func     = thread_custom_name_attr,
 		.userdata = &custom_marker,
 	};
 
diff --git a/include/ztd/thread/threads.h b/include/ztd/thread/threads.h
@@ -139,6 +139,29 @@ int thrd_sleep(const struct timespec* __duration, struct timespec* __remaining);
 typedef int(ztdc_thrd_attr_err_func_t)(const ztdc_thrd_attr_kind* __kind, int __err, void* __userdata);
 
 
+ZTD_USE(ZTD_C_LANGUAGE_LINKAGE)
+ZTD_USE(ZTD_THREAD_API_LINKAGE)
+/// @brief A ztdc_thrd_attr_err_func_t that returns `thrd_success` unconditionally.
+///
+/// @param[in] __kind The thread attribute kind. Ignored.
+/// @param[in] __err The error that occurred. Ignored.
+/// @param[in] __userdata A pointer to some userdata, or null. Ignored.
+///
+/// @return `thrd_success`.
+int ztdc_thrd_ignore_all_attr_errors(const ztdc_thrd_attr_kind* __kind, int __err, void* __userdata);
+
+ZTD_USE(ZTD_C_LANGUAGE_LINKAGE)
+ZTD_USE(ZTD_THREAD_API_LINKAGE)
+/// @brief A ztdc_thrd_attr_err_func_t that returns the error it was called with unconditionally. Has the effect of
+/// stopping on the first thread attribute that errors.
+///
+/// @param[in] __kind The thread attribute kind. Ignored.
+/// @param[in] __err The error that occurred.
+/// @param[in] __userdata A pointer to some userdata, or null. Ignored.
+///
+/// @return `__err`.
+int ztdc_thrd_stop_on_attr_error(const ztdc_thrd_attr_kind* __kind, int __err, void* __userdata);
+
 ZTD_USE(ZTD_C_LANGUAGE_LINKAGE)
 ZTD_USE(ZTD_THREAD_API_LINKAGE)
 /// @brief Starts a thread and configures that thread with the given thread attributes, if any. Any failure in the
diff --git a/source/ztd/thread/threads.c b/source/ztd/thread/threads.c
@@ -58,19 +58,29 @@ const ztdc_thrd_id_t ztdc_thrd_null_id =
 #endif
      ;
 
-inline static int __ztdc_ignore_all_thrd_errors(const ztdc_thrd_attr_kind* __kind, int __err, void* __userdata) {
+ZTD_USE(ZTD_C_LANGUAGE_LINKAGE)
+ZTD_USE(ZTD_THREAD_API_LINKAGE)
+int ztdc_thrd_ignore_all_attr_errors(const ztdc_thrd_attr_kind* __kind, int __err, void* __userdata) {
 	(void)__kind;
 	(void)__err;
 	(void)__userdata;
 	return thrd_success;
 }
 
+ZTD_USE(ZTD_C_LANGUAGE_LINKAGE)
+ZTD_USE(ZTD_THREAD_API_LINKAGE)
+int ztdc_thrd_stop_on_attr_error(const ztdc_thrd_attr_kind* __kind, int __err, void* __userdata) {
+	(void)__kind;
+	(void)__userdata;
+	return __err;
+}
+
 ZTD_USE(ZTD_C_LANGUAGE_LINKAGE)
 ZTD_USE(ZTD_THREAD_API_LINKAGE)
 int ztdc_thrd_create_attrs(
      thrd_t* __thr, thrd_start_t __func, void* __func_arg, size_t __attrs_size, const ztdc_thrd_attr_kind** __attrs) {
 	return ztdc_thrd_create_attrs_err(
-	     __thr, __func, __func_arg, __attrs_size, __attrs, __ztdc_ignore_all_thrd_errors, NULL);
+	     __thr, __func, __func_arg, __attrs_size, __attrs, ztdc_thrd_ignore_all_attr_errors, NULL);
 }
 
 ZTD_USE(ZTD_C_LANGUAGE_LINKAGE)
@@ -90,7 +100,7 @@ int ztdc_thrd_create_attrs_err(thrd_t* __thr, thrd_start_t __func, void* __func_
 		return thrd_success;
 	}
 	if (!__attr_err_func) {
-		__attr_err_func = __ztdc_ignore_all_thrd_errors;
+		__attr_err_func = ztdc_thrd_ignore_all_attr_errors;
 	}
 #if ZTD_IS_ON(ZTD_THREAD_PTHREAD_BASED)
 	return __ztdc_pthreads_thrd_create_attrs_err(
diff --git a/source/ztd/thread/threads.windows.c b/source/ztd/thread/threads.windows.c
@@ -508,7 +508,7 @@ int __ztdc_win32_thrd_create_attrs_err(thrd_t* __thr, thrd_start_t __func, void*
 			// store to invoke later (on the new thread, if success)
 			ztdc_thrd_attr_custom_on_new* __attr        = (ztdc_thrd_attr_custom_on_new*)__attr_kind;
 			__trampoline_userdata->__custom_on_new_attr = __attr;
-		}
+		} break;
 		default:
 			// unrecognized attribute
 			__attr_err = thrd_error;
@@ -518,7 +518,7 @@ int __ztdc_win32_thrd_create_attrs_err(thrd_t* __thr, thrd_start_t __func, void*
 			int __attr_err_res = __attr_err_func(__attr_kind, __attr_err, __attr_err_func_arg);
 			if (__attr_err_res != thrd_success) {
 				free(__trampoline_userdata);
-				return thrd_success;
+				return __attr_err_res;
 			}
 		}
 	}
@@ -661,32 +661,34 @@ int __ztdc_win32_thrd_create_attrs_err(thrd_t* __thr, thrd_start_t __func, void*
 		// spinlock until the thread is started and all internal work is okay.
 	}
 	// return any from-thread failures and bail if necessary
-	int __post_thread_start_results = __sync_result;
-	if (__post_thread_start_results != thrd_success) {
-		__post_thread_start_results = __attr_err_func(__sync_kind, __post_thread_start_results, __attr_err_func_arg);
-		__sync_result               = __post_thread_start_results;
+	int __thread_setup_result = __sync_result;
+	if (__thread_setup_result != thrd_success) {
+		int __processed_thread_setup_result
+		     = __attr_err_func(__sync_kind, __thread_setup_result, __attr_err_func_arg);
+		__sync_result = __processed_thread_setup_result;
 		// send back the result to the thread so it knows to either go or quit
 		atomic_store(&__sync_still_ok, false);
-		if (__post_thread_start_results != thrd_success) {
+		if (__processed_thread_setup_result != thrd_success) {
 			CloseHandle(*__handle);
 			*__thr = __original_thr;
-			return __post_thread_start_results;
+			return __processed_thread_setup_result;
 		}
 	}
 	// if all goes well, then we check out origin custom error bit
 	// invoke our origin custom thread work if possible
 	if (__custom_on_origin_attr) {
-		int __custom_err = __custom_on_origin_attr->func(*__thr, *__ztdc_win32_handle_ptr(__thr),
+		int __custom_origin_err = __custom_on_origin_attr->func(*__thr, *__ztdc_win32_handle_ptr(__thr),
 		     *__ztdc_win32_handle_id(__thr), __custom_on_origin_attr->userdata);
-		if (__custom_err != thrd_success) {
-			__custom_err  = __attr_err_func(__sync_kind, __custom_err, __attr_err_func_arg);
-			__sync_result = __post_thread_start_results;
+		if (__custom_origin_err != thrd_success) {
+			int __processed_custom_origin_err
+			     = __attr_err_func(__sync_kind, __custom_origin_err, __attr_err_func_arg);
+			__sync_result = __processed_custom_origin_err;
 			// send back the result to the thread so it knows to either go or quit
 			atomic_store(&__sync_still_ok, false);
-			if (__post_thread_start_results != thrd_success) {
+			if (__processed_custom_origin_err != thrd_success) {
 				CloseHandle(*__handle);
 				*__thr = __original_thr;
-				return __post_thread_start_results;
+				return __processed_custom_origin_err;
 			}
 		}
 	}
