mirror of
https://github.com/HDFGroup/hdf5.git
synced 2025-02-05 15:42:32 +08:00
Add documentation (H5FD) (#4269)
This commit is contained in:
bmribler
GitHub
parent
dc69e39f65
commit
f24e8113a3
@ -25,7 +25,9 @@
|
||||
/* Public Macros */
|
||||
/*****************/
|
||||
|
||||
/* H5FD_class_t struct version */
|
||||
/**
|
||||
* Version of the file driver struct, H5FD_class_t
|
||||
*/
|
||||
#define H5FD_CLASS_VERSION 0x01 /* File driver struct version */
|
||||
|
||||
/* Map "fractal heap" header blocks to 'ohdr' type file memory, since its
|
||||
@ -43,70 +45,92 @@
|
||||
*
|
||||
* -QAK
|
||||
*/
|
||||
#define H5FD_MEM_FHEAP_HDR H5FD_MEM_OHDR
|
||||
#define H5FD_MEM_FHEAP_IBLOCK H5FD_MEM_OHDR
|
||||
#define H5FD_MEM_FHEAP_DBLOCK H5FD_MEM_LHEAP
|
||||
|
||||
/**
|
||||
* Fractal heap header block; it is mapped to 'ohdr' type file memory to
|
||||
* benefit from their similarity.
|
||||
*/
|
||||
#define H5FD_MEM_FHEAP_HDR H5FD_MEM_OHDR
|
||||
/**
|
||||
* Fractal heap indirect block; it is mapped to 'ohdr' type file memory
|
||||
* because the indirect blocks are similar to fractal heap header blocks.
|
||||
*/
|
||||
#define H5FD_MEM_FHEAP_IBLOCK H5FD_MEM_OHDR
|
||||
/**
|
||||
* Fractal heap direct block; it is mapped to 'lheap' type file memory,
|
||||
* because the fractal heap direct blocks will be replacing local heaps.
|
||||
*/
|
||||
#define H5FD_MEM_FHEAP_DBLOCK H5FD_MEM_LHEAP
|
||||
/**
|
||||
* Fractal heap 'huge' object; it is mapped to 'draw' type file memory because
|
||||
* the fractal heap 'huge' objects represent large objects that are directly
|
||||
* stored in the file.
|
||||
*/
|
||||
#define H5FD_MEM_FHEAP_HUGE_OBJ H5FD_MEM_DRAW
|
||||
|
||||
/* 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.
|
||||
*
|
||||
* -QAK
|
||||
/**
|
||||
* Free space header blocks; it is mapped to 'ohdr' type file memory to
|
||||
* benefit from their similarity.
|
||||
*/
|
||||
#define H5FD_MEM_FSPACE_HDR H5FD_MEM_OHDR
|
||||
/**
|
||||
* Free space serialized section; it is mapped to 'lheap' type file memory
|
||||
* because it is similar enough to local heap info.
|
||||
*/
|
||||
#define H5FD_MEM_FSPACE_HDR H5FD_MEM_OHDR
|
||||
#define H5FD_MEM_FSPACE_SINFO H5FD_MEM_LHEAP
|
||||
|
||||
/* 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.
|
||||
*
|
||||
* Map "shared object header message" indices to 'btree' type file memory,
|
||||
* since they are similar enough to B-tree nodes.
|
||||
*
|
||||
* -QAK
|
||||
/**
|
||||
* Shared object header message master table; it is mapped to 'ohdr' type file
|
||||
* memory to benefit from their similarity.
|
||||
*/
|
||||
#define H5FD_MEM_SOHM_TABLE H5FD_MEM_OHDR
|
||||
/**
|
||||
* Shared object header message index; it is mapped to 'btree' type file memory
|
||||
* because the indices are similar enough to B-tree nodes.
|
||||
*/
|
||||
#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.
|
||||
*
|
||||
* Map "extensible array" super blocks to 'btree' type file memory, since they
|
||||
* are similar enough to B-tree nodes.
|
||||
*
|
||||
* Map "extensible array" data blocks & pages to 'lheap' type file memory, since
|
||||
* they are similar enough to local heap info.
|
||||
*
|
||||
* -QAK
|
||||
/**
|
||||
* Extensible array header block; it is mapped to 'ohdr' type file memory to
|
||||
* benefit from their similarity.
|
||||
*/
|
||||
#define H5FD_MEM_EARRAY_HDR H5FD_MEM_OHDR
|
||||
/**
|
||||
* Extensible array index block; it is mapped to 'ohdr' type file memory because
|
||||
* these index blocks are similar to extensible array header blocks.
|
||||
*/
|
||||
#define H5FD_MEM_EARRAY_IBLOCK H5FD_MEM_OHDR
|
||||
/**
|
||||
* Extensible array super block; it is mappend to 'btree' type file memory
|
||||
* because the indices are similar enough to B-tree nodes.
|
||||
*/
|
||||
#define H5FD_MEM_EARRAY_SBLOCK H5FD_MEM_BTREE
|
||||
/**
|
||||
* Extensible array data block; it is mapped to 'lheap' type file memory
|
||||
* because it is similar enough to local heap info.
|
||||
*/
|
||||
#define H5FD_MEM_EARRAY_DBLOCK H5FD_MEM_LHEAP
|
||||
/**
|
||||
* Extensible array data block & page; it is mapped to 'lheap' type file memory
|
||||
* because it is similar enough to local heap info.
|
||||
*/
|
||||
#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.
|
||||
*
|
||||
* Map "fixed array" data blocks & pages to 'lheap' type file memory, since
|
||||
* they are similar enough to local heap info.
|
||||
*
|
||||
/**
|
||||
* Fixed array header block; it is mapped to 'ohdr' type file memory to
|
||||
* benefit their similarity.
|
||||
*/
|
||||
#define H5FD_MEM_FARRAY_HDR H5FD_MEM_OHDR
|
||||
/**
|
||||
* Fixed array data block; it is mapped to 'lheap' type file memory
|
||||
* because it is similar enough to local heap info.
|
||||
*/
|
||||
#define H5FD_MEM_FARRAY_DBLOCK H5FD_MEM_LHEAP
|
||||
/**
|
||||
* Fixed array data block & page; it is mapped to 'lheap' type file memory
|
||||
* because it is similar enough to local heap info.
|
||||
*/
|
||||
#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
|
||||
|
||||
/*
|
||||
/**
|
||||
* 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
|
||||
@ -124,7 +148,7 @@
|
||||
H5FD_MEM_SUPER /*ohdr*/ \
|
||||
}
|
||||
|
||||
/*
|
||||
/**
|
||||
* A free-list map which segregates requests into `raw' or `meta' data
|
||||
* pools.
|
||||
*/
|
||||
@ -139,7 +163,7 @@
|
||||
H5FD_MEM_SUPER /*ohdr*/ \
|
||||
}
|
||||
|
||||
/*
|
||||
/**
|
||||
* The default free list map which causes each request type to use it's own
|
||||
* free-list.
|
||||
*/
|
||||
@ -161,80 +185,163 @@
|
||||
/* Forward declaration */
|
||||
typedef struct H5FD_t H5FD_t;
|
||||
|
||||
/* Class information for each file driver */
|
||||
/**
|
||||
* Class information for each file driver
|
||||
*/
|
||||
typedef struct H5FD_class_t {
|
||||
unsigned version; /**< File driver class struct version number */
|
||||
unsigned version;
|
||||
/**< File driver class struct version number */
|
||||
|
||||
H5FD_class_value_t value;
|
||||
const char *name;
|
||||
haddr_t maxaddr;
|
||||
/**< File driver identifier */
|
||||
|
||||
const char *name;
|
||||
/**< File driver name, must be unique */
|
||||
|
||||
haddr_t maxaddr;
|
||||
/**< Maximum address for file */
|
||||
|
||||
H5F_close_degree_t fc_degree;
|
||||
/**< File close behavior degree */
|
||||
|
||||
herr_t (*terminate)(void);
|
||||
/**< Shutdowns this driver */
|
||||
|
||||
hsize_t (*sb_size)(H5FD_t *file);
|
||||
/**< Gets the size of the private information to be stored in the superblock */
|
||||
|
||||
herr_t (*sb_encode)(H5FD_t *file, char *name /*out*/, unsigned char *p /*out*/);
|
||||
/**< Encodes driver information from the superblock */
|
||||
|
||||
herr_t (*sb_decode)(H5FD_t *f, const char *name, const unsigned char *p);
|
||||
size_t fapl_size;
|
||||
/**< Decodes the superblock information for this driver */
|
||||
|
||||
size_t fapl_size; /**< Size of driver-specific file access properties */
|
||||
void *(*fapl_get)(H5FD_t *file);
|
||||
/**< Returns the file access property list */
|
||||
|
||||
void *(*fapl_copy)(const void *fapl);
|
||||
/**< Copies the file access property list */
|
||||
|
||||
herr_t (*fapl_free)(void *fapl);
|
||||
/**< Frees the driver-specific file access property list */
|
||||
|
||||
size_t dxpl_size;
|
||||
/**< Size of the transfer property list */
|
||||
|
||||
void *(*dxpl_copy)(const void *dxpl);
|
||||
/**< Copies the transfer property list */
|
||||
|
||||
herr_t (*dxpl_free)(void *dxpl);
|
||||
/**< Frees the transfer property list */
|
||||
|
||||
H5FD_t *(*open)(const char *name, unsigned flags, hid_t fapl, haddr_t maxaddr);
|
||||
/**< Create or open an HDF5 file of this driver */
|
||||
|
||||
herr_t (*close)(H5FD_t *file);
|
||||
/**< Close an HDF5 file of this driver */
|
||||
|
||||
int (*cmp)(const H5FD_t *f1, const H5FD_t *f2);
|
||||
/**< Compares two files belonging to this driver */
|
||||
|
||||
herr_t (*query)(const H5FD_t *f1, unsigned long *flags);
|
||||
/**< Sets the flags that this driver is capable of supporting */
|
||||
|
||||
herr_t (*get_type_map)(const H5FD_t *file, H5FD_mem_t *type_map);
|
||||
/**< Retrieves the memory type mapping for this file */
|
||||
|
||||
haddr_t (*alloc)(H5FD_t *file, H5FD_mem_t type, hid_t dxpl_id, hsize_t size);
|
||||
/**< Allocates file memory */
|
||||
|
||||
herr_t (*free)(H5FD_t *file, H5FD_mem_t type, hid_t dxpl_id, haddr_t addr, hsize_t size);
|
||||
/**< Frees the resources for this driver */
|
||||
|
||||
haddr_t (*get_eoa)(const H5FD_t *file, H5FD_mem_t type);
|
||||
/**< Gets the address of first byte past the addressed space */
|
||||
|
||||
herr_t (*set_eoa)(H5FD_t *file, H5FD_mem_t type, haddr_t addr);
|
||||
/**< Sets the end-of-address marker for the file */
|
||||
|
||||
haddr_t (*get_eof)(const H5FD_t *file, H5FD_mem_t type);
|
||||
/**< Gets the address of first byte past the file-end */
|
||||
|
||||
herr_t (*get_handle)(H5FD_t *file, hid_t fapl, void **file_handle);
|
||||
/**< Returns the file handle of this file driver */
|
||||
|
||||
herr_t (*read)(H5FD_t *file, H5FD_mem_t type, hid_t dxpl, haddr_t addr, size_t size, void *buffer);
|
||||
/**< Reads the specified number of bytes of data from the file beginning at the specified
|
||||
* address into the provided buffer, according to the specified data transfer properties */
|
||||
|
||||
herr_t (*write)(H5FD_t *file, H5FD_mem_t type, hid_t dxpl, haddr_t addr, size_t size, const void *buffer);
|
||||
/**< Writes the specified number of bytes of data to the file beginning at the specified
|
||||
* address from the provided buffer, according to the specified data transfer properties */
|
||||
|
||||
herr_t (*read_vector)(H5FD_t *file, hid_t dxpl, uint32_t count, H5FD_mem_t types[], haddr_t addrs[],
|
||||
size_t sizes[], void *bufs[]);
|
||||
/**< Reads the specified length of data from the file into the provided array */
|
||||
|
||||
herr_t (*write_vector)(H5FD_t *file, hid_t dxpl, uint32_t count, H5FD_mem_t types[], haddr_t addrs[],
|
||||
size_t sizes[], const void *bufs[]);
|
||||
/**< Writes the specified length of data in the provided array to the file at the specified offsets */
|
||||
|
||||
herr_t (*read_selection)(H5FD_t *file, H5FD_mem_t type, hid_t dxpl_id, size_t count, hid_t mem_spaces[],
|
||||
hid_t file_spaces[], haddr_t offsets[], size_t element_sizes[],
|
||||
void *bufs[] /*out*/);
|
||||
/**< */
|
||||
|
||||
herr_t (*write_selection)(H5FD_t *file, H5FD_mem_t type, hid_t dxpl_id, size_t count, hid_t mem_spaces[],
|
||||
hid_t file_spaces[], haddr_t offsets[], size_t element_sizes[],
|
||||
const void *bufs[] /*in*/);
|
||||
/**< */
|
||||
|
||||
herr_t (*flush)(H5FD_t *file, hid_t dxpl_id, hbool_t closing);
|
||||
/**< Flushes all data to disk */
|
||||
|
||||
herr_t (*truncate)(H5FD_t *file, hid_t dxpl_id, hbool_t closing);
|
||||
/**< Truncates a file */
|
||||
|
||||
herr_t (*lock)(H5FD_t *file, hbool_t rw);
|
||||
/**< Places an advisory lock on a file */
|
||||
|
||||
herr_t (*unlock)(H5FD_t *file);
|
||||
/**< Removes the existing lock on a file */
|
||||
|
||||
herr_t (*del)(const char *name, hid_t fapl);
|
||||
/**< Deletes a file */
|
||||
|
||||
herr_t (*ctl)(H5FD_t *file, uint64_t op_code, uint64_t flags, const void *input, void **output);
|
||||
/**< Performs a CTL operation */
|
||||
|
||||
H5FD_mem_t fl_map[H5FD_MEM_NTYPES];
|
||||
/**< Free-list map */
|
||||
} H5FD_class_t;
|
||||
|
||||
/* A free list is a singly-linked list of address/size pairs. */
|
||||
/**
|
||||
* 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.
|
||||
*/
|
||||
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 */
|
||||
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 */
|
||||
hsize_t threshold; /**< Threshold for alignment */
|
||||
hsize_t alignment; /**< Allocation alignment */
|
||||
hbool_t paged_aggr; /**< Paged aggregation for file space is enabled or not */
|
||||
};
|
||||
|
||||
/* VFD initialization function */
|
||||
|
||||
Loading…
Reference in New Issue
Block a user