diff options
Diffstat (limited to 'src/H5FDsubfiling/H5FDioc.h')
| -rw-r--r-- | src/H5FDsubfiling/H5FDioc.h | 193 |
1 files changed, 156 insertions, 37 deletions
diff --git a/src/H5FDsubfiling/H5FDioc.h b/src/H5FDsubfiling/H5FDioc.h index 04850f3..48102ac 100644 --- a/src/H5FDsubfiling/H5FDioc.h +++ b/src/H5FDsubfiling/H5FDioc.h @@ -11,7 +11,7 @@ * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ /* - * Purpose: The public header file for the "io concentrator" driver. + * Purpose: The public header file for the "I/O concentrator" driver. * This provides a similar functionality to that of the subfiling driver * but introduces the necessary file access functionality via a multi- * threading MPI service @@ -20,72 +20,191 @@ #ifndef H5FDioc_H #define H5FDioc_H +#include "H5FDsubfiling.h" + #ifdef H5_HAVE_IOC_VFD +/** + * \def H5FD_IOC + * Macro that returns the identifier for the #H5FD_IOC driver. \hid_t{file driver} + */ #define H5FD_IOC (H5FDperform_init(H5FD_ioc_init)) #else #define H5FD_IOC (H5I_INVALID_HID) #endif +/** + * \def H5FD_IOC_NAME + * The canonical name for the #H5FD_IOC driver + */ #define H5FD_IOC_NAME "ioc" #ifdef H5_HAVE_IOC_VFD #ifndef H5FD_IOC_FAPL_MAGIC -#define H5FD_CURR_IOC_FAPL_VERSION 1 -#define H5FD_IOC_FAPL_MAGIC 0xFED21331 +/** + * \def H5FD_IOC_CURR_FAPL_VERSION + * The version number of the H5FD_ioc_config_t configuration + * structure for the #H5FD_IOC driver + */ +#define H5FD_IOC_CURR_FAPL_VERSION 1 +/** + * \def H5FD_IOC_FAPL_MAGIC + * Unique number used to distinguish the #H5FD_IOC driver from other HDF5 file drivers + */ +#define H5FD_IOC_FAPL_MAGIC 0xFED21331 #endif -#define H5FD_IOC_THREAD_POOL_SIZE 4 +/** + * \def H5FD_IOC_DEFAULT_THREAD_POOL_SIZE + * The default number of I/O concentrator worker threads + */ +#define H5FD_IOC_DEFAULT_THREAD_POOL_SIZE 4 /* * Environment variables interpreted by the IOC VFD */ -#define H5_IOC_THREAD_POOL_COUNT "H5_IOC_THREAD_POOL_COUNT" -/* - * Define the various constants to allow different allocations - * of subfile ranks. The choices are self explanatory, starting - * with the default of one IO Concentrator (IOC) per node and - * lastly, defining a fixed number. +/** + * \def H5FD_IOC_THREAD_POOL_SIZE + * Macro for name of the environment variable that controls/overrides + * the number of I/O concentrator worker threads + * + * The value set for this environment variable is interpreted as an + * int value and must be > 0. */ -typedef enum { - SELECT_IOC_ONE_PER_NODE = 0, /* Default */ - SELECT_IOC_EVERY_NTH_RANK, /* Starting at rank 0, select-next += N */ - SELECT_IOC_WITH_CONFIG, /* NOT IMPLEMENTED: Read-from-file */ - SELECT_IOC_TOTAL, /* Starting at rank 0, mpi_size / total */ - ioc_selection_options /* (Uses same selection as every Nth rank) */ -} ioc_selection_t; +#define H5FD_IOC_THREAD_POOL_SIZE "H5FD_IOC_THREAD_POOL_SIZE" -/* - * In addition to the common configuration fields, we can have - * VFD specific fields. Here's one for the IO Concentrator VFD. +//! <!-- [H5FD_ioc_config_t_snip] --> +/** + * \struct H5FD_ioc_config_t + * \brief Configuration structure for H5Pset_fapl_ioc() / H5Pget_fapl_ioc() * - * thread_pool_count (int32_t) - * Indicate the number of helper threads that we want for - * creating a thread pool + * \details H5FD_ioc_config_t is a public structure that is used to pass + * configuration data to the #H5FD_IOC driver via a File Access + * Property List. A pointer to an instance of this structure is + * a parameter to H5Pset_fapl_ioc() and H5Pget_fapl_ioc(). + * + * The #H5FD_IOC driver shares much of its configuration with the + * #H5FD_SUBFILING driver and so its configuration structure + * contains an instance of a H5FD_subfiling_shared_config_t + * configuration structure. + * + * \var uint32_t H5FD_ioc_config_t::magic + * A somewhat unique number which distinguishes the #H5FD_IOC driver + * from other drivers. Used in combination with a version number, it + * can help to validate a user-generated File Access Property List. + * This field should be set to #H5FD_IOC_FAPL_MAGIC. + * + * \var uint32_t H5FD_ioc_config_t::version + * Version number of the H5FD_ioc_config_t structure. Any instance passed + * to H5Pset_fapl_ioc() / H5Pget_fapl_ioc() must have a recognized version + * number or an error will be raised. Currently, this field should be set + * to #H5FD_IOC_CURR_FAPL_VERSION. + * + * \var hid_t H5FD_ioc_config_t::under_fapl_id + * The File Access Property List which is setup with the file driver + * to use for I/O to the HDF5 stub file. The stub file looks like a + * typical HDF5 file, but currently only contains the superblock metadata + * for compatibility with legacy HDF5 applications. The default driver used + * is currently the #H5FD_MPIO driver. + * + * \var int32_t H5FD_ioc_config_t::thread_pool_count + * The number of I/O concentrator worker threads to use. + * + * This value can also be set or adjusted with the #H5FD_IOC_THREAD_POOL_SIZE + * environment variable. + * + * \var H5FD_subfiling_shared_config_t H5FD_ioc_config_t::subf_config + * Subfiling configuration data for the parent #H5FD_SUBFILING driver. This + * includes the sub-file stripe size, number of I/O concentrators, IOC + * selection method, etc. * - * ---------------------------------------------------------------------------- */ - typedef struct H5FD_ioc_config_t { - uint32_t magic; /* set to H5FD_IOC_FAPL_MAGIC */ - uint32_t version; /* set to H5FD_CURR_IOC_FAPL_VERSION */ - int32_t stripe_count; /* How many io concentrators */ - int64_t stripe_depth; /* Max # of bytes in contiguous IO to an IOC */ - ioc_selection_t ioc_selection; /* Method to select IO Concentrators */ - hid_t ioc_fapl_id; /* The hid_t value of the stacked VFD */ - int32_t thread_pool_count; + uint32_t magic; /* Must be set to H5FD_IOC_FAPL_MAGIC */ + uint32_t version; /* Must be set to H5FD_IOC_CURR_FAPL_VERSION */ + hid_t under_fapl_id; /* FAPL setup with the VFD to use for I/O to the HDF5 stub file */ + int32_t thread_pool_count; /* Number of I/O concentrator worker threads to use */ + H5FD_subfiling_shared_config_t subf_config; /* Subfiling driver configuration */ } H5FD_ioc_config_t; +//! <!-- [H5FD_ioc_config_t_snip] --> #ifdef __cplusplus extern "C" { #endif -H5_DLL hid_t H5FD_ioc_init(void); -H5_DLL herr_t H5Pset_fapl_ioc(hid_t fapl_id, H5FD_ioc_config_t *config_ptr); -H5_DLL herr_t H5Pget_fapl_ioc(hid_t fapl_id, H5FD_ioc_config_t *config_ptr); -H5_DLL void begin_thread_exclusive(void); -H5_DLL void end_thread_exclusive(void); +/** + * \brief Internal routine to initialize #H5FD_IOC driver. Not meant to be + * called directly by an HDF5 application + */ +H5_DLL hid_t H5FD_ioc_init(void); +/** + * \ingroup FAPL + * + * \brief Modifies the specified File Access Property List to use the #H5FD_IOC driver + * + * \fapl_id + * \param[in] vfd_config Pointer to #H5FD_IOC driver configuration structure. May be NULL. + * \returns \herr_t + * + * \details H5Pset_fapl_ioc() modifies the File Access Property List to use the + * #H5FD_IOC driver. + * + * The #H5FD_IOC driver is a reference implementation of an "I/O concentrator" + * file driver that works in conjunction with the #H5FD_SUBFILING driver and + * provides the I/O backend for servicing I/O requests to sub-files. + * + * Typically, an HDF5 application won't need to call this routine directly. + * The #H5FD_IOC driver is usually set up as a side effect of an HDF5 application + * using the #H5FD_SUBFILING driver, but this routine is provided in case the + * application wishes to manually configure the #H5FD_IOC driver. + * + * \note The \p vfd_config parameter may be NULL. In this case, the driver will + * be setup with default settings. Note that in this case, it is assumed + * the parent #H5FD_SUBFILING driver was also setup with default settings. + * If the two drivers differ in configuration settings, application behavior + * may not be as expected. + * + * \since 1.13.2 + * + */ +H5_DLL herr_t H5Pset_fapl_ioc(hid_t fapl_id, H5FD_ioc_config_t *vfd_config); +/** + * \ingroup FAPL + * + * \brief Queries a File Access Property List for #H5FD_IOC file driver properties + * + * \fapl_id + * \param[out] config_out Pointer to H5FD_ioc_config_t structure through which the + * #H5FD_IOC file driver properties will be returned. + * + * \returns \herr_t + * + * \details H5Pget_fapl_ioc() queries the specified File Access Property List for + * #H5FD_IOC driver properties as set by H5Pset_fapl_ioc(). If the #H5FD_IOC + * driver has not been set on the File Access Property List, a default + * configuration is returned. An HDF5 application may use this functionality + * to manually configure the #H5FD_IOC driver by calling H5Pget_fapl_ioc() + * on a newly-created File Access Property List, adjusting the default + * values and then calling H5Pset_fapl_ioc() with the configured + * H5FD_ioc_config_t structure. + * + * \since 1.13.2 + * + */ +H5_DLL herr_t H5Pget_fapl_ioc(hid_t fapl_id, H5FD_ioc_config_t *config_out); +/** + * \brief Internal routine for managing exclusive access to critical sections + * by the #H5FD_IOC driver's worker threads. Not meant to be called + * directly by an HDF5 application + */ +H5_DLL void H5FD_ioc_begin_thread_exclusive(void); +/** + * \brief Internal routine for managing exclusive access to critical sections + * by the #H5FD_IOC driver's worker threads. Not meant to be called + * directly by an HDF5 application + */ +H5_DLL void H5FD_ioc_end_thread_exclusive(void); #ifdef __cplusplus } |