feat: add option to force use of custom futex implementation (#58)

Change

- add the option `FUTEX_CUSTOM` to force futex.h to rely on user
defined `vfutex_wait` and `vfutex_wake`. That was already the case for
unknown OS targets (eg, HMOS). With `FUTEX_CUSTOM` defined, the user can
bring their own `vfutex_` implementation on Linux.

----
Signed-off-by: Diogo Behrens <db7@sdf.org>

Author: db7

include/vsync/thread/internal/futex.h

@@ -1,5 +1,5 @@
 /*
- * Copyright (C) Huawei Technologies Co., Ltd. 2024-2025. All rights reserved.
+ * Copyright (C) Huawei Technologies Co., Ltd. 2024-2026. All rights reserved.
  * SPDX-License-Identifier: MIT
  */
 
@@ -9,7 +9,8 @@
  * futex syscalls
  *
  * If the macros are not defined, we mock the futex syscall with a simple
- * spinning mechanism.
+ * spinning mechanism. Define `FUTEX_CUSTOM` to provide `vfutex_wait` and
+ * `vfutex_wake` in user code, even on Linux.
  *
  * @note on linux compile with `-D_GNU_SOURCE`.
  ******************************************************************************/
@@ -25,7 +26,12 @@
     #define FUTEX_USERSPACE
 #endif
 
-#if defined(VSYNC_VERIFICATION) || defined(FUTEX_USERSPACE)
+#if defined(FUTEX_CUSTOM)
+
+void vfutex_wait(vatomic32_t *m, vuint32_t v);
+void vfutex_wake(vatomic32_t *m, vuint32_t v);
+
+#elif defined(VSYNC_VERIFICATION) || defined(FUTEX_USERSPACE)
 
     #if defined(VFUTEX_LIVENESS)
         #include <vsync/thread/internal/futex_mock_liveness.h>

scripts/clang-format.sh

@@ -19,13 +19,19 @@ if [ "${STYLE}" != "" ]; then
     STYLE=":${STYLE}"
 fi
 
+if which clang-format-14 >/dev/null 2>&1; then
+	CLANG_FORMAT=clang-format-14
+else
+	CLANG_FORMAT=clang-format
+fi
+
 # Apply clang-format to all *.h and *.c files in src folder.
 find "$@" \( -name '*.h' -o -name '*.c' -o -name '*.cpp' -o -name '*.hpp' -o -name '*.cxx' \) \
     -not -path '*/build/*' \
     -not -path '*/deps/*' \
     -not -path '*/vatomic/*' \
     -type f \
-    -exec clang-format -style=file${STYLE} -i {} +
+    -exec ${CLANG_FORMAT} -style=file${STYLE} -i {} +
 
 if [ "${SILENT}" != "true" ]; then
     # Display changed files and exit with 1 if there were differences.

test/thread/CMakeLists.txt

@@ -0,0 +1,8 @@
+file(GLOB SRCS *.c)
+foreach(SRC ${SRCS})
+    get_filename_component(TEST ${SRC} NAME_WE)
+
+    add_executable(${TEST} ${SRC})
+    target_link_libraries(${TEST} vsync pthread)
+    v_add_bin_test(NAME ${TEST} COMMAND ${TEST})
+endforeach()

test/thread/custom_futex_override.c

@@ -0,0 +1,43 @@
+/*
+ * Copyright (C) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+ * SPDX-License-Identifier: MIT
+ */
+
+#define FUTEX_CUSTOM
+#include <vsync/thread/internal/futex.h>
+
+static vatomic32_t g_word = VATOMIC_INIT(0);
+static vuint32_t g_wait_count;
+static vuint32_t g_wake_count;
+static vuint32_t g_wait_value;
+static vuint32_t g_wake_value;
+
+void
+vfutex_wait(vatomic32_t *m, vuint32_t v)
+{
+    ASSERT(m == &g_word);
+    g_wait_count++;
+    g_wait_value = v;
+}
+
+void
+vfutex_wake(vatomic32_t *m, vuint32_t v)
+{
+    ASSERT(m == &g_word);
+    g_wake_count++;
+    g_wake_value = v;
+}
+
+int
+main(void)
+{
+    vfutex_wait(&g_word, 7U);
+    vfutex_wake(&g_word, FUTEX_WAKE_ONE);
+
+    ASSERT(g_wait_count == 1U);
+    ASSERT(g_wake_count == 1U);
+    ASSERT(g_wait_value == 7U);
+    ASSERT(g_wake_value == FUTEX_WAKE_ONE);
+
+    return 0;
+}