summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorGerd Heber <gheber@hdfgroup.org>2020-11-10 20:28:59 (GMT)
committerGerd Heber <gheber@hdfgroup.org>2020-11-10 20:28:59 (GMT)
commit29b8231f92fb6b8da5e79e9f702135dec9819d07 (patch)
tree7bf29c408380067ecaab02345bfa74008f94c34d
parentc77bf5b3e5fda91259a5cef748ada97ac3b8437d (diff)
downloadhdf5-29b8231f92fb6b8da5e79e9f702135dec9819d07.zip
hdf5-29b8231f92fb6b8da5e79e9f702135dec9819d07.tar.gz
hdf5-29b8231f92fb6b8da5e79e9f702135dec9819d07.tar.bz2
Finished API Compatibility Macros.
-rw-r--r--doxygen/dox/H5Oget_info_by_name.dox18
-rw-r--r--doxygen/dox/api-compat-macros.dox105
-rw-r--r--doxygen/dox/mainpage.dox2
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 @@
* </tr>
* <tr>
* <td></td>
- * <td>This change was added to restore the broken API compatibility
+ * <td>This change was added to restore the broken API compatibility
* introduced in HDF5-1.10.3.</td>
* </tr>
* <tr>
* <td>1.10.3</td>
- * <td>The function \ref H5Oget_info_by_name() was renamed
+ * <td>The function \ref H5Oget_info_by_name() was renamed
* to \ref H5Oget_info_by_name1.</td>
* </tr>
* <tr>
* <td></td>
- * <td>The macro #H5Oget_info_by_name was renamed to
+ * <td>The macro #H5Oget_info_by_name was renamed to
* \ref H5Oget_info_by_name1().</td>
* </tr>
* <tr>
* <td></td>
- * <td>The macro #H5Oget_info_by_name and the function \ref H5Oget_info_name2()
+ * <td>The macro #H5Oget_info_by_name and the function \ref H5Oget_info_by_name2()
* were introduced in this release.</td>
* </tr>
* <tr>
* <td>1.8.8</td>
- * <td>Fortran 2003 subroutine and \ref h5o_info_t derived
+ * <td>Fortran 2003 subroutine and \ref H5O_info_t derived
* type introduced in this release.</td>
* </tr>
* <tr>
@@ -95,5 +95,5 @@
* </tr>
* </table>
*
- *
+ *
*/
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 @@
<table border="1" cellpadding="3">
<tr>
<th>\Code{configure} flag</th>
- <th>Macros map to release<br/>(versioned function; \Code{H5Lvisit} shown)</th>
- <th>Deprecated functions available? <br/>(\Code{H5Lvisit1})</th>
+ <th>Macros map to release <br/> (versioned function; \Code{H5Lvisit} shown)</th>
+ <th>Deprecated functions available? <br/> (\Code{H5Lvisit1})</th>
</tr>
<tr align="center">
<td>\Code{--with-default-api-version=v112} <br/> (the default in 1.12)</td>
@@ -304,7 +304,7 @@
\subsubsection fun-options-112 Function Mapping Options in Releases 1.12.x
<table>
<tr>
- <th style="text-align: left;">Macro<br/>(\Code{H5xxx})</th>
+ <th style="text-align: left;">Macro <br/> (\Code{H5xxx})</th>
<th>Default function used if no macro specified
<ul><li>Function/struct mapping:\Code{H5xxx_vers=N}</li></ul>
</th>
@@ -507,7 +507,7 @@
<table>
<tr>
<th>Macro</th>
- <th>Default function used<br/><sub>(if no macro specified)</sub></th>
+ <th>Default function used <br/> <sub>(if no macro specified)</sub></th>
<th>Introduced in</th>
<th>\Code{h5cc} version flag and value</th>
<th>Mapped to function or struct</th>
@@ -603,7 +603,7 @@
<tr>
<th>Macro</th>
<th><code>h5cc</code> version flag and value</th>
- <th>Mapped to function<br/>or struct</th>
+ <th>Mapped to function <br/> or struct</th>
</tr>
<tr>
<td rowspan="2">H5Acreate()</td>
@@ -686,7 +686,7 @@
<td>H5Eget_auto2()</td>
</tr>
<tr>
- <td rowspan="2">\ref H5E_auto_t <br/> Struct for H5Eset_auto() <br/> and H5Eget_auto()</td>
+ <td rowspan="2">\ref H5E_auto_t <br/> struct for H5Eset_auto() <br/> and H5Eget_auto()</td>
<td>\Code{DH5E_auto_t_vers=1}</td>
<td>\ref H5E_auto1_t</td>
</tr>
@@ -719,12 +719,12 @@
</tr>
<tr>
<td>\Code{DH5Gopen_vers=2}</td>
- <td>H5Gopen2}</td>
+ <td>H5Gopen2()</td>
</tr>
<tr>
<td rowspan="2">H5Pget_filter()</td>
<td>\Code{DH5Pget_filter_vers=1}</td>
- <td>H5Pget_filter1}()/td>
+ <td>H5Pget_filter1()</td>
</tr>
<tr>
<td>\Code{DH5Pget_filter_vers=2}</td>
@@ -751,7 +751,7 @@
<tr>
<td rowspan="2">H5Pregister()</td>
<td>\Code{DH5Pregister_vers=1}</td>
- <td>H5Pregister1}</td>
+ <td>H5Pregister1()</td>
</tr>
<tr>
<td>\Code{DH5Pregister_vers=2}</td>
@@ -803,7 +803,7 @@
<td>H5Topen2()</td>
</tr>
<tr>
- <td rowspan="2">\ref H5Z_class_t Struct for H5Zregister()</td>
+ <td rowspan="2">\ref H5Z_class_t struct for H5Zregister()</td>
<td>\Code{DH5Z_class_t_vers=1}</td>
<td>\ref H5Z_class1_t</td>
</tr>
@@ -811,10 +811,89 @@
<td>\Code{DH5Z_class_t_vers=2}</td>
<td>\ref H5Z_class2_t</td>
</tr>
- </table></div>
-
+ </table>
+ </div>
\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:
+ <ol>
+ <li>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.</li>
+ <li>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.</li>
+ <li>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.</li>
+ <li>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.</li>
+ <li>Finally, compile the application with the application mapping
+ \Code{-DH5_NO_DEPRECATED_SYMBOLS}, and address any failures to complete
+ the application migration process.</li>
+ </ol>
+
+ */ \ 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