diff options
| -rw-r--r-- | doxygen/dox/api-compat-macros.dox | 195 |
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 |