From 29b8231f92fb6b8da5e79e9f702135dec9819d07 Mon Sep 17 00:00:00 2001 From: Gerd Heber Date: Tue, 10 Nov 2020 14:28:59 -0600 Subject: Finished API Compatibility Macros. --- doxygen/dox/H5Oget_info_by_name.dox | 18 +++---- doxygen/dox/api-compat-macros.dox | 105 +++++++++++++++++++++++++++++++----- doxygen/dox/mainpage.dox | 2 +- 3 files changed, 102 insertions(+), 23 deletions(-) diff --git a/doxygen/dox/H5Oget_info_by_name.dox b/doxygen/dox/H5Oget_info_by_name.dox index 3276c5a..b1b9540 100644 --- a/doxygen/dox/H5Oget_info_by_name.dox +++ b/doxygen/dox/H5Oget_info_by_name.dox @@ -12,9 +12,9 @@ * document closely. * * In HDF5 versions 1.12 and after, #H5Oget_info_by_name is mapped to - * \ref H5Oget_info_by_name3(). In version 1.10 #H5Oget_info_by_name is - * identical to \ref H5Oget_info_by_name1(). - * + * \ref H5Oget_info_by_name3(). In version 1.10 #H5Oget_info_by_name is + * identical to \ref H5Oget_info_by_name1(). + * * Specific compile-time compatibility flags and the resulting * mappings are as follows: * @@ -66,27 +66,27 @@ * * * - * This change was added to restore the broken API compatibility + * This change was added to restore the broken API compatibility * introduced in HDF5-1.10.3. * * * 1.10.3 - * The function \ref H5Oget_info_by_name() was renamed + * The function \ref H5Oget_info_by_name() was renamed * to \ref H5Oget_info_by_name1. * * * - * The macro #H5Oget_info_by_name was renamed to + * The macro #H5Oget_info_by_name was renamed to * \ref H5Oget_info_by_name1(). * * * - * The macro #H5Oget_info_by_name and the function \ref H5Oget_info_name2() + * The macro #H5Oget_info_by_name and the function \ref H5Oget_info_by_name2() * were introduced in this release. * * * 1.8.8 - * Fortran 2003 subroutine and \ref h5o_info_t derived + * Fortran 2003 subroutine and \ref H5O_info_t derived * type introduced in this release. * * @@ -95,5 +95,5 @@ * * * - * + * */ diff --git a/doxygen/dox/api-compat-macros.dox b/doxygen/dox/api-compat-macros.dox index c5c868b..6b85ccb 100644 --- a/doxygen/dox/api-compat-macros.dox +++ b/doxygen/dox/api-compat-macros.dox @@ -146,8 +146,8 @@ - - + + @@ -304,7 +304,7 @@ \subsubsection fun-options-112 Function Mapping Options in Releases 1.12.x
\Code{configure} flagMacros map to release
(versioned function; \Code{H5Lvisit} shown)		Deprecated functions available?
(\Code{H5Lvisit1})		Macros map to release
(versioned function; \Code{H5Lvisit} shown)		Deprecated functions available?
(\Code{H5Lvisit1})
\Code{--with-default-api-version=v112}
(the default in 1.12)
- + @@ -507,7 +507,7 @@
Macro
(\Code{H5xxx})		Macro
(\Code{H5xxx})		 Default function used if no macro specified
  • Function/struct mapping:\Code{H5xxx_vers=N}
- + @@ -603,7 +603,7 @@ - + @@ -686,7 +686,7 @@ - + @@ -719,12 +719,12 @@ - + - @@ -751,7 +751,7 @@ - + @@ -803,7 +803,7 @@ - + @@ -811,10 +811,89 @@ -
MacroDefault function used
(if no macro specified)		Default function used
(if no macro specified)		 Introduced in \Code{h5cc} version flag and value Mapped to function or struct
Macro h5cc version flag and valueMapped to function
or struct		Mapped to function
or struct
H5Acreate()H5Eget_auto2()
\ref H5E_auto_t
Struct for H5Eset_auto()
and H5Eget_auto()		\ref H5E_auto_t
struct for H5Eset_auto()
and H5Eget_auto()		 \Code{DH5E_auto_t_vers=1} \ref H5E_auto1_t
\Code{DH5Gopen_vers=2}H5Gopen2}H5Gopen2()
H5Pget_filter() \Code{DH5Pget_filter_vers=1}H5Pget_filter1}()/td> + H5Pget_filter1()
\Code{DH5Pget_filter_vers=2}
H5Pregister() \Code{DH5Pregister_vers=1}H5Pregister1}H5Pregister1()
\Code{DH5Pregister_vers=2}H5Topen2()
\ref H5Z_class_t Struct for H5Zregister()\ref H5Z_class_t struct for H5Zregister() \Code{DH5Z_class_t_vers=1} \ref H5Z_class1_t
\Code{DH5Z_class_t_vers=2} \ref H5Z_class2_t
- + + \subsubsection further Further Information + It is possible to specify multiple function mappings for a single application build: + \code{.sh} + h5cc ... -DH5Rdereference_vers=1 -DH5Fget_info_vers=2 ... + \endcode + As a result of the function and struct mappings in this compile example, all + occurrences of the macro \Code{H5Rdereference} will be mapped to \Code{H5Rdereference1} + and all occurrences of the macro \Code{H5Fget_info} will be mapped to \Code{H5Fget_info2} + for the application being built. + + The function and struct mappings can be used to guarantee that a given API compatibility + macro will be mapped to the desired underlying function or struct version regardless of + the library or application mappings. In cases where an application may benefit greatly + from features offered by some of the later APIs, or must continue to use some earlier + API versions for compatibility reasons, this fine-grained control may be very important. + + As noted earlier, the function mappings can only reference versioned functions that are + included in the HDF5 library, as determined by the configure flag used to build the + library. For example, if the HDF5 library being linked with the application was built + with the \Code{--disable-deprecated-symbols} option, version 1 of the underlying functions + would not be available, and the example above that defined \Code{H5Rdereference_vers=1} + would not be supported. + + The function mappings do not negate any available functions. If \Code{H5Rdereference1} + is available in the installed version of the HDF5 library, and the application was not + compiled with the \Code{-DH5_NO_DEPRECATED_SYMBOLS} flag, the function \Code{H5Rdereference1} + will remain available to the application through its versioned name. Similarly, + \Code{H5Rdereference2} will remain available to the application as \Code{H5Rdereference2}. + The function mapping version flag \Code{H5Rdereference_vers} only controls the mapping of + the API compatibility macro \Code{H5Rdereference} to one of the two available functions. + + This can be especially useful in any case where the programmer does not have direct control + over global macro definitions, such as when writing code meant to be copied to multiple + applications or when writing code in a header file. + \section macros Compatibility Macros in HDF5 1.6.8 and Later + A series of similar compatibility macros were introduced into the release 1.6 + series of the library, starting with release 1.6.8. These macros simply alias the + '1' version functions, callbacks, and typedefs listed above to their original + non-numbered names. + + These macros were strictly a forward-looking feature at that time; they were not + necessary for compatibility in 1.6.x. These macros were created at that time to + enable writing code that could be used with any version of the library after 1.6.8 + and any library compilation options except \Code{H5_NO_DEPRECATED_SYMBOLS}, by always + using the '1' version of versioned functions and types. For example, \Code{H5Dopen1} + will always be interpreted in exactly the same manner by any version of the library + since 1.6.8. + \section use-case Common Use Case -*/ \ No newline at end of file + A common scenario where the API compatibility macros may be helpful is the migration + of an existing application to a new HDF5 release. An incremental migration plan is + outlined here: +
    +
  1. Build the HDF5 library without specifying any library mapping \Code{configure} + flag. In this default mode, the 1.6.x, 1.8.x, and 1.10.x versions of the + underlying functions are available, and the API compatibility macros will + be mapped to the current HDF5 versioned functions.
    2. +
  2. Compile the application with the \Code{-DH5_USE_NN_API} application mapping + option if it was written for use with an earlier HDF5 library. Because the + application mapping overrides the library mapping, the macros will all be + mapped to the earlier versions of the functions.
    3. +
  3. Remap one API compatibility macro at a time (or sets of macros), to use the + current HDF5 versions. At each stage, use the function mappings to map the macros + being worked on to the current versions. For example, use the + \Code{-DH5Rdereference_vers=2} version flag setting to remap the \Code{H5Rdereference} + macro to \Code{H5Rdereference2}, the 1.10.x version. + + During this step, the application code will need to be modified to change the calling + parameters used with the API compatibility macros to match the number and type + of the 1.10.x versioned functions. The macro name, for example \Code{H5Rdereference}, + should continue to be used in the code, to allow for possible re-mappings to later + versioned functions in a future release.
    4. +
  4. After all macros have been migrated to the latest versioned functions in step 3, + compile the application without any application or function mappings. This build + uses the library mappings set in step 1, and maps API compatibility macros to the + latest versions.
    5. +
  5. Finally, compile the application with the application mapping + \Code{-DH5_NO_DEPRECATED_SYMBOLS}, and address any failures to complete + the application migration process.
    6. +
+ + */ \ No newline at end of file diff --git a/doxygen/dox/mainpage.dox b/doxygen/dox/mainpage.dox index 7b62916..83fc323 100644 --- a/doxygen/dox/mainpage.dox +++ b/doxygen/dox/mainpage.dox @@ -33,4 +33,4 @@ * opportunity to close any temporary data structures that were set up when the * routine was called. The C++ application should save some state as the * routine is started so that any problem that occurs might be diagnosed. - */ + */ \ No newline at end of file -- cgit v0.12