Add use of Clang __attribute__((nonnull)) in Emscripten system headers. (#16545)

* Add use of Clang  __attribute__((nonnull)) in Emscripten system headers.

* Fix annotation on emscripten_futex_wake

* Remove nonnull on emscripten_fetch_wait

* Fix annotation and tests

* Add use of _Nonnull attribute

* Fix test

* Break up long lines in webgl2_ext.h

* Add notes about null pointers in emmalloc.h

Author: juj

system/include/emscripten/atomic.h

@@ -19,63 +19,63 @@ extern "C" {
 
 // Atomically stores the given value to the memory location, and returns the
 // value that was there prior to the store.
-uint8_t emscripten_atomic_exchange_u8(void/*uint8_t*/ *addr, uint8_t newVal);
-uint16_t emscripten_atomic_exchange_u16(void/*uint16_t*/ *addr, uint16_t newVal);
-uint32_t emscripten_atomic_exchange_u32(void/*uint32_t*/ *addr, uint32_t newVal);
-uint64_t emscripten_atomic_exchange_u64(void/*uint64_t*/ *addr, uint64_t newVal);
+uint8_t emscripten_atomic_exchange_u8(void/*uint8_t*/ *addr __attribute__((nonnull)), uint8_t newVal);
+uint16_t emscripten_atomic_exchange_u16(void/*uint16_t*/ *addr __attribute__((nonnull)), uint16_t newVal);
+uint32_t emscripten_atomic_exchange_u32(void/*uint32_t*/ *addr __attribute__((nonnull)), uint32_t newVal);
+uint64_t emscripten_atomic_exchange_u64(void/*uint64_t*/ *addr __attribute__((nonnull)), uint64_t newVal);
 
 // CAS returns the *old* value that was in the memory location before the
 // operation took place.
 // That is, if the return value when calling this function equals to 'oldVal',
 // then the operation succeeded, otherwise it was ignored.
-uint8_t emscripten_atomic_cas_u8(void/*uint8_t*/ *addr, uint8_t oldVal, uint8_t newVal);
-uint16_t emscripten_atomic_cas_u16(void/*uint16_t*/ *addr, uint16_t oldVal, uint16_t newVal);
-uint32_t emscripten_atomic_cas_u32(void/*uint32_t*/ *addr, uint32_t oldVal, uint32_t newVal);
-uint64_t emscripten_atomic_cas_u64(void/*uint64_t*/ *addr, uint64_t oldVal, uint64_t newVal);
+uint8_t emscripten_atomic_cas_u8(void/*uint8_t*/ *addr __attribute__((nonnull)), uint8_t oldVal, uint8_t newVal);
+uint16_t emscripten_atomic_cas_u16(void/*uint16_t*/ *addr __attribute__((nonnull)), uint16_t oldVal, uint16_t newVal);
+uint32_t emscripten_atomic_cas_u32(void/*uint32_t*/ *addr __attribute__((nonnull)), uint32_t oldVal, uint32_t newVal);
+uint64_t emscripten_atomic_cas_u64(void/*uint64_t*/ *addr __attribute__((nonnull)), uint64_t oldVal, uint64_t newVal);
 
-uint8_t emscripten_atomic_load_u8(const void/*uint8_t*/ *addr);
-uint16_t emscripten_atomic_load_u16(const void/*uint16_t*/ *addr);
-uint32_t emscripten_atomic_load_u32(const void/*uint32_t*/ *addr);
-float emscripten_atomic_load_f32(const void/*float*/ *addr);
-uint64_t emscripten_atomic_load_u64(const void/*uint64_t*/ *addr);
-double emscripten_atomic_load_f64(const void/*double*/ *addr);
+uint8_t emscripten_atomic_load_u8(const void/*uint8_t*/ *addr __attribute__((nonnull)));
+uint16_t emscripten_atomic_load_u16(const void/*uint16_t*/ *addr __attribute__((nonnull)));
+uint32_t emscripten_atomic_load_u32(const void/*uint32_t*/ *addr __attribute__((nonnull)));
+float emscripten_atomic_load_f32(const void/*float*/ *addr __attribute__((nonnull)));
+uint64_t emscripten_atomic_load_u64(const void/*uint64_t*/ *addr __attribute__((nonnull)));
+double emscripten_atomic_load_f64(const void/*double*/ *addr __attribute__((nonnull)));
 
 // Returns the value that was stored (i.e. 'val')
-uint8_t emscripten_atomic_store_u8(void/*uint8_t*/ *addr, uint8_t val);
-uint16_t emscripten_atomic_store_u16(void/*uint16_t*/ *addr, uint16_t val);
-uint32_t emscripten_atomic_store_u32(void/*uint32_t*/ *addr, uint32_t val);
-float emscripten_atomic_store_f32(void/*float*/ *addr, float val);
-uint64_t emscripten_atomic_store_u64(void/*uint64_t*/ *addr, uint64_t val);
-double emscripten_atomic_store_f64(void/*double*/ *addr, double val);
+uint8_t emscripten_atomic_store_u8(void/*uint8_t*/ *addr __attribute__((nonnull)), uint8_t val);
+uint16_t emscripten_atomic_store_u16(void/*uint16_t*/ *addr __attribute__((nonnull)), uint16_t val);
+uint32_t emscripten_atomic_store_u32(void/*uint32_t*/ *addr __attribute__((nonnull)), uint32_t val);
+float emscripten_atomic_store_f32(void/*float*/ *addr __attribute__((nonnull)), float val);
+uint64_t emscripten_atomic_store_u64(void/*uint64_t*/ *addr __attribute__((nonnull)), uint64_t val);
+double emscripten_atomic_store_f64(void/*double*/ *addr __attribute__((nonnull)), double val);
 
 void emscripten_atomic_fence(void);
 
 // Each of the functions below (add, sub, and, or, xor) return the value that
 // was in the memory location before the operation occurred.
-uint8_t emscripten_atomic_add_u8(void/*uint8_t*/ *addr, uint8_t val);
-uint16_t emscripten_atomic_add_u16(void/*uint16_t*/ *addr, uint16_t val);
-uint32_t emscripten_atomic_add_u32(void/*uint32_t*/ *addr, uint32_t val);
-uint64_t emscripten_atomic_add_u64(void/*uint64_t*/ *addr, uint64_t val);
+uint8_t emscripten_atomic_add_u8(void/*uint8_t*/ *addr __attribute__((nonnull)), uint8_t val);
+uint16_t emscripten_atomic_add_u16(void/*uint16_t*/ *addr __attribute__((nonnull)), uint16_t val);
+uint32_t emscripten_atomic_add_u32(void/*uint32_t*/ *addr __attribute__((nonnull)), uint32_t val);
+uint64_t emscripten_atomic_add_u64(void/*uint64_t*/ *addr __attribute__((nonnull)), uint64_t val);
 
-uint8_t emscripten_atomic_sub_u8(void/*uint8_t*/ *addr, uint8_t val);
-uint16_t emscripten_atomic_sub_u16(void/*uint16_t*/ *addr, uint16_t val);
-uint32_t emscripten_atomic_sub_u32(void/*uint32_t*/ *addr, uint32_t val);
-uint64_t emscripten_atomic_sub_u64(void/*uint64_t*/ *addr, uint64_t val);
+uint8_t emscripten_atomic_sub_u8(void/*uint8_t*/ *addr __attribute__((nonnull)), uint8_t val);
+uint16_t emscripten_atomic_sub_u16(void/*uint16_t*/ *addr __attribute__((nonnull)), uint16_t val);
+uint32_t emscripten_atomic_sub_u32(void/*uint32_t*/ *addr __attribute__((nonnull)), uint32_t val);
+uint64_t emscripten_atomic_sub_u64(void/*uint64_t*/ *addr __attribute__((nonnull)), uint64_t val);
 
-uint8_t emscripten_atomic_and_u8(void/*uint8_t*/ *addr, uint8_t val);
-uint16_t emscripten_atomic_and_u16(void/*uint16_t*/ *addr, uint16_t val);
-uint32_t emscripten_atomic_and_u32(void/*uint32_t*/ *addr, uint32_t val);
-uint64_t emscripten_atomic_and_u64(void/*uint64_t*/ *addr, uint64_t val);
+uint8_t emscripten_atomic_and_u8(void/*uint8_t*/ *addr __attribute__((nonnull)), uint8_t val);
+uint16_t emscripten_atomic_and_u16(void/*uint16_t*/ *addr __attribute__((nonnull)), uint16_t val);
+uint32_t emscripten_atomic_and_u32(void/*uint32_t*/ *addr __attribute__((nonnull)), uint32_t val);
+uint64_t emscripten_atomic_and_u64(void/*uint64_t*/ *addr __attribute__((nonnull)), uint64_t val);
 
-uint8_t emscripten_atomic_or_u8(void/*uint8_t*/ *addr, uint8_t val);
-uint16_t emscripten_atomic_or_u16(void/*uint16_t*/ *addr, uint16_t val);
-uint32_t emscripten_atomic_or_u32(void/*uint32_t*/ *addr, uint32_t val);
-uint64_t emscripten_atomic_or_u64(void/*uint64_t*/ *addr, uint64_t val);
+uint8_t emscripten_atomic_or_u8(void/*uint8_t*/ *addr __attribute__((nonnull)), uint8_t val);
+uint16_t emscripten_atomic_or_u16(void/*uint16_t*/ *addr __attribute__((nonnull)), uint16_t val);
+uint32_t emscripten_atomic_or_u32(void/*uint32_t*/ *addr __attribute__((nonnull)), uint32_t val);
+uint64_t emscripten_atomic_or_u64(void/*uint64_t*/ *addr __attribute__((nonnull)), uint64_t val);
 
-uint8_t emscripten_atomic_xor_u8(void/*uint8_t*/ *addr, uint8_t val);
-uint16_t emscripten_atomic_xor_u16(void/*uint16_t*/ *addr, uint16_t val);
-uint32_t emscripten_atomic_xor_u32(void/*uint32_t*/ *addr, uint32_t val);
-uint64_t emscripten_atomic_xor_u64(void/*uint64_t*/ *addr, uint64_t val);
+uint8_t emscripten_atomic_xor_u8(void/*uint8_t*/ *addr __attribute__((nonnull)), uint8_t val);
+uint16_t emscripten_atomic_xor_u16(void/*uint16_t*/ *addr __attribute__((nonnull)), uint16_t val);
+uint32_t emscripten_atomic_xor_u32(void/*uint32_t*/ *addr __attribute__((nonnull)), uint32_t val);
+uint64_t emscripten_atomic_xor_u64(void/*uint64_t*/ *addr __attribute__((nonnull)), uint64_t val);
 
 #ifdef __cplusplus
 }

system/include/emscripten/console.h

@@ -11,9 +11,9 @@ extern "C" {
 
 // Write directly JavaScript console.  This can be useful for debugging since it
 // bypasses the stdio and filesystem sub-systems.
-void emscripten_console_log(const char *utf8String);
-void emscripten_console_warn(const char *utf8String);
-void emscripten_console_error(const char *utf8String);
+void emscripten_console_log(const char *utf8String __attribute__((nonnull)));
+void emscripten_console_warn(const char *utf8String __attribute__((nonnull)));
+void emscripten_console_error(const char *utf8String __attribute__((nonnull)));
 
 // Write to the out() and err() hooks directly (defined in shell.js).
 // These have different behavior compared to console.log/err.
@@ -23,16 +23,16 @@ void emscripten_console_error(const char *utf8String);
 // printErr, if provided on the Module object.
 // These functions are mainly intended for internal use.
 // See https://github.com/emscripten-core/emscripten/issues/14804
-void _emscripten_out(const char *utf8String);
-void _emscripten_err(const char *utf8String);
+void _emscripten_out(const char *utf8String __attribute__((nonnull)));
+void _emscripten_err(const char *utf8String __attribute__((nonnull)));
 void _emscripten_dbg(const char *utf8String);
 
 // Similar to the above functions but operate with printf-like semantics.
-void emscripten_console_logf(const char *utf8String, ...) __attribute__((__format__(printf, 1, 2)));
-void emscripten_console_warnf(const char *utf8String, ...) __attribute__((__format__(printf, 1, 2)));
-void emscripten_console_errorf(const char *utf8String, ...)__attribute__((__format__(printf, 1, 2)));
-void _emscripten_outf(const char *utf8String, ...) __attribute__((__format__(printf, 1, 2)));
-void _emscripten_errf(const char *utf8String, ...) __attribute__((__format__(printf, 1, 2)));
+void emscripten_console_logf(const char *utf8String __attribute__((nonnull)), ...) __attribute__((__format__(printf, 1, 2)));
+void emscripten_console_warnf(const char *utf8String __attribute__((nonnull)), ...) __attribute__((__format__(printf, 1, 2)));
+void emscripten_console_errorf(const char *utf8String __attribute__((nonnull)), ...)__attribute__((__format__(printf, 1, 2)));
+void _emscripten_outf(const char *utf8String __attribute__((nonnull)), ...) __attribute__((__format__(printf, 1, 2)));
+void _emscripten_errf(const char *utf8String __attribute__((nonnull)), ...) __attribute__((__format__(printf, 1, 2)));
 void _emscripten_dbgf(const char *utf8String, ...) __attribute__((__format__(printf, 1, 2)));
 
 #ifdef __cplusplus

system/include/emscripten/emmalloc.h

@@ -13,34 +13,39 @@ extern "C" {
 // *extremely slow*, use for debugging allocation test cases.
 void emmalloc_dump_memory_regions(void);
 
-// Allocates size bytes with the given pow-2 alignment.
+// Allocates size bytes with the given pow-2 alignment. If the WebAssembly memory runs out of
+// free bytes, this function will abort execution, or if building with -sABORTING_MALLOC=0,
+// return a null pointer.
 void *memalign(size_t alignment, size_t size);
 void *emmalloc_memalign(size_t alignment, size_t size);
 void *aligned_alloc(size_t alignment, size_t size);
 
-// Allocates size bytes with default alignment (8 bytes)
+// Allocates size bytes with default alignment (8 bytes). Like above, either aborts or returns
+// null on OOM.
 void *malloc(size_t size);
 void *emmalloc_malloc(size_t size);
 
 // Returns the number of bytes that are actually allocated to the given pointer ptr.
 // E.g. due to alignment or size requirements, the actual size of the allocation can be
-// larger than what was requested.
+// larger than what was requested. It is ok to pass a null pointer to these functions, in which
+// case 0 will be returned.
 size_t malloc_usable_size(void *ptr);
 size_t emmalloc_usable_size(void *ptr);
 
 // Frees a memory pointer allocated with any of the memory allocation functions declared
 // in this file, e.g.
 // (emmalloc_)memalign, (emmalloc_)malloc, (emmalloc_)calloc, aligned_alloc,
 // (emmalloc_)realloc, emmalloc_realloc_try, emmalloc_realloc_uninitialized, (emmalloc_)aligned_realloc
+// It is ok to pass null in ptr, which will be a no-op.
 void free(void *ptr);
 void emmalloc_free(void *ptr);
 
 // Performs a reallocation of the given memory pointer to a new size. If the memory region
 // pointed by ptr cannot be resized in place, a new memory region will be allocated, old
 // memory copied over, and the old memory area freed. The pointer ptr must have been
 // allocated with one of the emmalloc memory allocation functions (malloc, memalign, ...).
-// If called with size == 0, the pointer ptr is freed, and a null pointer is returned. If
-// called with null ptr, a new pointer is allocated.
+// If called with size == 0, the pointer ptr is freed, and a null pointer is returned.
+// If called with null ptr, a new pointer is allocated.
 // If there is not enough memory, the old memory block is not freed and null pointer is
 // returned.
 void *realloc(void *ptr, size_t size);

system/include/emscripten/emscripten.h

@@ -32,11 +32,11 @@
 extern "C" {
 #endif
 
-void emscripten_run_script(const char *script);
-int emscripten_run_script_int(const char *script);
-char *emscripten_run_script_string(const char *script);
-void emscripten_async_run_script(const char *script, int millis);
-void emscripten_async_load_script(const char *script, em_callback_func onload, em_callback_func onerror);
+void emscripten_run_script(const char *script __attribute__((nonnull)));
+int emscripten_run_script_int(const char *script __attribute__((nonnull)));
+char *emscripten_run_script_string(const char *script __attribute__((nonnull)));
+void emscripten_async_run_script(const char *script __attribute__((nonnull)), int millis);
+void emscripten_async_load_script(const char *script __attribute__((nonnull)), em_callback_func onload, em_callback_func onerror);
 
 void emscripten_set_main_loop(em_callback_func func, int fps, int simulate_infinite_loop);
 
@@ -45,7 +45,7 @@ void emscripten_set_main_loop(em_callback_func func, int fps, int simulate_infin
 #define EM_TIMING_SETIMMEDIATE 2
 
 int emscripten_set_main_loop_timing(int mode, int value);
-void emscripten_get_main_loop_timing(int *mode, int *value);
+void emscripten_get_main_loop_timing(int *mode, int *value); // Pass a null pointer to skip receiving that particular value
 void emscripten_set_main_loop_arg(em_arg_callback_func func, void *arg, int fps, int simulate_infinite_loop);
 void emscripten_pause_main_loop(void);
 void emscripten_resume_main_loop(void);
@@ -79,22 +79,22 @@ double emscripten_get_device_pixel_ratio(void);
 
 char *emscripten_get_window_title();
 void emscripten_set_window_title(const char *);
-void emscripten_get_screen_size(int *width, int *height);
+void emscripten_get_screen_size(int *width __attribute__((nonnull)), int *height __attribute__((nonnull)));
 void emscripten_hide_mouse(void);
 void emscripten_set_canvas_size(int width, int height) __attribute__((deprecated("This variant does not allow specifying the target canvas", "Use emscripten_set_canvas_element_size() instead")));
-void emscripten_get_canvas_size(int *width, int *height, int *isFullscreen) __attribute__((deprecated("This variant does not allow specifying the target canvas", "Use emscripten_get_canvas_element_size() and emscripten_get_fullscreen_status() instead")));
+void emscripten_get_canvas_size(int *width __attribute__((nonnull)), int *height __attribute__((nonnull)), int *isFullscreen __attribute__((nonnull))) __attribute__((deprecated("This variant does not allow specifying the target canvas", "Use emscripten_get_canvas_element_size() and emscripten_get_fullscreen_status() instead")));
 
 double emscripten_get_now(void);
 float emscripten_random(void);
 
 // IDB
 
 typedef void (*em_idb_onload_func)(void*, void*, int);
-void emscripten_idb_async_load(const char *db_name, const char *file_id, void* arg, em_idb_onload_func onload, em_arg_callback_func onerror);
-void emscripten_idb_async_store(const char *db_name, const char *file_id, void* ptr, int num, void* arg, em_arg_callback_func onstore, em_arg_callback_func onerror);
-void emscripten_idb_async_delete(const char *db_name, const char *file_id, void* arg, em_arg_callback_func ondelete, em_arg_callback_func onerror);
+void emscripten_idb_async_load(const char *db_name __attribute__((nonnull)), const char *file_id __attribute__((nonnull)), void* arg, em_idb_onload_func onload, em_arg_callback_func onerror);
+void emscripten_idb_async_store(const char *db_name __attribute__((nonnull)), const char *file_id __attribute__((nonnull)), void* ptr, int num, void* arg, em_arg_callback_func onstore, em_arg_callback_func onerror);
+void emscripten_idb_async_delete(const char *db_name __attribute__((nonnull)), const char *file_id __attribute__((nonnull)), void* arg, em_arg_callback_func ondelete, em_arg_callback_func onerror);
 typedef void (*em_idb_exists_func)(void*, int);
-void emscripten_idb_async_exists(const char *db_name, const char *file_id, void* arg, em_idb_exists_func oncheck, em_arg_callback_func onerror);
+void emscripten_idb_async_exists(const char *db_name __attribute__((nonnull)), const char *file_id __attribute__((nonnull)), void* arg, em_idb_exists_func oncheck, em_arg_callback_func onerror);
 
 // IDB "sync"
 

system/include/emscripten/eventloop.h

@@ -15,15 +15,15 @@ extern "C" {
 
 void emscripten_unwind_to_js_event_loop(void) __attribute__((__noreturn__));
 
-int emscripten_set_timeout(void (*cb)(void *user_data), double msecs, void *user_data);
+int emscripten_set_timeout(void (*cb)(void *user_data) __attribute__((nonnull)), double msecs, void *user_data);
 void emscripten_clear_timeout(int id);
-void emscripten_set_timeout_loop(EM_BOOL (*cb)(double time, void *user_data), double interval_ms, void *user_data);
+void emscripten_set_timeout_loop(EM_BOOL (*cb)(double time, void *user_data) __attribute__((nonnull)), double interval_ms, void *user_data);
 
-int emscripten_set_immediate(void (*cb)(void *user_data), void *user_data);
+int emscripten_set_immediate(void (*cb)(void *user_data) __attribute__((nonnull)), void *user_data);
 void emscripten_clear_immediate(int id);
 void emscripten_set_immediate_loop(EM_BOOL (*cb)(void *user_data), void *user_data);
 
-int emscripten_set_interval(void (*cb)(void *user_data), double interval_ms, void *user_data);
+int emscripten_set_interval(void (*cb)(void *user_data) __attribute__((nonnull)), double interval_ms, void *user_data);
 void emscripten_clear_interval(int id);
 
 void emscripten_runtime_keepalive_push();

system/include/emscripten/exports.h

@@ -16,7 +16,7 @@ extern "C" {
 
 // Returns a function pointer to the given exported function by name. Cast the returned pointer
 // to its proper signature before calling the function.
-void *emscripten_get_exported_function(const char *fname);
+void *emscripten_get_exported_function(const char *fname __attribute__((nonnull)));
 
 #ifdef __cplusplus
 }