Skip to content

Commit

Permalink
Onion VFD header cleanup (#2337) (#2339)
Browse files Browse the repository at this point in the history 
* 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>
  • Loading branch information
@derobins @github-actions
derobins and github-actions[bot] authored Dec 21, 2022
1 parent 3a44e72 commit 1d7160f
Show file tree
Hide file tree
Showing 3 changed files with 85 additions and 112 deletions.
10 changes: 1 addition & 9 deletions src/H5FDonion.c
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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")

Expand Down Expand Up @@ -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;

Expand Down Expand Up @@ -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 */
Expand Down Expand Up @@ -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;
Expand Down
178 changes: 80 additions & 98 deletions src/H5FDonion.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.
*
* + <Remaining bits reserved>
*
* 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
Expand All @@ -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);

Expand All @@ -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);

Expand All @@ -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);

Expand Down
9 changes: 4 additions & 5 deletions src/H5FDonion_header.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.
*/
Expand Down

0 comments on commit 1d7160f

Please sign in to comment.