Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Add documentation (H5FD) #4269

Merged
merged 6 commits into from
Apr 1, 2024
Merged

Add documentation (H5FD) #4269

Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
4adbecd
Add documentation for H5FD
bmribler Mar 27, 2024
8f8864b
Committing clang-format changes
github-actions[bot] Mar 27, 2024
62991af
Update src/H5FDdevelop.h
bmribler Mar 28, 2024
4ef51cf
Update src/H5FDdevelop.h
bmribler Mar 28, 2024
d89b4e2
Update src/H5FDdevelop.h
bmribler Mar 28, 2024
d1a353f
Update src/H5FDdevelop.h
bmribler Mar 28, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
249 changes: 178 additions & 71 deletions src/H5FDdevelop.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand All @@ -124,7 +148,7 @@
H5FD_MEM_SUPER /*ohdr*/ \
}

/*
/**
* A free-list map which segregates requests into `raw' or `meta' data
* pools.
*/
Expand All @@ -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.
*/
Expand All @@ -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 */
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Shouldn't these be before the struct member?

Copy link
Contributor Author

@bmribler bmribler Mar 28, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

These are inline, so should be after, I believe. Because some have long comment and have to be on the next line, so I just wanted to make them all consistent.

} 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 */
Expand Down
Loading