summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--doxygen/dox/api-compat-macros.dox195
1 files changed, 195 insertions, 0 deletions
diff --git a/doxygen/dox/api-compat-macros.dox b/doxygen/dox/api-compat-macros.dox
new file mode 100644
index 0000000..239e608
--- /dev/null
+++ b/doxygen/dox/api-compat-macros.dox
@@ -0,0 +1,195 @@
+/** \page api-compat-macros API Compatibility Macros
+ \tableofcontents
+
+ \section audience Audience
+ The target audience for this document has existing applications that use the
+ HDF5 library, and is considering moving to the latest HDF5 release to take
+ advantage of the latest library features and enhancements.
+
+ \section compat-issues Compatibility Issues
+ With each major release of HDF5, such as 1.12 or 1.10, certain compatibility
+ issues must be considered when migrating applications from an earlier major
+ release.
+
+ This document describes the approach taken by The HDF Group to help existing
+ users of HDF5 address compatibility issues in the HDF5 API.
+
+ \section summary Summary and Motivation
+ In response to new and evolving requirements for the library and data format,
+ several basic functions have changed since HDF5 was first released. To allow
+ existing applications to continue to compile and run properly, all versions
+ of these functions have been retained in the later releases of the HDF5 library.
+
+ Given the scope of changes available with each major release of HDF5, and
+ recognizing the potentially time-consuming task of editing all the affected
+ calls in user applications, The HDF Group has created a set of macros that
+ can be used to flexibly and easily map existing API calls to previous release
+ functions. We refer to these as the \Emph{API compatibility macros}.
+
+ The HDF Group generally encourages users to update applications to work with
+ the latest HDF5 library release so that all new features and enhancements are
+ available to them. At the same time, The HDF Group understands that, under
+ some circumstances, updating applications may not be feasible or necessary.
+ The API compatibility macros, described in this document, provide a bridge
+ from old APIs to new and can be particularly helpful in situations such as these:
+ <ul>
+ <li>Source code is not available - only binaries are available; updating the
+ application is not feasible.</li>
+ <li>Source code is available, but there are no resources to update it.</li>
+ <li>Source code is available, as are resources to update it, but the old
+ version works quite well so updates are not a priority. At the same time,
+ it is desirable to take advantage of certain efficiencies in the newer HDF5
+ release that do not require code changes.</li>
+ <li>Source code is available, as are resources to update it, but the applications
+ are large or complex, and must continue to run while the code updates are
+ carried out.</li>
+ </ul>
+
+ \section using Understanding and Using the Macros
+ As part of latest HDF5 release, several functions that existed in previous
+ versions of the library were updated with new calling parameters and given
+ new names. The updated versions of the functions have a number (for, e.g., '2')
+ at the end of the original function name. The original versions of these
+ functions were retained and renamed to have an earlier number (for, e.g., '1')
+ at the end of the original function name.
+
+ For example, consider the function \Code{H5Lvisit} in HDF5 release 1.10
+ as compared with 1.12:
+
+ <table>
+ <tr>
+ <th>Original function name and signature in 1.10.0</th>
+ <td colspan="1">
+ \Code{herr_t H5Lvisit(hid_t grp_id, H5_index_t idx_type, H5_iter_order_t order, H5L_iterate_t op, void *op_data)}
+ </td>
+ </tr>
+ <tr>
+ <th>Updated function and signature, introduced in release 1.12.0</th>
+ <td colspan="1">
+ \Code{herr_t H5Lvisit2(hid_t group_id, H5_index_t idx_type, H5_iter_order_t order, H5L_iterate2_t op, void *op_data)}
+ </td>
+ </tr>
+ <tr><th>Original function and signature, renamed in release 1.12.0</th>
+ <td colspan="1">
+ \Code{herr_t H5Lvisit1(hid_t group_id, H5_index_t idx_type, H5_iter_order_t order, H5L_iterate1_t op, void *op_data)}
+ </td>
+ </tr>
+ <tr><th>API compatibility macro, introduced in release 1.12.0</th>
+ <td colspan="1">
+ \Code{H5Lvisit}
+ <p>The macro, \Code{H5Lvisit}, will be mapped to either \Code{H5Lvisit1} or
+ \Code{H5Lvisit2}. The mapping is determined by a combination of the
+ configuration options use to build the HDF5 library and compile-time
+ options used to build the application. The calling parameters used with the
+ \Code{H5Lvisit} compatibility macro should match the number and type of the
+ function the macros will be mapped to (\Code{H5Lvisit1} or \Code{H5Lvisit2}).
+ </p>
+ <p>The function names ending in '1' or '2' are referred to as \Emph{versioned names},
+ and the corresponding functions are referred to as \Emph{versioned functions}.
+ For new code development, The HDF Group recommends use of the compatibility macro
+ mapped to the latest version of the function. The original version of the function
+ should be considered deprecated and, in general, should not be used when developing
+ new code.
+ </p>
+ </td>
+ </tr>
+ </table>
+
+ \section options Compatibility Macro Mapping Options
+ To determine the mapping for a given API compatibility macro in a given application,
+ a combination of user-controlled selections, collectively referred to as the
+ \Emph{compatibility macro mapping options}, is considered in the following sequence:
+
+ <table border="0" style="width: 100.0%;">
+ <tr>
+ <td valign="top" width="50%">
+ <ol>
+ <li>What compatibility macro configuration option was used to build the HDF5 library?
+ We refer to this selection as the \Emph{library mapping}.</li>
+ <li>Was a compatibility macro global compile-time option specified when the application
+ was built? We refer to this (optional) selection as the \Emph{application mapping}.
+ If an application mapping exists, it overrides the library mapping.
+ \Emph{(See adjacent notes.)}</li>
+ <li>Were any compatibility macro function-level compile-time options specified when the
+ application was built? We refer to these (optional) selections as \Emph{function mappings}.
+ If function mappings exist, they override library and application mappings for the
+ relevant API compatibility macros. \Emph{(See adjacent notes.)}</li>
+ </ol>
+ </td>
+ <td valign="top" width="50%">
+ <table border="1" cellpadding="10" style="width: 100.0%;">
+ <tr><td>
+ \Bold{Notes:} An application mapping can map APIs to the same version or to a version
+ older than the configured library mapping. When the application attempts to map APIs
+ to a newer version of the API than the library was configured with, it will fail to
+ "upgrade" the mapping (and may fail silently).
+
+ When it is necessary to "upgrade" the macro mappings from those set in the library mapping,
+ it must be done at the per-function level, using the function-level mappings. As long as
+ one does not try to map a function to a version that was compiled out in the library mapping,
+ individual functions can be upgraded or downgraded freely.
+ </td>
+ </tr>
+ </table>
+ </td>
+ </tr>
+ </table>
+
+ \subsection lib-options Library Mapping Options
+ When the HDF5 library is built, \Code{configure} flags can be used to control the API
+ compatibility macro mapping behavior exhibited by the library. This behavior can be
+ overridden by application and function mappings. One configure flag excludes deprecated
+ functions from the HDF5 library, making them unavailable to applications linked with the
+ library.
+
+ <div align="center">Table 1: Library Mapping Options
+ <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>
+ </tr>
+ <tr align="center">
+ <td>\Code{--with-default-api-version=v112} <br/> (the default in 1.12)</td>
+ <td>1.12.x (\Code{H5Lvisit2})</td>
+ <td>yes</td>
+ </tr>
+ <tr align="center">
+ <td align="left">\Code{--with-default-api-version=v110}</td>
+ <td>1.10.x (\Code{H5Lvisit1})</td>
+ <td>yes</td>
+ </tr>
+ <tr align="center">
+ <td align="left">\Code{--with-default-api-version=v18}</td>
+ <td>1.8.x (\Code{H5Lvisit1})</td>
+ <td>yes</td>
+ </tr>
+ <tr align="center">
+ <td align="left">\Code{--with-default-api-version=v16}</td>
+ <td>1.6.x (\Code{H5Lvisit1})</td>
+ <td>yes</td>
+ </tr>
+ <tr align="center">
+ <td align="left">\Code{--disable-deprecated-symbols}</td>
+ <td>1.12.x (\Code{H5Lvisit2})</td>
+ <td>no</td>
+ </tr>
+ </table>
+ </div>
+ Refer to the file \Code{libhdf5.settings} in the directory where the HDF5 library is
+ installed to determine the \Code{configure} flags used to build the library. In particular,
+ look for the two lines shown here under \Emph{Features}:
+
+ \Code{Default API mapping: v112}
+
+ \Code{With deprecated public symbols: yes}
+
+ \subsection app-options Application Mapping Options
+ \subsection fun-options Function Mapping Options
+ \subsubsection fun-options-112 Function Mapping Options in Releases 1.12.x
+ \subsubsection fun-options-110 Function Mapping Options in Releases 1.10.x
+ \subsubsection fun-options-18 Function Mapping Options in Releases 1.8.x
+ \subsubsection further Further Information
+ \section macros Compatibility Macros in HDF5 1.6.8 and Later
+ \section use-case Common Use Case
+*/ \ No newline at end of file