From f9a8fd5a4c8f3c8f2d707dd384582181a0c33077 Mon Sep 17 00:00:00 2001 From: David Young Date: Mon, 10 Feb 2020 14:41:20 -0600 Subject: H5_HAVE_PARALLEL, _DEBUG_API, etc. Add attributes to some variables and parameters that are unused under some configurations. --- src/H5B2leaf.c | 2 +- src/H5I.c | 3 ++- src/H5Odbg.c | 4 +-- src/H5Pfapl.c | 3 ++- src/H5VLnative_attr.c | 3 ++- src/H5VLnative_group.c | 5 ++-- src/H5Z.c | 3 ++- src/H5private.h | 53 ++++++++++++++++++++++++++++----------- test/gen_new_super.c | 4 +-- test/gen_nullspace.c | 4 +-- test/gen_plist.c | 2 +- test/gen_specmetaread.c | 5 ++-- test/ttsafe_cancel.c | 2 +- tools/test/h5dump/h5dumpgentest.c | 2 +- 14 files changed, 63 insertions(+), 32 deletions(-) diff --git a/src/H5B2leaf.c b/src/H5B2leaf.c index 7ed0468..c1221ba 100644 --- a/src/H5B2leaf.c +++ b/src/H5B2leaf.c @@ -1051,7 +1051,7 @@ H5B2__assert_leaf(const H5B2_hdr_t H5_ATTR_NDEBUG_UNUSED *hdr, *------------------------------------------------------------------------- */ H5_ATTR_PURE herr_t -H5B2__assert_leaf2(const H5B2_hdr_t *hdr, const H5B2_leaf_t *leaf, const H5B2_leaf_t H5_ATTR_UNUSED *leaf2) +H5B2__assert_leaf2(const H5B2_hdr_t H5_ATTR_NDEBUG_UNUSED *hdr, const H5B2_leaf_t H5_ATTR_NDEBUG_UNUSED *leaf, const H5B2_leaf_t H5_ATTR_UNUSED *leaf2) { /* General sanity checking on node */ HDassert(leaf->nrec <= hdr->node_info->split_nrec); diff --git a/src/H5I.c b/src/H5I.c index 2ba8a2a..b233d23 100644 --- a/src/H5I.c +++ b/src/H5I.c @@ -215,7 +215,8 @@ H5I_term_package(void) *------------------------------------------------------------------------- */ H5I_type_t -H5Iregister_type(size_t hash_size, unsigned reserved, H5I_free_t free_func) +H5Iregister_type(size_t H5_ATTR_DEBUG_API_USED hash_size, unsigned reserved, + H5I_free_t free_func) { H5I_class_t *cls = NULL; /* New ID class */ H5I_type_t new_type; /* New ID type value */ diff --git a/src/H5Odbg.c b/src/H5Odbg.c index b8190ae..3c91cae 100644 --- a/src/H5Odbg.c +++ b/src/H5Odbg.c @@ -153,7 +153,7 @@ H5O__assert(const H5O_t *oh) /* Loop over all messages in object header */ for(u = 0, curr_msg = &oh->mesg[0]; u < oh->nmesgs; u++, curr_msg++) { - uint8_t *curr_hdr; /* Start of current message header */ + uint8_t H5_ATTR_NDEBUG_UNUSED *curr_hdr; /* Start of current message header */ size_t curr_tot_size; /* Total size of current message (including header) */ curr_hdr = curr_msg->raw - H5O_SIZEOF_MSGHDR_OH(oh); @@ -164,7 +164,7 @@ H5O__assert(const H5O_t *oh) free_space += curr_tot_size; else if(H5O_CONT_ID == curr_msg->type->id) { H5O_cont_t *cont = (H5O_cont_t *)curr_msg->native; - hbool_t found_chunk = FALSE; /* Found a chunk that matches */ + hbool_t H5_ATTR_NDEBUG_UNUSED found_chunk = FALSE; /* Found a chunk that matches */ HDassert(cont); diff --git a/src/H5Pfapl.c b/src/H5Pfapl.c index 9a04c3e..7866464 100644 --- a/src/H5Pfapl.c +++ b/src/H5Pfapl.c @@ -4479,7 +4479,8 @@ H5P_facc_mdc_log_location_close(const char H5_ATTR_UNUSED *name, size_t H5_ATTR_ *------------------------------------------------------------------------- */ herr_t -H5Pset_evict_on_close(hid_t fapl_id, hbool_t evict_on_close) +H5Pset_evict_on_close(hid_t fapl_id, + hbool_t H5_ATTR_PARALLEL_UNUSED evict_on_close) { H5P_genplist_t *plist; /* property list pointer */ herr_t ret_value = SUCCEED; /* return value */ diff --git a/src/H5VLnative_attr.c b/src/H5VLnative_attr.c index e54c49f..8072cd5 100644 --- a/src/H5VLnative_attr.c +++ b/src/H5VLnative_attr.c @@ -525,7 +525,8 @@ done: */ herr_t H5VL__native_attr_optional(void H5_ATTR_UNUSED *obj, H5VL_attr_optional_t opt_type, - hid_t H5_ATTR_UNUSED dxpl_id, void H5_ATTR_UNUSED **req, va_list arguments) + hid_t H5_ATTR_UNUSED dxpl_id, void H5_ATTR_UNUSED **req, + va_list H5_ATTR_DEPRECATED_USED arguments) { herr_t ret_value = SUCCEED; /* Return value */ diff --git a/src/H5VLnative_group.c b/src/H5VLnative_group.c index 3fdb2d9..236ee9d 100644 --- a/src/H5VLnative_group.c +++ b/src/H5VLnative_group.c @@ -266,8 +266,9 @@ done: *------------------------------------------------------------------------- */ herr_t -H5VL__native_group_optional(void *obj, H5VL_group_optional_t optional_type, - hid_t H5_ATTR_UNUSED dxpl_id, void H5_ATTR_UNUSED **req, va_list arguments) +H5VL__native_group_optional(void H5_ATTR_UNUSED *obj, + H5VL_group_optional_t optional_type, hid_t H5_ATTR_UNUSED dxpl_id, + void H5_ATTR_UNUSED **req, va_list H5_ATTR_DEPRECATED_USED arguments) { herr_t ret_value = SUCCEED; /* Return value */ diff --git a/src/H5Z.c b/src/H5Z.c index 53186f1..2f477a3 100644 --- a/src/H5Z.c +++ b/src/H5Z.c @@ -585,7 +585,8 @@ done: *------------------------------------------------------------------------- */ static int -H5Z__flush_file_cb(void *obj_ptr, hid_t H5_ATTR_UNUSED obj_id, void *key) +H5Z__flush_file_cb(void *obj_ptr, hid_t H5_ATTR_UNUSED obj_id, + void *key H5_ATTR_PARALLEL_USED) { H5F_t *f = (H5F_t *)obj_ptr; /* File object for operations */ #ifdef H5_HAVE_PARALLEL diff --git a/src/H5private.h b/src/H5private.h index f0f3687..a132ed3 100644 --- a/src/H5private.h +++ b/src/H5private.h @@ -304,17 +304,38 @@ * file). Be sure to update that file if the #ifdefs change here. */ #ifdef __cplusplus -# define H5_ATTR_FORMAT(X,Y,Z) /*void*/ -# define H5_ATTR_UNUSED /*void*/ -# define H5_ATTR_NDEBUG_UNUSED /*void*/ -# define H5_ATTR_NORETURN /*void*/ -# define H5_ATTR_CONST /*void*/ -# define H5_ATTR_PURE /*void*/ -# define H5_ATTR_FALLTHROUGH /*void*/ +# define H5_ATTR_FORMAT(X,Y,Z) /*void*/ +# define H5_ATTR_UNUSED /*void*/ +# define H5_ATTR_DEPRECATED_USED /*void*/ +# define H5_ATTR_NDEBUG_UNUSED /*void*/ +# define H5_ATTR_DEBUG_API_USED /*void*/ +# define H5_ATTR_PARALLEL_UNUSED /*void*/ +# define H5_ATTR_PARALLEL_USED /*void*/ +# define H5_ATTR_NORETURN /*void*/ +# define H5_ATTR_CONST /*void*/ +# define H5_ATTR_PURE /*void*/ +# define H5_ATTR_FALLTHROUGH /*void*/ #else /* __cplusplus */ #if defined(H5_HAVE_ATTRIBUTE) && !defined(__SUNPRO_C) # define H5_ATTR_FORMAT(X,Y,Z) __attribute__((format(X, Y, Z))) # define H5_ATTR_UNUSED __attribute__((unused)) +#ifdef H5_HAVE_PARALLEL +# define H5_ATTR_PARALLEL_UNUSED __attribute__((unused)) +# define H5_ATTR_PARALLEL_USED /*void*/ +#else +# define H5_ATTR_PARALLEL_UNUSED /*void*/ +# define H5_ATTR_PARALLEL_USED __attribute__((unused)) +#endif +#ifdef H5_NO_DEPRECATED_SYMBOLS +#define H5_ATTR_DEPRECATED_USED H5_ATTR_UNUSED +#else /* H5_NO_DEPRECATED_SYMBOLS */ +#define H5_ATTR_DEPRECATED_USED /*void*/ +#endif /* H5_NO_DEPRECATED_SYMBOLS */ +#ifdef H5_DEBUG_API +#define H5_ATTR_DEBUG_API_USED /*void*/ +#else /* H5_DEBUG_API */ +#define H5_ATTR_DEBUG_API_USED H5_ATTR_UNUSED +#endif /* H5_DEBUG_API */ #ifndef NDEBUG #define H5_ATTR_NDEBUG_UNUSED /*void*/ #else /* NDEBUG */ @@ -329,13 +350,17 @@ # define H5_ATTR_FALLTHROUGH /*void*/ #endif #else -# define H5_ATTR_FORMAT(X,Y,Z) /*void*/ -# define H5_ATTR_UNUSED /*void*/ -# define H5_ATTR_NDEBUG_UNUSED /*void*/ -# define H5_ATTR_NORETURN /*void*/ -# define H5_ATTR_CONST /*void*/ -# define H5_ATTR_PURE /*void*/ -# define H5_ATTR_FALLTHROUGH /*void*/ +# define H5_ATTR_FORMAT(X,Y,Z) /*void*/ +# define H5_ATTR_UNUSED /*void*/ +# define H5_ATTR_NDEBUG_UNUSED /*void*/ +# define H5_ATTR_DEBUG_API_USED /*void*/ +# define H5_ATTR_DEPRECATED_USED /*void*/ +# define H5_ATTR_PARALLEL_UNUSED /*void*/ +# define H5_ATTR_PARALLEL_USED /*void*/ +# define H5_ATTR_NORETURN /*void*/ +# define H5_ATTR_CONST /*void*/ +# define H5_ATTR_PURE /*void*/ +# define H5_ATTR_FALLTHROUGH /*void*/ #endif #endif /* __cplusplus */ diff --git a/test/gen_new_super.c b/test/gen_new_super.c index f6ce589..ed43a39 100644 --- a/test/gen_new_super.c +++ b/test/gen_new_super.c @@ -24,7 +24,7 @@ */ #include -#include "hdf5.h" +#include "testhdf5.h" #define TESTFILE "tsupern.h5" #define ISTORE_IK 64 @@ -50,7 +50,7 @@ main(void) { hid_t file; /* File IDs for old & new files */ hid_t fcpl; /* File creation property list */ - herr_t ret; /* Generic return value */ + herr_t H5_ATTR_NDEBUG_UNUSED ret; /* Create a file creation property list */ fcpl = H5Pcreate(H5P_FILE_CREATE); diff --git a/test/gen_nullspace.c b/test/gen_nullspace.c index 9d76deb..e4e75ac 100644 --- a/test/gen_nullspace.c +++ b/test/gen_nullspace.c @@ -24,8 +24,8 @@ * put into the 'test' directory in the 1.6.x branch of the library. */ -#include "hdf5.h" #include +#include "testhdf5.h" #define NULLFILE "tnullspace.h5" #define NULLDATASET "null_dataset" @@ -39,7 +39,7 @@ main(void) hid_t sid; /* Dataspace ID */ hid_t did; /* Dataset ID */ hid_t attr; /* Attribute ID */ - herr_t ret; /* Generic return value */ + herr_t H5_ATTR_NDEBUG_UNUSED ret; /* Generic return value */ /* Create the file */ fid = H5Fcreate(NULLFILE, H5F_ACC_TRUNC, H5P_DEFAULT, H5P_DEFAULT); diff --git a/test/gen_plist.c b/test/gen_plist.c index 8f38b1a..8fc8a05 100644 --- a/test/gen_plist.c +++ b/test/gen_plist.c @@ -458,7 +458,7 @@ encode_plist(hid_t plist_id, int little_endian, int word_length, const char *fil herr_t ret = 0; void *temp_buf = NULL; size_t temp_size = 0; - ssize_t write_size; + ssize_t H5_ATTR_NDEBUG_UNUSED write_size; char filename[1024]; /* Generate filename */ diff --git a/test/gen_specmetaread.c b/test/gen_specmetaread.c index d06bd59..fd484d1 100644 --- a/test/gen_specmetaread.c +++ b/test/gen_specmetaread.c @@ -23,9 +23,10 @@ * the library on the trunk as of when this file is checked in. */ -#include "hdf5.h" #include +#include "testhdf5.h" + #define FILENAME "specmetaread.h5" #define DIM 10 @@ -39,7 +40,7 @@ main(void) hsize_t dim[1] = {DIM}; unsigned data[DIM]; unsigned u; - herr_t ret; /* Generic return value */ + herr_t H5_ATTR_NDEBUG_UNUSED ret; /* Initialize the data */ for(u = 0; u < DIM; u++) diff --git a/test/ttsafe_cancel.c b/test/ttsafe_cancel.c index dd52232..f6bcd0d 100644 --- a/test/ttsafe_cancel.c +++ b/test/ttsafe_cancel.c @@ -61,7 +61,7 @@ tts_cancel(void) pthread_attr_t attribute; hid_t dataset; int buffer; - int ret; + int H5_ATTR_NDEBUG_UNUSED ret; /* make thread scheduling global */ ret=pthread_attr_init(&attribute); diff --git a/tools/test/h5dump/h5dumpgentest.c b/tools/test/h5dump/h5dumpgentest.c index e68e622..d72664e 100644 --- a/tools/test/h5dump/h5dumpgentest.c +++ b/tools/test/h5dump/h5dumpgentest.c @@ -3093,7 +3093,7 @@ static void gent_array1(void) hsize_t sdims1[] = {SPACE1_DIM1}; hsize_t tdims1[] = {ARRAY1_DIM1}; int i,j; /* counting variables */ - herr_t ret; /* Generic return value */ + herr_t ret H5_ATTR_NDEBUG_UNUSED; /* Generic return value */ /* Allocate and initialize array data to write */ for(i=0; i Date: Tue, 18 Feb 2020 16:31:35 -0600 Subject: Filter all of the new _USED / _UNUSED type modifiers. --- bin/trace | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/bin/trace b/bin/trace index 0256da6..de6a83f 100755 --- a/bin/trace +++ b/bin/trace @@ -239,7 +239,11 @@ sub argstring ($$$) { # certain type qualifiers, and indirection. $atype =~ s/^\bconst\b//; $atype =~ s/\bH5_ATTR_UNUSED\b//g; + $atype =~ s/\bH5_ATTR_DEPRECATED_USED\b//g; $atype =~ s/\bH5_ATTR_NDEBUG_UNUSED\b//g; + $atype =~ s/\bH5_ATTR_DEBUG_API_USED\b//g; + $atype =~ s/\bH5_ATTR_PARALLEL_UNUSED\b//g; + $atype =~ s/\bH5_ATTR_PARALLEL_USED\b//g; $atype =~ s/\s+/ /g; $ptr = length $1 if $atype =~ s/(\*+)//; $atype =~ s/^\s+//; -- cgit v0.12 From 50aac126d7c4082c2aeb0f3a68cad26bd1cd9783 Mon Sep 17 00:00:00 2001 From: David Young Date: Tue, 18 Feb 2020 17:07:40 -0600 Subject: Start to document the function/parameter/variable attribute macros. --- doc/code-conventions.md | 57 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 57 insertions(+) create mode 100644 doc/code-conventions.md diff --git a/doc/code-conventions.md b/doc/code-conventions.md new file mode 100644 index 0000000..ff3b4cf --- /dev/null +++ b/doc/code-conventions.md @@ -0,0 +1,57 @@ +# HDF5 Library Code Conventions + +This document describes some practices that are new, or newly +documented, starting in 2020. + +## Function / Variable Attributes + +In H5private.h, the library provides platform-independent macros +for qualifying function and variable definitions. + +### Functions that accept `printf(3)` and `scanf(3)` format strings + +Label functions that accept a `printf(3)`-compliant format string with +`H5_ATTR_FORMAT(printf,format_argno,variadic_argno)`, where +the format string is the `format_argno`th argument (counting from 1) +and the variadic arguments start with the `variadic_argno`th. + +Functions that accept a `scanf(3)`-compliant format string should +be labeled `H5_ATTR_FORMAT(scanf,format_argno,variadic_argno)`. + +### Functions that do never return + +The definition of a function that always causes the program to abort and hang +should be labeled `H5_ATTR_NORETURN` to help the compiler see which flows of +control are infeasible. + +### Other attributes + +**TBD** + +### Unused variables and parameters + +Compilers will warn about unused parameters and variables—developers should pay +attention to those warnings and make an effort to prevent them. + +Some function parameters and variables are unused in *all* configurations of +the project. Ordinarily, such parameters and variables should be deleted. +However, sometimes it is possible to foresee a parameter being used, or +removing it would change an API, or a parameter has to be defined to conform a +function to some function pointer type. In those cases, it's permissible to +mark a symbol `H5_ATTR_UNUSED`. + +Other parameters and variables are unused in *some* configurations of the +project, but not all. A symbol may fall into disuse in some configuration in +the future—then the compiler should warn, and the symbol should not be +defined—so developers should try to label a sometimes-unused symbol with an +attribute that's specific to the configurations where the symbol is (or is not) +expected to be used. The library provides the following attributes for that +purpose: + +* `H5_ATTR_DEPRECATED_USED`: used only if deprecated symbols are enabled +* `H5_ATTR_NDEBUG_UNUSED`: used only if `NDEBUG` is *not* \#defined +* `H5_ATTR_DEBUG_API_USED`: used if the debug API is enabled +* `H5_ATTR_PARALLEL_UNUSED`: used only if Parallel HDF5 *is not* configured +* `H5_ATTR_PARALLEL_USED`: used only if Parallel HDF5 *is* configured + +Some attributes may be phased in or phased out in the future. -- cgit v0.12