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 documentation (H5M) #4259

Merged
merged 4 commits into from
Mar 28, 2024
Merged

Add documentation (H5M) #4259

Changes from 2 commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
bcb5e21
Add documentation
bmribler Mar 27, 2024
8ed5aa6
Committing clang-format changes
github-actions[bot] Mar 27, 2024
9424e3f
Remove the mentioning of specific operations in a common place.
bmribler Mar 27, 2024
74eafce
Fix incorrect statement
bmribler Mar 27, 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
154 changes: 81 additions & 73 deletions src/H5Mpublic.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,33 +32,37 @@

/* Macros defining operation IDs for map VOL callbacks (implemented using the
* "optional" VOL callback) */
#define H5VL_MAP_CREATE 1
#define H5VL_MAP_OPEN 2
#define H5VL_MAP_GET_VAL 3
#define H5VL_MAP_EXISTS 4
#define H5VL_MAP_PUT 5
#define H5VL_MAP_GET 6
#define H5VL_MAP_SPECIFIC 7
#define H5VL_MAP_OPTIONAL 8
#define H5VL_MAP_CLOSE 9
#define H5VL_MAP_CREATE 1 /**< Callback operation ID for map create */
#define H5VL_MAP_OPEN 2 /**< Callback operation ID for map open */
#define H5VL_MAP_GET_VAL 3 /**< Callback operation ID for getting an associated value from a map */
#define H5VL_MAP_EXISTS 4 /**< Callback operation ID for checking a map existence */
Copy link
Collaborator

Choose a reason for hiding this comment

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

This is used to check if a value exists in the map

#define H5VL_MAP_PUT 5 /**< Callback operation ID for putting a key-value pair to a map */
#define H5VL_MAP_GET 6 /**< Callback operation ID for map get callback */
#define H5VL_MAP_SPECIFIC 7 /**< Callback operation ID for map specific operation */
#define H5VL_MAP_OPTIONAL 8 /**< Currently unused */
#define H5VL_MAP_CLOSE 9 /**< Callback operation ID for terminating access to a map */

/*******************/
/* Public Typedefs */
/*******************/

/* types for map GET callback */
/**
* Types for map GET callback
*/
typedef enum H5VL_map_get_t {
H5VL_MAP_GET_MAPL, /* map access property list */
H5VL_MAP_GET_MCPL, /* map creation property list */
H5VL_MAP_GET_KEY_TYPE, /* key type */
H5VL_MAP_GET_VAL_TYPE, /* value type */
H5VL_MAP_GET_COUNT /* key count */
H5VL_MAP_GET_MAPL, /**< Callback operation ID for getting map access property list */
H5VL_MAP_GET_MCPL, /**< Callback operation ID for getting map creation property list */
H5VL_MAP_GET_KEY_TYPE, /**< Callback operation ID for getting the key datatype for a map */
H5VL_MAP_GET_VAL_TYPE, /**< Callback operation ID for getting the value datatype for a map */
H5VL_MAP_GET_COUNT /**< Callback operation ID for getting the number of key-value pairs stored in a map */
} H5VL_map_get_t;

/* types for map SPECIFIC callback */
/**
* Types for map SPECIFIC callback
*/
typedef enum H5VL_map_specific_t {
H5VL_MAP_ITER, /* H5Miterate */
H5VL_MAP_DELETE /* H5Mdelete */
H5VL_MAP_ITER, /**< Callback operation ID for iterating over all key-value pairs stored in the map */
H5VL_MAP_DELETE /**< Callback operation ID for deleting a key-value pair stored in the map */
} H5VL_map_specific_t;

//! <!-- [H5M_iterate_t_snip] -->
Expand All @@ -68,112 +72,116 @@ typedef enum H5VL_map_specific_t {
typedef herr_t (*H5M_iterate_t)(hid_t map_id, const void *key, void *op_data);
//! <!-- [H5M_iterate_t_snip] -->

/* Parameters for map operations */
/**
* Parameters for map operations
*/
typedef union H5VL_map_args_t {
/* H5VL_MAP_CREATE */

/** H5VL_MAP_CREATE */
struct {
H5VL_loc_params_t loc_params; /* Location parameters for object */
const char *name; /* Name of new map object */
hid_t lcpl_id; /* Link creation property list for map */
hid_t key_type_id; /* Datatype for map keys */
hid_t val_type_id; /* Datatype for map values */
hid_t mcpl_id; /* Map creation property list */
hid_t mapl_id; /* Map access property list */
void *map; /* Pointer to newly created map object (OUT) */
H5VL_loc_params_t loc_params; /**< Location parameters for object */
const char *name; /**< Name of new map object */
hid_t lcpl_id; /**< Link creation property list for map */
hid_t key_type_id; /**< Datatype for map keys */
hid_t val_type_id; /**< Datatype for map values */
hid_t mcpl_id; /**< Map creation property list */
hid_t mapl_id; /**< Map access property list */
void *map; /**< Pointer to newly created map object (OUT) */
} create;

/* H5VL_MAP_OPEN */
/** H5VL_MAP_OPEN */
struct {
H5VL_loc_params_t loc_params; /* Location parameters for object */
const char *name; /* Name of new map object */
hid_t mapl_id; /* Map access property list */
void *map; /* Pointer to newly created map object (OUT) */
H5VL_loc_params_t loc_params; /**< Location parameters for object */
const char *name; /**< Name of new map object */
hid_t mapl_id; /**< Map access property list */
void *map; /**< Pointer to newly created map object (OUT) */
} open;

/* H5VL_MAP_GET_VAL */
/** H5VL_MAP_GET_VAL */
struct {
hid_t key_mem_type_id; /* Memory datatype for key */
const void *key; /* Pointer to key */
hid_t value_mem_type_id; /* Memory datatype for value */
void *value; /* Buffer for value (OUT) */
hid_t key_mem_type_id; /**< Memory datatype for key */
const void *key; /**< Pointer to key */
hid_t value_mem_type_id; /**< Memory datatype for value */
void *value; /**< Buffer for value (OUT) */
} get_val;

/* H5VL_MAP_EXISTS */
/** H5VL_MAP_EXISTS */
struct {
hid_t key_mem_type_id; /* Memory datatype for key */
const void *key; /* Pointer to key */
hbool_t exists; /* Flag indicating whether key exists in map (OUT) */
hid_t key_mem_type_id; /**< Memory datatype for key */
const void *key; /**< Pointer to key */
hbool_t exists; /**< Flag indicating whether key exists in map (OUT) */
} exists;

/* H5VL_MAP_PUT */
/** H5VL_MAP_PUT */
struct {
hid_t key_mem_type_id; /* Memory datatype for key */
const void *key; /* Pointer to key */
hid_t value_mem_type_id; /* Memory datatype for value */
const void *value; /* Pointer to value */
hid_t key_mem_type_id; /**< Memory datatype for key */
const void *key; /**< Pointer to key */
hid_t value_mem_type_id; /**< Memory datatype for value */
const void *value; /**< Pointer to value */
} put;

/* H5VL_MAP_GET */
/** H5VL_MAP_GET */
struct {
H5VL_map_get_t get_type; /* 'get' operation to perform */
H5VL_map_get_t get_type; /**< 'get' operation to perform */

/* Parameters for each operation */
/** Parameters for each operation */
union {
/* H5VL_MAP_GET_MAPL */
/** H5VL_MAP_GET_MAPL */
struct {
hid_t mapl_id; /* Map access property list ID (OUT) */
hid_t mapl_id; /**< Get map access property list ID (OUT) */
} get_mapl;

/* H5VL_MAP_GET_MCPL */
/** H5VL_MAP_GET_MCPL */
struct {
hid_t mcpl_id; /* Map creation property list ID (OUT) */
hid_t mcpl_id; /**< Get map creation property list ID (OUT) */
} get_mcpl;

/* H5VL_MAP_GET_KEY_TYPE */
/** H5VL_MAP_GET_KEY_TYPE */
struct {
hid_t type_id; /* Datatype ID for map's keys (OUT) */
hid_t type_id; /**< Get datatype ID for map's keys (OUT) */
} get_key_type;

/* H5VL_MAP_GET_VAL_TYPE */
/** H5VL_MAP_GET_VAL_TYPE */
struct {
hid_t type_id; /* Datatype ID for map's values (OUT) */
hid_t type_id; /**< Get datatype ID for map's values (OUT) */
} get_val_type;

/* H5VL_MAP_GET_COUNT */
/** H5VL_MAP_GET_COUNT */
struct {
hsize_t count; /* # of KV pairs in map (OUT) */
hsize_t count; /**< Get number of key-value pairs in the map (OUT) */
} get_count;
} args;
} get;

/* H5VL_MAP_SPECIFIC */
/** H5VL_MAP_SPECIFIC */
struct {
H5VL_map_specific_t specific_type; /* 'specific' operation to perform */
H5VL_map_specific_t specific_type;
/**< 'specific' operation to perform, which are 'iterate' and 'del' currently */
Copy link
Collaborator

@jhendersonHDF jhendersonHDF Mar 27, 2024 •
edited
Loading

Choose a reason for hiding this comment

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

I wouldn't mention specific operations here, so that we don't forget to update this in the future. It may be better to document the specific operations themselves where their operation name/macro appears if possible.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Thanks, I fixed them.


/* Parameters for each operation */
/** Parameters for each operation */
union {
/* H5VL_MAP_ITER */
struct {
H5VL_loc_params_t loc_params; /* Location parameters for object */
hsize_t idx; /* Start/end iteration index (IN/OUT) */
hid_t key_mem_type_id; /* Memory datatype for key */
H5M_iterate_t op; /* Iteration callback routine */
void *op_data; /* Pointer to callback context */
H5VL_loc_params_t loc_params; /**< Location parameters for object */
hsize_t idx; /**< Start/end iteration index (IN/OUT) */
hid_t key_mem_type_id; /**< Memory datatype for key */
H5M_iterate_t op; /**< Iteration callback routine */
void *op_data; /**< Pointer to callback context */
} iterate;

/* H5VL_MAP_DELETE */
struct {
H5VL_loc_params_t loc_params; /* Location parameters for object */
hid_t key_mem_type_id; /* Memory datatype for key */
const void *key; /* Pointer to key */
H5VL_loc_params_t loc_params; /**< Location parameters for object */
hid_t key_mem_type_id; /**< Memory datatype for key */
const void *key; /**< Pointer to key */
} del;
} args;
} specific;

/* H5VL_MAP_OPTIONAL */
/** H5VL_MAP_OPTIONAL */
/* Unused */

/* H5VL_MAP_CLOSE */
/** H5VL_MAP_CLOSE */
/* No args */
} H5VL_map_args_t;

Expand Down
Loading