From 1d7160f01632d20301af136cf9d2d927e1c1c94c Mon Sep 17 00:00:00 2001 From: Dana Robinson <43805+derobins@users.noreply.github.com> Date: Wed, 21 Dec 2022 11:47:29 -0800 Subject: Onion VFD header cleanup (#2337) (#2339) * Partial work towards cleaning up the onion VFD code * Committing clang-format changes * A few minor tweaks to the onion VFD public header Co-authored-by: github-actions <41898282+github-actions[bot]@users.noreply.github.com> Co-authored-by: github-actions <41898282+github-actions[bot]@users.noreply.github.com> --- src/H5FDonion.c | 10 +-- src/H5FDonion.h | 178 ++++++++++++++++++++++--------------------------- src/H5FDonion_header.h | 9 ++- 3 files changed, 85 insertions(+), 112 deletions(-) diff --git a/src/H5FDonion.c b/src/H5FDonion.c index 904f2cc..1c81870 100644 --- a/src/H5FDonion.c +++ b/src/H5FDonion.c @@ -577,8 +577,6 @@ H5FD__onion_close(H5FD_t *_file) HGOTO_ERROR(H5E_VFL, H5E_WRITEERROR, FAIL, "Can't write updated header to backing store") } } - else if (H5FD_ONION_STORE_TARGET_H5 == file->fa.store_target) - HGOTO_ERROR(H5E_VFL, H5E_UNSUPPORTED, FAIL, "hdf5 store-target not supported") else HGOTO_ERROR(H5E_VFL, H5E_BADVALUE, FAIL, "invalid history target") @@ -704,8 +702,6 @@ H5FD__onion_create_truncate_onion(H5FD_onion_t *file, const char *filename, cons rec = &file->curr_rev_record; hdr->flags = H5FD_ONION_HEADER_FLAG_WRITE_LOCK; - if (H5FD_ONION_FAPL_INFO_CREATE_FLAG_ENABLE_DIVERGENT_HISTORY & file->fa.creation_flags) - hdr->flags |= H5FD_ONION_HEADER_FLAG_DIVERGENT_HISTORY; if (H5FD_ONION_FAPL_INFO_CREATE_FLAG_ENABLE_PAGE_ALIGNMENT & file->fa.creation_flags) hdr->flags |= H5FD_ONION_HEADER_FLAG_PAGE_ALIGNMENT; @@ -955,9 +951,7 @@ H5FD__onion_open(const char *filename, unsigned flags, hid_t fapl_id, haddr_t ma } /* Check for unsupported target values */ - if (H5FD_ONION_STORE_TARGET_H5 == fa->store_target) - HGOTO_ERROR(H5E_ARGS, H5E_UNSUPPORTED, NULL, "same-file storage not implemented") - else if (H5FD_ONION_STORE_TARGET_ONION != fa->store_target) + if (H5FD_ONION_STORE_TARGET_ONION != fa->store_target) HGOTO_ERROR(H5E_ARGS, H5E_BADVALUE, NULL, "invalid store target") /* Allocate space for the file struct */ @@ -1056,8 +1050,6 @@ H5FD__onion_open(const char *filename, unsigned flags, hid_t fapl_id, haddr_t ma new_open = true; - if (H5FD_ONION_FAPL_INFO_CREATE_FLAG_ENABLE_DIVERGENT_HISTORY & file->fa.creation_flags) - hdr->flags |= H5FD_ONION_HEADER_FLAG_DIVERGENT_HISTORY; if (H5FD_ONION_FAPL_INFO_CREATE_FLAG_ENABLE_PAGE_ALIGNMENT & file->fa.creation_flags) { hdr->flags |= H5FD_ONION_HEADER_FLAG_PAGE_ALIGNMENT; file->align_history_on_pages = TRUE; diff --git a/src/H5FDonion.h b/src/H5FDonion.h index 0e605d0..09b290e 100644 --- a/src/H5FDonion.h +++ b/src/H5FDonion.h @@ -21,117 +21,93 @@ #define H5FD_ONION (H5FDperform_init(H5FD_onion_init)) #define H5FD_ONION_VALUE H5_VFD_ONION -/* Current version of the fapl info struct */ +/** + * Current version of the onion VFD fapl info struct. + */ #define H5FD_ONION_FAPL_INFO_VERSION_CURR 1 -/* Flag to open a file that has a locked header (after crashes, for example) */ -#define H5FD_ONION_FAPL_INFO_FLAG_FORCE_OPEN 1 - -/* Flag to enable opening older revisions in write mode, creating a tree */ -#define H5FD_ONION_FAPL_INFO_CREATE_FLAG_ENABLE_DIVERGENT_HISTORY 0x1 - -/* Flag to require page alignment of onion revision data */ -#define H5FD_ONION_FAPL_INFO_CREATE_FLAG_ENABLE_PAGE_ALIGNMENT 0x2 +#define H5FD_ONION_FAPL_INFO_CREATE_FLAG_ENABLE_PAGE_ALIGNMENT \ + (0x0001u) /**< \ + * Onion history metadata will align to page_size. \ + * Partial pages of unused space will occur in the file, \ + * but may improve read performance from the backing store \ + * on some systems. \ + * If disabled (0), padding will not be inserted to align \ + * to page boundaries. \ + */ -/* Max length of a comment - * The buffer is defined to be this size + 1 to handle the NUL +/** + * Max length of a comment. + * The buffer is defined to be this size + 1 to handle the NUL. */ #define H5FD_ONION_FAPL_INFO_COMMENT_MAX_LEN 255 -/* Indicates that you want the latest revision */ +/** + * Indicates that you want the latest revision. + */ #define H5FD_ONION_FAPL_INFO_REVISION_ID_LATEST UINT64_MAX +/** + * Indicates how the new onion data will be stored. + */ typedef enum H5FD_onion_target_file_constant_t { - H5FD_ONION_STORE_TARGET_H5, /* Onion history as part of HDF5 file */ - H5FD_ONION_STORE_TARGET_ONION, /* Separate, single "onion" file */ + H5FD_ONION_STORE_TARGET_ONION, /**< + * Onion history is stored in a single, separate "onion + * file". Shares filename and path as hdf5 file (if any), + * with only a different filename extension. + */ } H5FD_onion_target_file_constant_t; -/*----------------------------------------------------------------------------- - * Structure H5FD_onion_fapl_info_t - * - * Purpose: Encapsulate info for the Onion driver FAPL entry. - * - * version: Future-proofing identifier. Informs struct membership. - * Must equal H5FD_ONION_FAPL_VERSION_CURR to be considered valid. - * - * backing_fapl_id: - * Backing or 'child' FAPL ID to handle I/O with the - * underlying backing store. If the onion data is stored as a - * separate file, it must use the same backing driver as the - * original file. - * - * page_size: Size of the amended data pages. If opening an existing file, - * must equal the existing page size or zero. If creating a new - * file or an initial revision of an existing file, must be a - * power of 2. - * - * store_target: - * Enumerated/defined value identifying where the history data is - * stored, either in the same file (appended to HDF5 data) or a - * separate file. Other options may be added in later versions. - * - * + H5FD_ONION_FAPL_STORE_MODE_SEPARATE_SINGLE (1) - * Onion history is stored in a single, separate "onion - * file". Shares filename and path as hdf5 file (if any), - * with only a different filename extension. - * - * revision_num: Which revision to open. Must be 0 (the original file) or the - * revision number of an existing revision. - * Revision ID -1 is reserved to open the most recently-created - * revision in history. - * - * force_write_open: - * Flag to ignore the write-lock flag in the onion data - * and attempt to open the file write-only anyway. - * This may be relevant if, for example, the library crashed - * while the file was open in write mode and the write-lock - * flag was not cleared. - * Must equal H5FD_ONION_FAPL_FLAG_FORCE_OPEN to enable. - * - * creation_flags: - * Flag used only when instantiating an Onion file. - * If the relevant bit is set to a nonzero value, its feature - * will be enabled. - * - * + H5FD_ONION_FAPL_CREATE_FLAG_ENABLE_DIVERGENT_HISTORY - * (1, bit 1) - * User will be allowed to open arbitrary revisions - * in write mode. - * If disabled (0), only the most recent revision may be - * opened for amendment. - * - * + H5FD_ONION_FAPL_CREATE_FLAG_ENABLE_PAGE_ALIGNMENT (2, bit 2) - * Onion history metadata will align to page_size. - * Partial pages of unused space will occur in the file, - * but may improve read performance from the backing store - * on some systems. - * If disabled (0), padding will not be inserted to align - * to page boundaries. - * - * + - * - * comment: User-supplied NULL-terminated comment for a revision to be - * written. - * Cannot be longer than H5FD_ONION_FAPL_COMMENT_MAX_LEN. - * Ignored if part of a FAPL used to open in read mode. - * - * The comment for a revision may be modified prior to committing - * to the revision (closing the file and writing the record) - * with a call to H5FDfctl(). - * This H5FDfctl overwrite may be used to exceed constraints of - * maximum string length and the NULL-terminator requirement. - * - *----------------------------------------------------------------------------- +/** + * Stores fapl information for creating onion VFD files. */ typedef struct H5FD_onion_fapl_info_t { - uint8_t version; - hid_t backing_fapl_id; - uint32_t page_size; - H5FD_onion_target_file_constant_t store_target; - uint64_t revision_num; - uint8_t force_write_open; - uint8_t creation_flags; - char comment[H5FD_ONION_FAPL_INFO_COMMENT_MAX_LEN + 1]; + uint8_t version; /**< + * Future-proofing identifier. Informs struct membership. + * Must equal H5FD_ONION_FAPL_VERSION_CURR to be considered valid. + */ + hid_t backing_fapl_id; /**< + * Backing or 'child' FAPL ID to handle I/O with the + * underlying backing store. It must use the same backing driver as the + * original file. + */ + uint32_t page_size; /**< + * page_size: Size of the amended data pages. If opening an existing file, + * must equal the existing page size or zero. If creating a new + * file or an initial revision of an existing file, must be a + * power of 2. + * + */ + H5FD_onion_target_file_constant_t store_target; /**< + * Identifies where the history data is stored. + */ + uint64_t revision_num; /**< + * Which revision to open. Valid values are 0 (the original file) or the + * revision number of an existing revision. + * H5FD_ONION_FAPL_INFO_REVISION_ID_LATEST refers to the most + * recently-created revision in the history. + */ + uint8_t force_write_open; /**< + * Flag to ignore the write-lock flag in the onion data + * and attempt to open the file write-only anyway. + * This may be relevant if, for example, the library crashed + * while the file was open in write mode and the write-lock + * flag was not cleared. + * Must equal H5FD_ONION_FAPL_FLAG_FORCE_OPEN to enable. + * + */ + uint8_t creation_flags; /**< + * Flag used only when instantiating an onion file. + * If the relevant bit is set to a nonzero value, its feature + * will be enabled. + */ + char comment[H5FD_ONION_FAPL_INFO_COMMENT_MAX_LEN + + 1]; /**< + * User-supplied NULL-terminated comment for a revision to be + * written. + * Cannot be longer than H5FD_ONION_FAPL_COMMENT_MAX_LEN. + * Ignored if part of a FAPL used to open in read mode. + */ } H5FD_onion_fapl_info_t; #ifdef __cplusplus @@ -154,6 +130,8 @@ H5_DLL hid_t H5FD_onion_init(void); * \details H5Pget_fapl_onion() retrieves the structure H5FD_onion_fapl_info_t * from the file access property list that is set for the onion VFD * driver. + * + * \since 1.14.0 */ H5_DLL herr_t H5Pget_fapl_onion(hid_t fapl_id, H5FD_onion_fapl_info_t *fa_out); @@ -171,6 +149,8 @@ H5_DLL herr_t H5Pget_fapl_onion(hid_t fapl_id, H5FD_onion_fapl_info_t *fa_out); * \details H5Pset_fapl_onion() sets the structure H5FD_onion_fapl_info_t * for the file access property list that is set for the onion VFD * driver. + * + * \since 1.14.0 */ H5_DLL herr_t H5Pset_fapl_onion(hid_t fapl_id, const H5FD_onion_fapl_info_t *fa); @@ -190,6 +170,8 @@ H5_DLL herr_t H5Pset_fapl_onion(hid_t fapl_id, const H5FD_onion_fapl_info_t *fa) * for an onion file. It takes the file name and file access property * list that is set for the onion VFD driver. * + * + * \since 1.14.0 */ H5_DLL herr_t H5FDonion_get_revision_count(const char *filename, hid_t fapl_id, uint64_t *revision_count); diff --git a/src/H5FDonion_header.h b/src/H5FDonion_header.h index deb0d96..f8dd739 100644 --- a/src/H5FDonion_header.h +++ b/src/H5FDonion_header.h @@ -23,11 +23,10 @@ #define H5FD_ONION_ENCODED_SIZE_HEADER 40 /* Flags must align exactly one per bit, up to 24 bits */ -#define H5FD_ONION_HEADER_FLAG_WRITE_LOCK 0x1 -#define H5FD_ONION_HEADER_FLAG_DIVERGENT_HISTORY 0x2 -#define H5FD_ONION_HEADER_FLAG_PAGE_ALIGNMENT 0x4 -#define H5FD_ONION_HEADER_SIGNATURE "OHDH" -#define H5FD_ONION_HEADER_VERSION_CURR 1 +#define H5FD_ONION_HEADER_FLAG_WRITE_LOCK 0x1 +#define H5FD_ONION_HEADER_FLAG_PAGE_ALIGNMENT 0x2 +#define H5FD_ONION_HEADER_SIGNATURE "OHDH" +#define H5FD_ONION_HEADER_VERSION_CURR 1 /* In-memory representation of the on-store onion history file header. */ -- cgit v0.12