source/include/H5FDdirect.h

0001 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
0002  * Copyright by The HDF Group.                                               *
0003  * All rights reserved.                                                      *
0004  *                                                                           *
0005  * This file is part of HDF5.  The full HDF5 copyright notice, including     *
0006  * terms governing use, modification, and redistribution, is contained in    *
0007  * the COPYING file, which can be found at the root of the source code       *
0008  * distribution tree, or in https://www.hdfgroup.org/licenses.               *
0009  * If you do not have access to either file, you may request a copy from     *
0010  * help@hdfgroup.org.                                                        *
0011  * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
0012
0013 /*
0014  * Purpose: The public header file for the direct virtual file driver (VFD)
0015  */
0016 #ifndef H5FDdirect_H
0017 #define H5FDdirect_H
0018
0019 #ifdef H5_HAVE_DIRECT
0020
0021 /** Initializer for the direct VFD */
0022 #define H5FD_DIRECT (H5FDperform_init(H5FD_direct_init))
0023
0024 /** Identifier for the direct VFD */
0025 #define H5FD_DIRECT_VALUE H5_VFD_DIRECT
0026
0027 #else
0028
0029 /** Initializer for the direct VFD (disabled) */
0030 #define H5FD_DIRECT       (H5I_INVALID_HID)
0031
0032 /** Identifier for the direct VFD (disabled) */
0033 #define H5FD_DIRECT_VALUE H5_VFD_INVALID
0034
0035 #endif /* H5_HAVE_DIRECT */
0036
0037 /** Default value for memory boundary */
0038 #define MBOUNDARY_DEF 4096
0039
0040 /** Default value for file block size */
0041 #define FBSIZE_DEF 4096
0042
0043 /** Default value for maximum copy buffer size */
0044 #define CBSIZE_DEF (16 * 1024 * 1024)
0045
0046 #ifdef H5_HAVE_DIRECT
0047 #ifdef __cplusplus
0048 extern "C" {
0049 #endif
0050
0051 /** @private
0052  *
0053  * \brief Private initializer for the direct VFD
0054  */
0055 H5_DLL hid_t H5FD_direct_init(void);
0056
0057 /**
0058  * \ingroup FAPL
0059  *
0060  * \brief Sets up use of the direct I/O driver
0061  *
0062  * \fapl_id
0063  * \param[in] alignment Required memory alignment boundary
0064  * \param[in] block_size File system block size
0065  * \param[in] cbuf_size Copy buffer size
0066  * \returns \herr_t
0067  *
0068  * \details H5Pset_fapl_direct() sets the file access property list, \p fapl_id,
0069  *          to use the direct I/O driver, #H5FD_DIRECT. With this driver, data
0070  *          is written to or read from the file synchronously without being
0071  *          cached by the system.
0072  *
0073  *          File systems usually require the data address in memory, the file
0074  *          address, and the size of the data to be aligned. The HDF5 library's
0075  *          direct I/O driver is able to handle unaligned data, though that will
0076  *          consume some additional memory resources and may slow
0077  *          performance. To get better performance, use the system function \p
0078  *          posix_memalign to align the data buffer in memory and the HDF5
0079  *          function H5Pset_alignment() to align the data in the file. Be aware,
0080  *          however, that aligned data I/O may cause the HDF5 file to be bigger
0081  *          than the actual data size would otherwise require because the
0082  *          alignment may leave some holes in the file.
0083  *
0084  *          \p alignment specifies the required alignment boundary in memory.
0085  *
0086  *          \p block_size specifies the file system block size. A value of 0
0087  *          (zero) means to use HDF5 library's default value of 4KB.
0088  *
0089  *          \p cbuf_size specifies the copy buffer size.
0090  *
0091  * \since 1.8.0
0092  *
0093  */
0094 H5_DLL herr_t H5Pset_fapl_direct(hid_t fapl_id, size_t alignment, size_t block_size, size_t cbuf_size);
0095
0096 /**
0097  * \ingroup FAPL
0098  *
0099  * \brief Retrieves direct I/O driver settings
0100  *
0101  * \fapl_id
0102  * \param[out] boundary Required memory alignment boundary
0103  * \param[out] block_size File system block size
0104  * \param[out] cbuf_size Copy buffer size
0105  * \returns \herr_t
0106  *
0107  * \details H5Pget_fapl_direct() retrieves the required memory alignment (\p
0108  *          alignment), file system block size (\p block_size), and copy buffer
0109  *          size (\p cbuf_size) settings for the direct I/O driver, #H5FD_DIRECT,
0110  *          from the file access property list \p fapl_id.
0111  *
0112  *          See H5Pset_fapl_direct() for discussion of these values,
0113  *          requirements, and important considerations.
0114  *
0115  * \since 1.8.0
0116  *
0117  */
0118 H5_DLL herr_t H5Pget_fapl_direct(hid_t fapl_id, size_t *boundary /*out*/, size_t *block_size /*out*/,
0119                                  size_t *cbuf_size /*out*/);
0120
0121 #ifdef __cplusplus
0122 }
0123 #endif
0124
0125 #endif /* H5_HAVE_DIRECT */
0126
0127 #endif