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

Add Doxygen to H5FDmirror.h #4158

Merged
merged 1 commit into from
Mar 16, 2024
Merged

Add Doxygen to H5FDmirror.h #4158

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
77 changes: 52 additions & 25 deletions src/H5FDmirror.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,46 +25,54 @@
/** Identifier for the mirror VFD */
#define H5FD_MIRROR_VALUE H5_VFD_MIRROR

#ifdef __cplusplus
extern "C" {
#endif
/** Magic number to identify the H5FD_mirror_fapl_t struct */
#define H5FD_MIRROR_FAPL_MAGIC 0xF8DD514C

/* ============================================================================
* Mirror VFD use and operation.
* ============================================================================
/**
* The version number of the H5FD_mirror_fapl_t configuration
* structure for the #H5FD_MIRROR driver
*/
#define H5FD_MIRROR_CURR_FAPL_T_VERSION 1

/* ---------------------------------------------------------------------------
* Structure: H5FD_mirror_fapl_t
/** Max size of the remote_ip array in H5FD_mirror_fapl_t */
#define H5FD_MIRROR_MAX_IP_LEN 32
Copy link
Member

Choose a reason for hiding this comment

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

https://stackoverflow.com/questions/1076714/max-length-for-client-ip-address

Copy link
Member Author

Choose a reason for hiding this comment

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

I'll update that in a separate PR


/**
*\struct H5FD_mirror_fapl_t
* \brief Configuration structure for H5Pset_fapl_mirror() / H5Pget_fapl_mirror()
*
* Used to pass configuration information to the Mirror VFD.
* Populate components as appropriate and pass structure pointer to
* `H5Pset_fapl_mirror()`.
* \details H5FD_mirror_fapl_t is a public structure that is used to pass
* configuration data to the #H5FD_MIRROR driver via a File Access
* Property List. A pointer to an instance of this structure is
* a parameter to H5Pset_fapl_mirror() and H5Pget_fapl_mirror().
*
* `magic` (uint32_t)
* \var uint32_t H5FD_mirror_fapl_t::magic
* Semi-unique number to sanity-check pointers to this structure type.
* MUST equal H5FD_MIRROR_FAPL_MAGIC to be considered valid.
* Must equal H5FD_MIRROR_FAPL_MAGIC to be considered valid.
*
* `version` (uint32_t)
* Indicates expected components of the structure.
* \var uint32_t H5FD_mirror_fapl_t::version
* Version number of the H5FD_mirror_fapl_t structure. Any instance passed
* to H5Pset_fapl_mirror() / H5Pget_fapl_mirror() must have a recognized version
* number or an error will be raised. Currently, this field should be set
* to #H5FD_MIRROR_CURR_FAPL_T_VERSION.
*
* `handshake_port (int)
* Port number to expect to reach the "Mirror Server" on the remote host.
* \var int H5FD_mirror_fapl_t::handshake_port
* Port number on the remote host.
*
* `remote_ip` (char[])
* IP address string of "Mirror Server" remote host.
* ---------------------------------------------------------------------------
* \var char H5FD_mirror_fapl_t::remote_ip[H5FD_MIRROR_MAX_IP_LEN + 1]
* IP address string of the remote host.
*/
#define H5FD_MIRROR_FAPL_MAGIC 0xF8DD514C
#define H5FD_MIRROR_CURR_FAPL_T_VERSION 1
#define H5FD_MIRROR_MAX_IP_LEN 32
typedef struct H5FD_mirror_fapl_t {
uint32_t magic;
uint32_t version;
int handshake_port;
char remote_ip[H5FD_MIRROR_MAX_IP_LEN + 1];
} H5FD_mirror_fapl_t;

#ifdef __cplusplus
extern "C" {
#endif

/** @private
*
* \brief Private initializer for the mirror VFD
Expand All @@ -74,14 +82,33 @@ H5_DLL hid_t H5FD_mirror_init(void);
/**
* \ingroup FAPL
*
* \todo Add missing documentation
* \brief Queries a File Access Property List for #H5FD_MIRROR file driver properties
*
* \fapl_id
* \param[out] fa_out Pointer to #H5FD_MIRROR driver configuration structure
* \returns \herr_t
*
* \details H5Pget_fapl_mirror() queries the #H5FD_MIRROR driver properties as set
* by H5Pset_fapl_mirror().
*
* \since 1.10.7
*/
H5_DLL herr_t H5Pget_fapl_mirror(hid_t fapl_id, H5FD_mirror_fapl_t *fa_out);

/**
* \ingroup FAPL
*
* \todo Add missing documentation
* \brief Modifies the file access property list to use the #H5FD_MIRROR driver
*
* \fapl_id
* \param[in] fa Pointer to #H5FD_MIRROR driver configuration structure
*
* \returns \herr_t
*
* \details H5Pset_fapl_mirror() modifies the file access property list to use the
* #H5FD_MIRROR driver.
*
* \since 1.10.7
*/
H5_DLL herr_t H5Pset_fapl_mirror(hid_t fapl_id, H5FD_mirror_fapl_t *fa);

Expand Down
Loading