source/include/H5FDdevelop.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  * This file contains public declarations for the H5FD (file drivers) developer
0015  *      support routines.
0016  */
0017
0018 #ifndef H5FDdevelop_H
0019 #define H5FDdevelop_H
0020
0021 /* Include package's public header */
0022 #include "H5FDpublic.h"
0023
0024 /*****************/
0025 /* Public Macros */
0026 /*****************/
0027
0028 /**
0029  * Version of the file driver struct, H5FD_class_t
0030  */
0031 #define H5FD_CLASS_VERSION 0x01 /* File driver struct version */
0032
0033 /* Map "fractal heap" header blocks to 'ohdr' type file memory, since its
0034  * a fair amount of work to add a new kind of file memory and they are similar
0035  * enough to object headers and probably too minor to deserve their own type.
0036  *
0037  * Map "fractal heap" indirect blocks to 'ohdr' type file memory, since they
0038  * are similar to fractal heap header blocks.
0039  *
0040  * Map "fractal heap" direct blocks to 'lheap' type file memory, since they
0041  * will be replacing local heaps.
0042  *
0043  * Map "fractal heap" 'huge' objects to 'draw' type file memory, since they
0044  * represent large objects that are directly stored in the file.
0045  *
0046  *      -QAK
0047  */
0048
0049 /**
0050  * Fractal heap header block; it is mapped to 'ohdr' type file memory to
0051  * benefit from their similarity.
0052  */
0053 #define H5FD_MEM_FHEAP_HDR H5FD_MEM_OHDR
0054 /**
0055  * Fractal heap indirect block; it is mapped to 'ohdr' type file memory
0056  * because the indirect blocks are similar to fractal heap header blocks.
0057  */
0058 #define H5FD_MEM_FHEAP_IBLOCK H5FD_MEM_OHDR
0059 /**
0060  * Fractal heap direct block; it is mapped to 'lheap' type file memory,
0061  * because the fractal heap direct blocks will be replacing local heaps.
0062  */
0063 #define H5FD_MEM_FHEAP_DBLOCK H5FD_MEM_LHEAP
0064 /**
0065  * Fractal heap 'huge' object; it is mapped to 'draw' type file memory because
0066  * the fractal heap 'huge' objects represent large objects that are directly
0067  * stored in the file.
0068  */
0069 #define H5FD_MEM_FHEAP_HUGE_OBJ H5FD_MEM_DRAW
0070
0071 /**
0072  * Free space header blocks; it is mapped to 'ohdr' type file memory to
0073  * benefit from their similarity.
0074  */
0075 #define H5FD_MEM_FSPACE_HDR H5FD_MEM_OHDR
0076 /**
0077  * Free space serialized section; it is mapped to 'lheap' type file memory
0078  * because it is similar enough to local heap info.
0079  */
0080 #define H5FD_MEM_FSPACE_SINFO H5FD_MEM_LHEAP
0081
0082 /**
0083  * Shared object header message master table; it is mapped to 'ohdr' type file
0084  * memory to benefit from their similarity.
0085  */
0086 #define H5FD_MEM_SOHM_TABLE H5FD_MEM_OHDR
0087 /**
0088  * Shared object header message index; it is mapped to 'btree' type file memory
0089  * because the indices are similar enough to B-tree nodes.
0090  */
0091 #define H5FD_MEM_SOHM_INDEX H5FD_MEM_BTREE
0092 /**
0093  * Extensible array header block; it is mapped to 'ohdr' type file memory to
0094  * benefit from their similarity.
0095  * \since 1.10.0
0096  */
0097 #define H5FD_MEM_EARRAY_HDR H5FD_MEM_OHDR
0098 /**
0099  * Extensible array index block; it is mapped to 'ohdr' type file memory because
0100  * these index blocks are similar to extensible array header blocks.
0101  * \since 1.10.0
0102  */
0103 #define H5FD_MEM_EARRAY_IBLOCK H5FD_MEM_OHDR
0104 /**
0105  * Extensible array super block; it is mappend to 'btree' type file memory
0106  * because the indices are similar enough to B-tree nodes.
0107  * \since 1.10.0
0108  */
0109 #define H5FD_MEM_EARRAY_SBLOCK H5FD_MEM_BTREE
0110 /**
0111  * Extensible array data block; it is mapped to 'lheap' type file memory
0112  * because it is similar enough to local heap info.
0113  * \since 1.10.0
0114  */
0115 #define H5FD_MEM_EARRAY_DBLOCK H5FD_MEM_LHEAP
0116 /**
0117  * Extensible array data block & page; it is mapped to 'lheap' type file memory
0118  * because it is similar enough to local heap info.
0119  * \since 1.10.0
0120  */
0121 #define H5FD_MEM_EARRAY_DBLK_PAGE H5FD_MEM_LHEAP
0122 /**
0123  * Fixed array header block; it is mapped to 'ohdr' type file memory to
0124  * benefit their similarity.
0125  * \since 1.10.0
0126  */
0127 #define H5FD_MEM_FARRAY_HDR H5FD_MEM_OHDR
0128 /**
0129  * Fixed array data block; it is mapped to 'lheap' type file memory
0130  * because it is similar enough to local heap info.
0131  * \since 1.10.0
0132  */
0133 #define H5FD_MEM_FARRAY_DBLOCK H5FD_MEM_LHEAP
0134 /**
0135  * Fixed array data block & page; it is mapped to 'lheap' type file memory
0136  * because it is similar enough to local heap info.
0137  * \since 1.10.0
0138  */
0139 #define H5FD_MEM_FARRAY_DBLK_PAGE H5FD_MEM_LHEAP
0140
0141 /**
0142  * A free-list map which maps all types of allocation requests to a single
0143  * free list.  This is useful for drivers that don't really care about
0144  * keeping different requests segregated in the underlying file and which
0145  * want to make most efficient reuse of freed memory.  The use of the
0146  * H5FD_MEM_SUPER free list is arbitrary.
0147  */
0148 #define H5FD_FLMAP_SINGLE                                                                                    \
0149     {                                                                                                        \
0150         H5FD_MEM_SUPER,     /*default*/                                                                      \
0151             H5FD_MEM_SUPER, /*super*/                                                                        \
0152             H5FD_MEM_SUPER, /*btree*/                                                                        \
0153             H5FD_MEM_SUPER, /*draw*/                                                                         \
0154             H5FD_MEM_SUPER, /*gheap*/                                                                        \
0155             H5FD_MEM_SUPER, /*lheap*/                                                                        \
0156             H5FD_MEM_SUPER  /*ohdr*/                                                                         \
0157     }
0158
0159 /**
0160  * A free-list map which segregates requests into `raw' or `meta' data
0161  * pools.
0162  */
0163 #define H5FD_FLMAP_DICHOTOMY                                                                                 \
0164     {                                                                                                        \
0165         H5FD_MEM_SUPER,     /*default*/                                                                      \
0166             H5FD_MEM_SUPER, /*super*/                                                                        \
0167             H5FD_MEM_SUPER, /*btree*/                                                                        \
0168             H5FD_MEM_DRAW,  /*draw*/                                                                         \
0169             H5FD_MEM_DRAW,  /*gheap*/                                                                        \
0170             H5FD_MEM_SUPER, /*lheap*/                                                                        \
0171             H5FD_MEM_SUPER  /*ohdr*/                                                                         \
0172     }
0173
0174 /**
0175  * The default free list map which causes each request type to use it's own
0176  * free-list.
0177  */
0178 #define H5FD_FLMAP_DEFAULT                                                                                   \
0179     {                                                                                                        \
0180         H5FD_MEM_DEFAULT,     /*default*/                                                                    \
0181             H5FD_MEM_DEFAULT, /*super*/                                                                      \
0182             H5FD_MEM_DEFAULT, /*btree*/                                                                      \
0183             H5FD_MEM_DEFAULT, /*draw*/                                                                       \
0184             H5FD_MEM_DEFAULT, /*gheap*/                                                                      \
0185             H5FD_MEM_DEFAULT, /*lheap*/                                                                      \
0186             H5FD_MEM_DEFAULT  /*ohdr*/                                                                       \
0187     }
0188
0189 /*******************/
0190 /* Public Typedefs */
0191 /*******************/
0192
0193 /* Forward declaration */
0194 typedef struct H5FD_t H5FD_t;
0195
0196 /**
0197  * Class information for each file driver
0198  */
0199 typedef struct H5FD_class_t {
0200     unsigned version;
0201     /**< File driver class struct version number */
0202
0203     H5FD_class_value_t value;
0204     /**< File driver identifier */
0205
0206     const char *name;
0207     /**< File driver name, must be unique */
0208
0209     haddr_t maxaddr;
0210     /**< Maximum address for file */
0211
0212     H5F_close_degree_t fc_degree;
0213     /**< File close behavior degree */
0214
0215     herr_t (*terminate)(void);
0216     /**< Shutdowns this driver */
0217
0218     hsize_t (*sb_size)(H5FD_t *file);
0219     /**< Gets the size of the private information to be stored in the superblock */
0220
0221     herr_t (*sb_encode)(H5FD_t *file, char *name /*out*/, unsigned char *p /*out*/);
0222     /**< Encodes driver information from the superblock */
0223
0224     herr_t (*sb_decode)(H5FD_t *f, const char *name, const unsigned char *p);
0225     /**< Decodes the superblock information for this driver */
0226
0227     size_t fapl_size; /**< Size of driver-specific file access properties */
0228     void *(*fapl_get)(H5FD_t *file);
0229     /**< Returns the file access property list */
0230
0231     void *(*fapl_copy)(const void *fapl);
0232     /**< Copies the file access property list */
0233
0234     herr_t (*fapl_free)(void *fapl);
0235     /**< Frees the driver-specific file access property list */
0236
0237     size_t dxpl_size;
0238     /**< Size of the transfer property list */
0239
0240     void *(*dxpl_copy)(const void *dxpl);
0241     /**< Copies the transfer property list */
0242
0243     herr_t (*dxpl_free)(void *dxpl);
0244     /**< Frees the transfer property list */
0245
0246     H5FD_t *(*open)(const char *name, unsigned flags, hid_t fapl, haddr_t maxaddr);
0247     /**< Create or open an HDF5 file of this driver */
0248
0249     herr_t (*close)(H5FD_t *file);
0250     /**< Close an HDF5 file of this driver */
0251
0252     int (*cmp)(const H5FD_t *f1, const H5FD_t *f2);
0253     /**< Compares two files belonging to this driver */
0254
0255     herr_t (*query)(const H5FD_t *f1, unsigned long *flags);
0256     /**< Sets the flags that this driver is capable of supporting */
0257
0258     herr_t (*get_type_map)(const H5FD_t *file, H5FD_mem_t *type_map);
0259     /**< Retrieves the memory type mapping for this file */
0260
0261     haddr_t (*alloc)(H5FD_t *file, H5FD_mem_t type, hid_t dxpl_id, hsize_t size);
0262     /**< Allocates file memory */
0263
0264     herr_t (*free)(H5FD_t *file, H5FD_mem_t type, hid_t dxpl_id, haddr_t addr, hsize_t size);
0265     /**< Frees the resources for this driver */
0266
0267     haddr_t (*get_eoa)(const H5FD_t *file, H5FD_mem_t type);
0268     /**< Gets the address of first byte past the addressed space */
0269
0270     herr_t (*set_eoa)(H5FD_t *file, H5FD_mem_t type, haddr_t addr);
0271     /**< Sets the end-of-address marker for the file */
0272
0273     haddr_t (*get_eof)(const H5FD_t *file, H5FD_mem_t type);
0274     /**< Gets the address of first byte past the file-end */
0275
0276     herr_t (*get_handle)(H5FD_t *file, hid_t fapl, void **file_handle);
0277     /**< Returns the file handle of this file driver */
0278
0279     herr_t (*read)(H5FD_t *file, H5FD_mem_t type, hid_t dxpl, haddr_t addr, size_t size, void *buffer);
0280     /**< Reads the specified number of bytes of data from the file beginning at the specified
0281      * address into the provided buffer, according to the specified data transfer properties  */
0282
0283     herr_t (*write)(H5FD_t *file, H5FD_mem_t type, hid_t dxpl, haddr_t addr, size_t size, const void *buffer);
0284     /**< Writes the specified number of bytes of data to the file beginning at the specified
0285      * address from the provided buffer, according to the specified data transfer properties  */
0286
0287     herr_t (*read_vector)(H5FD_t *file, hid_t dxpl, uint32_t count, H5FD_mem_t types[], haddr_t addrs[],
0288                           size_t sizes[], void *bufs[]);
0289     /**< Reads the specified length of data from the file into the provided array */
0290
0291     herr_t (*write_vector)(H5FD_t *file, hid_t dxpl, uint32_t count, H5FD_mem_t types[], haddr_t addrs[],
0292                            size_t sizes[], const void *bufs[]);
0293     /**< Writes the specified length of data in the provided array to the file at the specified offsets */
0294
0295     herr_t (*read_selection)(H5FD_t *file, H5FD_mem_t type, hid_t dxpl_id, size_t count, hid_t mem_spaces[],
0296                              hid_t file_spaces[], haddr_t offsets[], size_t element_sizes[],
0297                              void *bufs[] /*out*/);
0298     /**< */
0299
0300     herr_t (*write_selection)(H5FD_t *file, H5FD_mem_t type, hid_t dxpl_id, size_t count, hid_t mem_spaces[],
0301                               hid_t file_spaces[], haddr_t offsets[], size_t element_sizes[],
0302                               const void *bufs[] /*in*/);
0303     /**< */
0304
0305     herr_t (*flush)(H5FD_t *file, hid_t dxpl_id, hbool_t closing);
0306     /**< Flushes all data to disk */
0307
0308     herr_t (*truncate)(H5FD_t *file, hid_t dxpl_id, hbool_t closing);
0309     /**< Truncates a file */
0310
0311     herr_t (*lock)(H5FD_t *file, hbool_t rw);
0312     /**< Places an advisory lock on a file */
0313
0314     herr_t (*unlock)(H5FD_t *file);
0315     /**< Removes the existing lock on a file */
0316
0317     herr_t (*del)(const char *name, hid_t fapl);
0318     /**< Deletes a file */
0319
0320     herr_t (*ctl)(H5FD_t *file, uint64_t op_code, uint64_t flags, const void *input, void **output);
0321     /**< Performs a CTL operation */
0322
0323     H5FD_mem_t fl_map[H5FD_MEM_NTYPES];
0324     /**< Free-list map */
0325 } H5FD_class_t;
0326
0327 /**
0328  * A free list is a singly-linked list of address/size pairs.
0329  */
0330 typedef struct H5FD_free_t {
0331     haddr_t             addr;
0332     hsize_t             size;
0333     struct H5FD_free_t *next;
0334 } H5FD_free_t;
0335
0336 /**
0337  * The main datatype for each driver. Public fields common to all drivers
0338  * are declared here and the driver appends private fields in memory.
0339  */
0340 struct H5FD_t {
0341     hid_t               driver_id;     /**< Driver ID for this file   */
0342     const H5FD_class_t *cls;           /**< Constant class info       */
0343     unsigned long       fileno;        /**< File 'serial' number     */
0344     unsigned            access_flags;  /**< File access flags (from create or open) */
0345     unsigned long       feature_flags; /**< VFL Driver feature Flags */
0346     haddr_t             maxaddr;       /**< For this file, overrides class */
0347     haddr_t             base_addr;     /**< Base address for HDF5 data w/in file */
0348
0349     /* Space allocation management fields */
0350     hsize_t threshold;  /**< Threshold for alignment  */
0351     hsize_t alignment;  /**< Allocation alignment     */
0352     hbool_t paged_aggr; /**< Paged aggregation for file space is enabled or not */
0353 };
0354
0355 /* VFD initialization function */
0356 typedef hid_t (*H5FD_init_t)(void);
0357
0358 /********************/
0359 /* Public Variables */
0360 /********************/
0361
0362 /*********************/
0363 /* Public Prototypes */
0364 /*********************/
0365
0366 #ifdef __cplusplus
0367 extern "C" {
0368 #endif
0369
0370 H5_DLL hid_t   H5FDperform_init(H5FD_init_t op);
0371 H5_DLL hid_t   H5FDregister(const H5FD_class_t *cls);
0372 H5_DLL htri_t  H5FDis_driver_registered_by_name(const char *driver_name);
0373 H5_DLL htri_t  H5FDis_driver_registered_by_value(H5FD_class_value_t driver_value);
0374 H5_DLL herr_t  H5FDunregister(hid_t driver_id);
0375 H5_DLL H5FD_t *H5FDopen(const char *name, unsigned flags, hid_t fapl_id, haddr_t maxaddr);
0376 H5_DLL herr_t  H5FDclose(H5FD_t *file);
0377 H5_DLL int     H5FDcmp(const H5FD_t *f1, const H5FD_t *f2);
0378 H5_DLL herr_t  H5FDquery(const H5FD_t *f, unsigned long *flags);
0379 H5_DLL haddr_t H5FDalloc(H5FD_t *file, H5FD_mem_t type, hid_t dxpl_id, hsize_t size);
0380 H5_DLL herr_t  H5FDfree(H5FD_t *file, H5FD_mem_t type, hid_t dxpl_id, haddr_t addr, hsize_t size);
0381 H5_DLL haddr_t H5FDget_eoa(H5FD_t *file, H5FD_mem_t type);
0382 H5_DLL herr_t  H5FDset_eoa(H5FD_t *file, H5FD_mem_t type, haddr_t eoa);
0383 H5_DLL haddr_t H5FDget_eof(H5FD_t *file, H5FD_mem_t type);
0384 H5_DLL herr_t  H5FDget_vfd_handle(H5FD_t *file, hid_t fapl, void **file_handle);
0385 H5_DLL herr_t  H5FDread(H5FD_t *file, H5FD_mem_t type, hid_t dxpl_id, haddr_t addr, size_t size,
0386                         void *buf /*out*/);
0387 H5_DLL herr_t  H5FDwrite(H5FD_t *file, H5FD_mem_t type, hid_t dxpl_id, haddr_t addr, size_t size,
0388                          const void *buf);
0389 H5_DLL herr_t  H5FDread_vector(H5FD_t *file, hid_t dxpl_id, uint32_t count, H5FD_mem_t types[],
0390                                haddr_t addrs[], size_t sizes[], void *bufs[] /* out */);
0391 H5_DLL herr_t  H5FDwrite_vector(H5FD_t *file, hid_t dxpl_id, uint32_t count, H5FD_mem_t types[],
0392                                 haddr_t addrs[], size_t sizes[], const void *bufs[] /* in */);
0393 H5_DLL herr_t  H5FDread_selection(H5FD_t *file, H5FD_mem_t type, hid_t dxpl_id, uint32_t count,
0394                                   hid_t mem_spaces[], hid_t file_spaces[], haddr_t offsets[],
0395                                   size_t element_sizes[], void *bufs[] /* out */);
0396 H5_DLL herr_t  H5FDwrite_selection(H5FD_t *file, H5FD_mem_t type, hid_t dxpl_id, uint32_t count,
0397                                    hid_t mem_spaces[], hid_t file_spaces[], haddr_t offsets[],
0398                                    size_t element_sizes[], const void *bufs[]);
0399 H5_DLL herr_t  H5FDread_vector_from_selection(H5FD_t *file, H5FD_mem_t type, hid_t dxpl_id, uint32_t count,
0400                                               hid_t mem_spaces[], hid_t file_spaces[], haddr_t offsets[],
0401                                               size_t element_sizes[], void *bufs[] /* out */);
0402 H5_DLL herr_t  H5FDwrite_vector_from_selection(H5FD_t *file, H5FD_mem_t type, hid_t dxpl_id, uint32_t count,
0403                                                hid_t mem_spaces[], hid_t file_spaces[], haddr_t offsets[],
0404                                                size_t element_sizes[], const void *bufs[] /* in */);
0405 H5_DLL herr_t  H5FDread_from_selection(H5FD_t *file, H5FD_mem_t type, hid_t dxpl_id, uint32_t count,
0406                                        hid_t mem_space_ids[], hid_t file_space_ids[], haddr_t offsets[],
0407                                        size_t element_sizes[], void *bufs[] /* out */);
0408 H5_DLL herr_t  H5FDwrite_from_selection(H5FD_t *file, H5FD_mem_t type, hid_t dxpl_id, uint32_t count,
0409                                         hid_t mem_space_ids[], hid_t file_space_ids[], haddr_t offsets[],
0410                                         size_t element_sizes[], const void *bufs[] /* in */);
0411 H5_DLL herr_t  H5FDflush(H5FD_t *file, hid_t dxpl_id, hbool_t closing);
0412 H5_DLL herr_t  H5FDtruncate(H5FD_t *file, hid_t dxpl_id, hbool_t closing);
0413 H5_DLL herr_t  H5FDlock(H5FD_t *file, hbool_t rw);
0414 H5_DLL herr_t  H5FDunlock(H5FD_t *file);
0415 H5_DLL herr_t  H5FDdelete(const char *name, hid_t fapl_id);
0416 H5_DLL herr_t  H5FDctl(H5FD_t *file, uint64_t op_code, uint64_t flags, const void *input, void **output);
0417
0418 #ifdef __cplusplus
0419 }
0420 #endif
0421
0422 #endif /* H5FDdevelop_H */