diff options
Diffstat (limited to 'src/H5FDpublic.h')
| -rw-r--r-- | src/H5FDpublic.h | 667 |
1 files changed, 343 insertions, 324 deletions
diff --git a/src/H5FDpublic.h b/src/H5FDpublic.h index 514d1bf..221f569 100644 --- a/src/H5FDpublic.h +++ b/src/H5FDpublic.h @@ -6,389 +6,408 @@ * This file is part of HDF5. The full HDF5 copyright notice, including * * terms governing use, modification, and redistribution, is contained in * * the COPYING file, which can be found at the root of the source code * - * distribution tree, or in https://support.hdfgroup.org/ftp/HDF5/releases. * + * distribution tree, or in https://www.hdfgroup.org/licenses. * * If you do not have access to either file, you may request a copy from * * help@hdfgroup.org. * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ /* - * Programmer: Robb Matzke <matzke@llnl.gov> + * Programmer: Robb Matzke * Monday, July 26, 1999 */ -#ifndef _H5FDpublic_H -#define _H5FDpublic_H +#ifndef H5FDpublic_H +#define H5FDpublic_H -#include "H5public.h" -#include "H5Fpublic.h" /*for H5F_close_degree_t */ +/* Public headers needed by this file */ +#include "H5public.h" /* Generic Functions */ +#include "H5Fpublic.h" /* Files */ -#define H5_HAVE_VFL 1 /*define a convenient app feature test*/ -#define H5FD_VFD_DEFAULT 0 /* Default VFL driver value */ +/*****************/ +/* Public Macros */ +/*****************/ -/* Types of allocation requests: see H5Fpublic.h */ -typedef enum H5F_mem_t H5FD_mem_t; +#define H5FD_VFD_DEFAULT 0 /* Default VFL driver value */ -/* Map "fractal heap" header blocks to 'ohdr' type file memory, since its - * a fair amount of work to add a new kind of file memory and they are similar - * enough to object headers and probably too minor to deserve their own type. - * - * Map "fractal heap" indirect blocks to 'ohdr' type file memory, since they - * are similar to fractal heap header blocks. - * - * Map "fractal heap" direct blocks to 'lheap' type file memory, since they - * will be replacing local heaps. - * - * Map "fractal heap" 'huge' objects to 'draw' type file memory, since they - * represent large objects that are directly stored in the file. - * - * -QAK +/* VFD identifier values + * These are H5FD_class_value_t values, NOT hid_t values! */ -#define H5FD_MEM_FHEAP_HDR H5FD_MEM_OHDR -#define H5FD_MEM_FHEAP_IBLOCK H5FD_MEM_OHDR -#define H5FD_MEM_FHEAP_DBLOCK H5FD_MEM_LHEAP -#define H5FD_MEM_FHEAP_HUGE_OBJ H5FD_MEM_DRAW +#define H5_VFD_INVALID ((H5FD_class_value_t)(-1)) +#define H5_VFD_SEC2 ((H5FD_class_value_t)(0)) +#define H5_VFD_CORE ((H5FD_class_value_t)(1)) +#define H5_VFD_LOG ((H5FD_class_value_t)(2)) +#define H5_VFD_FAMILY ((H5FD_class_value_t)(3)) +#define H5_VFD_MULTI ((H5FD_class_value_t)(4)) +#define H5_VFD_STDIO ((H5FD_class_value_t)(5)) +#define H5_VFD_SPLITTER ((H5FD_class_value_t)(6)) +#ifdef H5_HAVE_PARALLEL +#define H5_VFD_MPIO ((H5FD_class_value_t)(7)) +#endif +#ifdef H5_HAVE_DIRECT +#define H5_VFD_DIRECT ((H5FD_class_value_t)(8)) +#endif +#ifdef H5_HAVE_MIRROR_VFD +#define H5_VFD_MIRROR ((H5FD_class_value_t)(9)) +#endif +#ifdef H5_HAVE_LIBHDFS +#define H5_VFD_HDFS ((H5FD_class_value_t)(10)) +#endif +#ifdef H5_HAVE_ROS3_VFD +#define H5_VFD_ROS3 ((H5FD_class_value_t)(11)) +#endif -/* Map "free space" header blocks to 'ohdr' type file memory, since its - * a fair amount of work to add a new kind of file memory and they are similar - * enough to object headers and probably too minor to deserve their own type. - * - * Map "free space" serialized sections to 'lheap' type file memory, since they - * are similar enough to local heap info. +/* VFD IDs below this value are reserved for library use. */ +#define H5_VFD_RESERVED 256 + +/* Maximum VFD ID */ +#define H5_VFD_MAX 65535 + +/* Define VFL driver features that can be enabled on a per-driver basis */ +/* These are returned with the 'query' function pointer in H5FD_class_t */ +/* + * Defining H5FD_FEAT_AGGREGATE_METADATA for a VFL driver means that + * the library will attempt to allocate a larger block for metadata and + * then sub-allocate each metadata request from that larger block. + */ +#define H5FD_FEAT_AGGREGATE_METADATA 0x00000001 +/* + * Defining H5FD_FEAT_ACCUMULATE_METADATA for a VFL driver means that + * the library will attempt to cache metadata as it is written to the file + * and build up a larger block of metadata to eventually pass to the VFL + * 'write' routine. * - * -QAK + * Distinguish between updating the metadata accumulator on writes and + * reads. This is particularly (perhaps only, even) important for MPI-I/O + * where we guarantee that writes are collective, but reads may not be. + * If we were to allow the metadata accumulator to be written during a + * read operation, the application would hang. + */ +#define H5FD_FEAT_ACCUMULATE_METADATA_WRITE 0x00000002 +#define H5FD_FEAT_ACCUMULATE_METADATA_READ 0x00000004 +#define H5FD_FEAT_ACCUMULATE_METADATA \ + (H5FD_FEAT_ACCUMULATE_METADATA_WRITE | H5FD_FEAT_ACCUMULATE_METADATA_READ) +/* + * Defining H5FD_FEAT_DATA_SIEVE for a VFL driver means that + * the library will attempt to cache raw data as it is read from/written to + * a file in a "data seive" buffer. See Rajeev Thakur's papers: + * http://www.mcs.anl.gov/~thakur/papers/romio-coll.ps.gz + * http://www.mcs.anl.gov/~thakur/papers/mpio-high-perf.ps.gz + */ +#define H5FD_FEAT_DATA_SIEVE 0x00000008 +/* + * Defining H5FD_FEAT_AGGREGATE_SMALLDATA for a VFL driver means that + * the library will attempt to allocate a larger block for "small" raw data + * and then sub-allocate "small" raw data requests from that larger block. + */ +#define H5FD_FEAT_AGGREGATE_SMALLDATA 0x00000010 +/* + * Defining H5FD_FEAT_IGNORE_DRVRINFO for a VFL driver means that + * the library will ignore the driver info that is encoded in the file + * for the VFL driver. (This will cause the driver info to be eliminated + * from the file when it is flushed/closed, if the file is opened R/W). + */ +#define H5FD_FEAT_IGNORE_DRVRINFO 0x00000020 +/* + * Defining the H5FD_FEAT_DIRTY_DRVRINFO_LOAD for a VFL driver means that + * the library will mark the driver info dirty when the file is opened + * R/W. This will cause the driver info to be re-encoded when the file + * is flushed/closed. */ -#define H5FD_MEM_FSPACE_HDR H5FD_MEM_OHDR -#define H5FD_MEM_FSPACE_SINFO H5FD_MEM_LHEAP +#define H5FD_FEAT_DIRTY_DRVRINFO_LOAD 0x00000040 +/* + * Defining H5FD_FEAT_POSIX_COMPAT_HANDLE for a VFL driver means that + * the handle for the VFD (returned with the 'get_handle' callback) is + * of type 'int' and is compatible with POSIX I/O calls. + */ +#define H5FD_FEAT_POSIX_COMPAT_HANDLE 0x00000080 +/* + * Defining H5FD_FEAT_HAS_MPI for a VFL driver means that + * the driver makes use of MPI communication and code may retrieve + * communicator/rank information from it + */ +#define H5FD_FEAT_HAS_MPI 0x00000100 +/* + * Defining the H5FD_FEAT_ALLOCATE_EARLY for a VFL driver will force + * the library to use the H5D_ALLOC_TIME_EARLY on dataset create + * instead of the default H5D_ALLOC_TIME_LATE + */ +#define H5FD_FEAT_ALLOCATE_EARLY 0x00000200 +/* + * Defining H5FD_FEAT_ALLOW_FILE_IMAGE for a VFL driver means that + * the driver is able to use a file image in the fapl as the initial + * contents of a file. + */ +#define H5FD_FEAT_ALLOW_FILE_IMAGE 0x00000400 +/* + * Defining H5FD_FEAT_CAN_USE_FILE_IMAGE_CALLBACKS for a VFL driver + * means that the driver is able to use callbacks to make a copy of the + * image to store in memory. + */ +#define H5FD_FEAT_CAN_USE_FILE_IMAGE_CALLBACKS 0x00000800 +/* + * Defining H5FD_FEAT_SUPPORTS_SWMR_IO for a VFL driver means that the + * driver supports the single-writer/multiple-readers I/O pattern. + */ +#define H5FD_FEAT_SUPPORTS_SWMR_IO 0x00001000 +/* + * Defining H5FD_FEAT_USE_ALLOC_SIZE for a VFL driver + * means that the library will just pass the allocation size to the + * the driver's allocation callback which will eventually handle alignment. + * This is specifically used for the multi/split driver. + */ +#define H5FD_FEAT_USE_ALLOC_SIZE 0x00002000 +/* + * Defining H5FD_FEAT_PAGED_AGGR for a VFL driver + * means that the driver needs special file space mapping for paged aggregation. + * This is specifically used for the multi/split driver. + */ +#define H5FD_FEAT_PAGED_AGGR 0x00004000 +/* + * Defining H5FD_FEAT_DEFAULT_VFD_COMPATIBLE for a VFL driver + * that creates a file which is compatible with the default VFD. + * Generally, this means that the VFD creates a single file that follows + * the canonical HDF5 file format. + * Regarding the Splitter VFD specifically, only drivers with this flag + * enabled may be used as the Write-Only (W/O) channel driver. + */ +#define H5FD_FEAT_DEFAULT_VFD_COMPATIBLE 0x00008000 +/* + * Defining H5FD_FEAT_MEMMANAGE for a VFL driver means that + * the driver uses special memory management routines or wishes + * to do memory management in a specific manner. Therefore, HDF5 + * should request that the driver handle any memory management + * operations when appropriate. + */ +#define H5FD_FEAT_MEMMANAGE 0x00010000 + +/* ctl function definitions: */ +#define H5FD_CTL_OPC_RESERVED 512 /* Opcodes below this value are reserved for library use */ +#define H5FD_CTL_OPC_EXPER_MIN \ + H5FD_CTL_OPC_RESERVED /* Minimum opcode value available for experimental use \ + */ +#define H5FD_CTL_OPC_EXPER_MAX \ + (H5FD_CTL_OPC_RESERVED + 511) /* Maximum opcode value available for experimental use */ -/* Map "shared object header message" master table to 'ohdr' type file memory, - * since its a fair amount of work to add a new kind of file memory and they are - * similar enough to object headers and probably too minor to deserve their own - * type. +/* ctl function op codes: */ +#define H5FD_CTL__INVALID_OPCODE 0 +#define H5FD_CTL__TEST_OPCODE 1 +#define H5FD_CTL__GET_MPI_COMMUNICATOR_OPCODE 2 +#define H5FD_CTL__GET_MPI_RANK_OPCODE 3 +#define H5FD_CTL__GET_MPI_SIZE_OPCODE 4 +#define H5FD_CTL__MEM_ALLOC 5 +#define H5FD_CTL__MEM_FREE 6 +#define H5FD_CTL__MEM_COPY 7 + +/* ctl function flags: */ + +/* Definitions: * - * Map "shared object header message" indices to 'btree' type file memory, - * since they are similar enough to B-tree nodes. + * WARNING: While the following definitions of Terminal + * and Passthrough VFDs should be workable for now, they + * have to be adjusted as our use cases for VFDs expand. + * + * JRM -- 8/4/21 * - * -QAK - */ -#define H5FD_MEM_SOHM_TABLE H5FD_MEM_OHDR -#define H5FD_MEM_SOHM_INDEX H5FD_MEM_BTREE - -/* Map "extensible array" header blocks to 'ohdr' type file memory, since its - * a fair amount of work to add a new kind of file memory and they are similar - * enough to object headers and probably too minor to deserve their own type. * - * Map "extensible array" index blocks to 'ohdr' type file memory, since they - * are similar to extensible array header blocks. + * Terminal VFD: Lowest VFD in the VFD stack through + * which all VFD calls pass. Note that this definition + * is situational. For example, the sec2 VFD is typically + * terminal. However, in the context of the family file + * driver, it is not -- the family file driver is the + * bottom VFD through which all VFD calls pass, and thus + * it is terminal. * - * Map "extensible array" super blocks to 'btree' type file memory, since they - * are similar enough to B-tree nodes. + * Similarly, on the splitter VFD, a sec2 VFD on the + * R/W channel is terminal, but a sec2 VFD on the W/O + * channel is not. * - * Map "extensible array" data blocks & pages to 'lheap' type file memory, since - * they are similar enough to local heap info. * - * -QAK + * Pass through VFD: Any VFD that relays all VFD calls + * (with the possible exception of some non-I/O related + * calls) to underlying VFD(s). */ -#define H5FD_MEM_EARRAY_HDR H5FD_MEM_OHDR -#define H5FD_MEM_EARRAY_IBLOCK H5FD_MEM_OHDR -#define H5FD_MEM_EARRAY_SBLOCK H5FD_MEM_BTREE -#define H5FD_MEM_EARRAY_DBLOCK H5FD_MEM_LHEAP -#define H5FD_MEM_EARRAY_DBLK_PAGE H5FD_MEM_LHEAP -/* Map "fixed array" header blocks to 'ohdr' type file memory, since its - * a fair amount of work to add a new kind of file memory and they are similar - * enough to object headers and probably too minor to deserve their own type. +/* Unknown op codes should be ignored silently unless the + * H5FD_CTL__FAIL_IF_UNKNOWN_FLAG is set. * - * Map "fixed array" data blocks & pages to 'lheap' type file memory, since - * they are similar enough to local heap info. + * On terminal VFDs, unknown op codes should generate an + * error unconditionally if this flag is set. * + * On pass through VFDs, unknown op codes should be routed + * to the underlying VFD(s) as indicated by any routing + * flags. In the absence of such flags, the VFD should + * generate an error. */ -#define H5FD_MEM_FARRAY_HDR H5FD_MEM_OHDR -#define H5FD_MEM_FARRAY_DBLOCK H5FD_MEM_LHEAP -#define H5FD_MEM_FARRAY_DBLK_PAGE H5FD_MEM_LHEAP +#define H5FD_CTL__FAIL_IF_UNKNOWN_FLAG 0x0001 -/* - * A free-list map which maps all types of allocation requests to a single - * free list. This is useful for drivers that don't really care about - * keeping different requests segregated in the underlying file and which - * want to make most efficient reuse of freed memory. The use of the - * H5FD_MEM_SUPER free list is arbitrary. +/* The H5FD_CTL__ROUTE_TO_TERMINAL_VFD_FLAG is used only + * by non-ternminal VFDs, and only applies to unknown + * opcodes. (known op codes should be handled as + * appropriate.) + * + * If this flag is set for an unknown op code, that + * op code should be passed to the next VFD down + * the VFD stack en-route to the terminal VFD. + * If that VFD does not support the ctl call, the + * pass through VFD should fail or succeed as directed + * by the H5FD_CTL__FAIL_IF_UNKNOWN_FLAG. */ -#define H5FD_FLMAP_SINGLE { \ - H5FD_MEM_SUPER, /*default*/ \ - H5FD_MEM_SUPER, /*super*/ \ - H5FD_MEM_SUPER, /*btree*/ \ - H5FD_MEM_SUPER, /*draw*/ \ - H5FD_MEM_SUPER, /*gheap*/ \ - H5FD_MEM_SUPER, /*lheap*/ \ - H5FD_MEM_SUPER /*ohdr*/ \ -} +#define H5FD_CTL__ROUTE_TO_TERMINAL_VFD_FLAG 0x0002 -/* - * A free-list map which segregates requests into `raw' or `meta' data - * pools. - */ -#define H5FD_FLMAP_DICHOTOMY { \ - H5FD_MEM_SUPER, /*default*/ \ - H5FD_MEM_SUPER, /*super*/ \ - H5FD_MEM_SUPER, /*btree*/ \ - H5FD_MEM_DRAW, /*draw*/ \ - H5FD_MEM_DRAW, /*gheap*/ \ - H5FD_MEM_SUPER, /*lheap*/ \ - H5FD_MEM_SUPER /*ohdr*/ \ -} +/*******************/ +/* Public Typedefs */ +/*******************/ /* - * The default free list map which causes each request type to use it's own - * free-list. + * File driver identifiers. + * + * Values 0 through 255 are for drivers defined by the HDF5 library. + * Values 256 through 511 are available for testing new drivers. + * Subsequent values should be obtained from the HDF5 development + * team at mailto:help@hdfgroup.org. */ -#define H5FD_FLMAP_DEFAULT { \ - H5FD_MEM_DEFAULT, /*default*/ \ - H5FD_MEM_DEFAULT, /*super*/ \ - H5FD_MEM_DEFAULT, /*btree*/ \ - H5FD_MEM_DEFAULT, /*draw*/ \ - H5FD_MEM_DEFAULT, /*gheap*/ \ - H5FD_MEM_DEFAULT, /*lheap*/ \ - H5FD_MEM_DEFAULT /*ohdr*/ \ -} +typedef int H5FD_class_value_t; +/* Types of allocation requests: see H5Fpublic.h */ +typedef enum H5F_mem_t H5FD_mem_t; -/* Define VFL driver features that can be enabled on a per-driver basis */ -/* These are returned with the 'query' function pointer in H5FD_class_t */ - /* - * Defining H5FD_FEAT_AGGREGATE_METADATA for a VFL driver means that - * the library will attempt to allocate a larger block for metadata and - * then sub-allocate each metadata request from that larger block. - */ -#define H5FD_FEAT_AGGREGATE_METADATA 0x00000001 - /* - * Defining H5FD_FEAT_ACCUMULATE_METADATA for a VFL driver means that - * the library will attempt to cache metadata as it is written to the file - * and build up a larger block of metadata to eventually pass to the VFL - * 'write' routine. - * - * Distinguish between updating the metadata accumulator on writes and - * reads. This is particularly (perhaps only, even) important for MPI-I/O - * where we guarantee that writes are collective, but reads may not be. - * If we were to allow the metadata accumulator to be written during a - * read operation, the application would hang. - */ -#define H5FD_FEAT_ACCUMULATE_METADATA_WRITE 0x00000002 -#define H5FD_FEAT_ACCUMULATE_METADATA_READ 0x00000004 -#define H5FD_FEAT_ACCUMULATE_METADATA (H5FD_FEAT_ACCUMULATE_METADATA_WRITE|H5FD_FEAT_ACCUMULATE_METADATA_READ) - /* - * Defining H5FD_FEAT_DATA_SIEVE for a VFL driver means that - * the library will attempt to cache raw data as it is read from/written to - * a file in a "data seive" buffer. See Rajeev Thakur's papers: - * http://www.mcs.anl.gov/~thakur/papers/romio-coll.ps.gz - * http://www.mcs.anl.gov/~thakur/papers/mpio-high-perf.ps.gz - */ -#define H5FD_FEAT_DATA_SIEVE 0x00000008 - /* - * Defining H5FD_FEAT_AGGREGATE_SMALLDATA for a VFL driver means that - * the library will attempt to allocate a larger block for "small" raw data - * and then sub-allocate "small" raw data requests from that larger block. - */ -#define H5FD_FEAT_AGGREGATE_SMALLDATA 0x00000010 - /* - * Defining H5FD_FEAT_IGNORE_DRVRINFO for a VFL driver means that - * the library will ignore the driver info that is encoded in the file - * for the VFL driver. (This will cause the driver info to be eliminated - * from the file when it is flushed/closed, if the file is opened R/W). - */ -#define H5FD_FEAT_IGNORE_DRVRINFO 0x00000020 - /* - * Defining the H5FD_FEAT_DIRTY_DRVRINFO_LOAD for a VFL driver means that - * the library will mark the driver info dirty when the file is opened - * R/W. This will cause the driver info to be re-encoded when the file - * is flushed/closed. - */ -#define H5FD_FEAT_DIRTY_DRVRINFO_LOAD 0x00000040 - /* - * Defining H5FD_FEAT_POSIX_COMPAT_HANDLE for a VFL driver means that - * the handle for the VFD (returned with the 'get_handle' callback) is - * of type 'int' and is compatible with POSIX I/O calls. - */ -#define H5FD_FEAT_POSIX_COMPAT_HANDLE 0x00000080 - /* - * Defining H5FD_FEAT_HAS_MPI for a VFL driver means that - * the driver makes use of MPI communication and code may retrieve - * communicator/rank information from it - */ -#define H5FD_FEAT_HAS_MPI 0x00000100 - /* - * Defining the H5FD_FEAT_ALLOCATE_EARLY for a VFL driver will force - * the library to use the H5D_ALLOC_TIME_EARLY on dataset create - * instead of the default H5D_ALLOC_TIME_LATE - */ -#define H5FD_FEAT_ALLOCATE_EARLY 0x00000200 - /* - * Defining H5FD_FEAT_ALLOW_FILE_IMAGE for a VFL driver means that - * the driver is able to use a file image in the fapl as the initial - * contents of a file. - */ -#define H5FD_FEAT_ALLOW_FILE_IMAGE 0x00000400 - /* - * Defining H5FD_FEAT_CAN_USE_FILE_IMAGE_CALLBACKS for a VFL driver - * means that the driver is able to use callbacks to make a copy of the - * image to store in memory. - */ -#define H5FD_FEAT_CAN_USE_FILE_IMAGE_CALLBACKS 0x00000800 - /* - * Defining H5FD_FEAT_SUPPORTS_SWMR_IO for a VFL driver means that the - * driver supports the single-writer/multiple-readers I/O pattern. - */ -#define H5FD_FEAT_SUPPORTS_SWMR_IO 0x00001000 - /* - * Defining H5FD_FEAT_USE_ALLOC_SIZE for a VFL driver - * means that the library will just pass the allocation size to the - * the driver's allocation callback which will eventually handle alignment. - * This is specifically used for the multi/split driver. - */ -#define H5FD_FEAT_USE_ALLOC_SIZE 0x00002000 - /* - * Defining H5FD_FEAT_PAGED_AGGR for a VFL driver - * means that the driver needs special file space mapping for paged aggregation. - * This is specifically used for the multi/split driver. - */ -#define H5FD_FEAT_PAGED_AGGR 0x00004000 - /* - * Defining H5FD_FEAT_DEFAULT_VFD_COMPATIBLE for a VFL driver - * that creates a file which is compatible with the default VFD. - * Generally, this means that the VFD creates a single file that follows - * the canonical HDF5 file format. - */ -#define H5FD_FEAT_DEFAULT_VFD_COMPATIBLE 0x00008000 - - -/* Forward declaration */ -typedef struct H5FD_t H5FD_t; - -/* Class information for each file driver */ -typedef struct H5FD_class_t { - const char *name; - haddr_t maxaddr; - H5F_close_degree_t fc_degree; - herr_t (*terminate)(void); - hsize_t (*sb_size)(H5FD_t *file); - herr_t (*sb_encode)(H5FD_t *file, char *name/*out*/, - unsigned char *p/*out*/); - herr_t (*sb_decode)(H5FD_t *f, const char *name, const unsigned char *p); - size_t fapl_size; - void * (*fapl_get)(H5FD_t *file); - void * (*fapl_copy)(const void *fapl); - herr_t (*fapl_free)(void *fapl); - size_t dxpl_size; - void * (*dxpl_copy)(const void *dxpl); - herr_t (*dxpl_free)(void *dxpl); - H5FD_t *(*open)(const char *name, unsigned flags, hid_t fapl, - haddr_t maxaddr); - herr_t (*close)(H5FD_t *file); - int (*cmp)(const H5FD_t *f1, const H5FD_t *f2); - herr_t (*query)(const H5FD_t *f1, unsigned long *flags); - herr_t (*get_type_map)(const H5FD_t *file, H5FD_mem_t *type_map); - haddr_t (*alloc)(H5FD_t *file, H5FD_mem_t type, hid_t dxpl_id, hsize_t size); - herr_t (*free)(H5FD_t *file, H5FD_mem_t type, hid_t dxpl_id, - haddr_t addr, hsize_t size); - haddr_t (*get_eoa)(const H5FD_t *file, H5FD_mem_t type); - herr_t (*set_eoa)(H5FD_t *file, H5FD_mem_t type, haddr_t addr); - haddr_t (*get_eof)(const H5FD_t *file, H5FD_mem_t type); - herr_t (*get_handle)(H5FD_t *file, hid_t fapl, void**file_handle); - herr_t (*read)(H5FD_t *file, H5FD_mem_t type, hid_t dxpl, - haddr_t addr, size_t size, void *buffer); - herr_t (*write)(H5FD_t *file, H5FD_mem_t type, hid_t dxpl, - haddr_t addr, size_t size, const void *buffer); - herr_t (*flush)(H5FD_t *file, hid_t dxpl_id, hbool_t closing); - herr_t (*truncate)(H5FD_t *file, hid_t dxpl_id, hbool_t closing); - herr_t (*lock)(H5FD_t *file, hbool_t rw); - herr_t (*unlock)(H5FD_t *file); - H5FD_mem_t fl_map[H5FD_MEM_NTYPES]; -} H5FD_class_t; - -/* A free list is a singly-linked list of address/size pairs. */ -typedef struct H5FD_free_t { - haddr_t addr; - hsize_t size; - struct H5FD_free_t *next; -} H5FD_free_t; - -/* - * The main datatype for each driver. Public fields common to all drivers - * are declared here and the driver appends private fields in memory. +/** + * Define enum for the source of file image callbacks */ -struct H5FD_t { - hid_t driver_id; /*driver ID for this file */ - const H5FD_class_t *cls; /*constant class info */ - unsigned long fileno; /* File 'serial' number */ - unsigned access_flags; /* File access flags (from create or open) */ - unsigned long feature_flags; /* VFL Driver feature Flags */ - haddr_t maxaddr; /* For this file, overrides class */ - haddr_t base_addr; /* Base address for HDF5 data w/in file */ - - /* Space allocation management fields */ - hsize_t threshold; /* Threshold for alignment */ - hsize_t alignment; /* Allocation alignment */ - hbool_t paged_aggr; /* Paged aggregation for file space is enabled or not */ -}; - -/* Define enum for the source of file image callbacks */ +//! <!-- [H5FD_file_image_op_t_snip] --> typedef enum { H5FD_FILE_IMAGE_OP_NO_OP, - H5FD_FILE_IMAGE_OP_PROPERTY_LIST_SET, + H5FD_FILE_IMAGE_OP_PROPERTY_LIST_SET, + /**< Passed to the \p image_malloc and \p image_memcpy callbacks when a + * file image buffer is to be copied while being set in a file access + * property list (FAPL)*/ H5FD_FILE_IMAGE_OP_PROPERTY_LIST_COPY, + /**< Passed to the \p image_malloc and \p image_memcpy callbacks + * when a file image buffer is to be copied when a FAPL is copied*/ H5FD_FILE_IMAGE_OP_PROPERTY_LIST_GET, + /**<Passed to the \p image_malloc and \p image_memcpy callbacks when + * a file image buffer is to be copied while being retrieved from a FAPL*/ H5FD_FILE_IMAGE_OP_PROPERTY_LIST_CLOSE, + /**<Passed to the \p image_free callback when a file image + * buffer is to be released during a FAPL close operation*/ H5FD_FILE_IMAGE_OP_FILE_OPEN, + /**<Passed to the \p image_malloc and + * \p image_memcpy callbackswhen a + * file image buffer is to be copied during a file open operation \n + * While the file image being opened will typically be copied from a + * FAPL, this need not always be the case. For example, the core file + * driver, also known as the memory file driver, takes its initial + * image from a file.*/ H5FD_FILE_IMAGE_OP_FILE_RESIZE, + /**<Passed to the \p image_realloc callback when a file driver needs + * to resize an image buffer*/ H5FD_FILE_IMAGE_OP_FILE_CLOSE + /**<Passed to the \p image_free callback when an image buffer is to + * be released during a file close operation*/ } H5FD_file_image_op_t; +//! <!-- [H5FD_file_image_op_t_snip] --> -/* Define structure to hold file image callbacks */ +/** + * Define structure to hold file image callbacks + */ +//! <!-- [H5FD_file_image_callbacks_t_snip] --> typedef struct { - void *(*image_malloc)(size_t size, H5FD_file_image_op_t file_image_op, - void *udata); - void *(*image_memcpy)(void *dest, const void *src, size_t size, - H5FD_file_image_op_t file_image_op, void *udata); - void *(*image_realloc)(void *ptr, size_t size, - H5FD_file_image_op_t file_image_op, void *udata); - herr_t (*image_free)(void *ptr, H5FD_file_image_op_t file_image_op, + /** + * \param[in] size Size in bytes of the file image buffer to allocate + * \param[in] file_image_op A value from H5FD_file_image_op_t indicating + * the operation being performed on the file image + * when this callback is invoked + * \param[in] udata Value passed in in the H5Pset_file_image_callbacks + * parameter \p udata + */ + //! <!-- [image_malloc_snip] --> + void *(*image_malloc)(size_t size, H5FD_file_image_op_t file_image_op, void *udata); + //! <!-- [image_malloc_snip] --> + /** + * \param[in] dest Address of the destination buffer + * \param[in] src Address of the source buffer + * \param[in] file_image_op A value from #H5FD_file_image_op_t indicating + * the operation being performed on the file image + * when this callback is invoked + * \param[in] udata Value passed in in the H5Pset_file_image_callbacks + * parameter \p udata + */ + //! <!-- [image_memcpy_snip] --> + void *(*image_memcpy)(void *dest, const void *src, size_t size, H5FD_file_image_op_t file_image_op, void *udata); - void *(*udata_copy)(void *udata); - herr_t (*udata_free)(void *udata); + //! <!-- [image_memcpy_snip] --> + /** + * \param[in] ptr Pointer to the buffer being reallocated + * \param[in] file_image_op A value from #H5FD_file_image_op_t indicating + * the operation being performed on the file image + * when this callback is invoked + * \param[in] udata Value passed in in the H5Pset_file_image_callbacks + * parameter \p udata + */ + //! <!-- [image_realloc_snip] --> + void *(*image_realloc)(void *ptr, size_t size, H5FD_file_image_op_t file_image_op, void *udata); + //! <!-- [image_realloc_snip] --> + /** + * \param[in] udata Value passed in in the H5Pset_file_image_callbacks + * parameter \p udata + */ + //! <!-- [image_free_snip] --> + herr_t (*image_free)(void *ptr, H5FD_file_image_op_t file_image_op, void *udata); + //! <!-- [image_free_snip] --> + /** + * \param[in] udata Value passed in in the H5Pset_file_image_callbacks + * parameter \p udata + */ + //! <!-- [udata_copy_snip] --> + void *(*udata_copy)(void *udata); + //! <!-- [udata_copy_snip] --> + /** + * \param[in] udata Value passed in in the H5Pset_file_image_callbacks + * parameter \p udata + */ + //! <!-- [udata_free_snip] --> + herr_t (*udata_free)(void *udata); + //! <!-- [udata_free_snip] --> + /** + * \brief The final field in the #H5FD_file_image_callbacks_t struct, + * provides a pointer to user-defined data. This pointer will be + * passed to the image_malloc, image_memcpy, image_realloc, and + * image_free callbacks. Define udata as NULL if no user-defined + * data is provided. + */ void *udata; } H5FD_file_image_callbacks_t; +//! <!-- [H5FD_file_image_callbacks_t_snip] --> + +/** + * Define structure to hold "ctl memory copy" parameters + */ +//! <!-- [H5FD_ctl_memcpy_args_t_snip] --> +typedef struct H5FD_ctl_memcpy_args_t { + void * dstbuf; /**< Destination buffer */ + hsize_t dst_off; /**< Offset within destination buffer */ + const void *srcbuf; /**< Source buffer */ + hsize_t src_off; /**< Offset within source buffer */ + size_t len; /**< Length of data to copy from source buffer */ +} H5FD_ctl_memcpy_args_t; +//! <!-- [H5FD_ctl_memcpy_args_t_snip] --> + +/********************/ +/* Public Variables */ +/********************/ + +/*********************/ +/* Public Prototypes */ +/*********************/ #ifdef __cplusplus extern "C" { #endif /* Function prototypes */ -H5_DLL hid_t H5FDregister(const H5FD_class_t *cls); -H5_DLL herr_t H5FDunregister(hid_t driver_id); -H5_DLL H5FD_t *H5FDopen(const char *name, unsigned flags, hid_t fapl_id, - haddr_t maxaddr); -H5_DLL herr_t H5FDclose(H5FD_t *file); -H5_DLL int H5FDcmp(const H5FD_t *f1, const H5FD_t *f2); -H5_DLL int H5FDquery(const H5FD_t *f, unsigned long *flags); -H5_DLL haddr_t H5FDalloc(H5FD_t *file, H5FD_mem_t type, hid_t dxpl_id, hsize_t size); -H5_DLL herr_t H5FDfree(H5FD_t *file, H5FD_mem_t type, hid_t dxpl_id, - haddr_t addr, hsize_t size); -H5_DLL haddr_t H5FDget_eoa(H5FD_t *file, H5FD_mem_t type); -H5_DLL herr_t H5FDset_eoa(H5FD_t *file, H5FD_mem_t type, haddr_t eoa); -H5_DLL haddr_t H5FDget_eof(H5FD_t *file, H5FD_mem_t type); -H5_DLL herr_t H5FDget_vfd_handle(H5FD_t *file, hid_t fapl, void**file_handle); -H5_DLL herr_t H5FDread(H5FD_t *file, H5FD_mem_t type, hid_t dxpl_id, - haddr_t addr, size_t size, void *buf/*out*/); -H5_DLL herr_t H5FDwrite(H5FD_t *file, H5FD_mem_t type, hid_t dxpl_id, - haddr_t addr, size_t size, const void *buf); -H5_DLL herr_t H5FDflush(H5FD_t *file, hid_t dxpl_id, hbool_t closing); -H5_DLL herr_t H5FDtruncate(H5FD_t *file, hid_t dxpl_id, hbool_t closing); -H5_DLL herr_t H5FDlock(H5FD_t *file, hbool_t rw); -H5_DLL herr_t H5FDunlock(H5FD_t *file); - /* Allows querying a VFD ID for features before the file is opened */ -H5_DLL herr_t H5FDdriver_query(hid_t driver_id, unsigned long *flags/*out*/); +H5_DLL herr_t H5FDdriver_query(hid_t driver_id, unsigned long *flags /*out*/); #ifdef __cplusplus } #endif #endif - |