diff options
Diffstat (limited to 'hl/src/H5PTpublic.h')
| -rw-r--r-- | hl/src/H5PTpublic.h | 416 |
1 files changed, 416 insertions, 0 deletions
diff --git a/hl/src/H5PTpublic.h b/hl/src/H5PTpublic.h index d74baa5..b881b25 100644 --- a/hl/src/H5PTpublic.h +++ b/hl/src/H5PTpublic.h @@ -18,19 +18,201 @@ extern "C" { #endif +/**\defgroup H5PT Packet Table + * + * <em>Creating and manipulating HDF5 datasets to support append- + * and read-only operations on table data (H5PT)</em> + * + * The HDF5 Packet Table API is designed to allow records to be + * appended to and read from a table. Packet Table datasets are + * chunked, allowing them to grow as needed. + * + * The Packet Table API, with the H5PT prefix, is not to be confused with + * the H5TB Table API (H5TB prefix). The H5TB APIs are stateless + * (H5TB Tables do not need to be opened or closed) but H5PT Packet Tables + * require less performance overhead. Also, H5TB Tables support insertions + * and deletions, while H5PT Packet Tables support only append operations. + * H5TB functions should not be called on tables created with the + * H5PT API, or vice versa. + * + * Packet Tables are datasets in an HDF5 file, so while their contents + * should not be changed outside of the H5PT API calls, the datatypes of + * Packet Tables can be queried using \ref H5Dget_type. + * Packet Tables can also be given attributes using the normal HDF5 APIs. + * + * \note \Bold{Programming hints:} + * \note The following line includes the HDF5 Packet Table package, H5PT, + * in C applications: + * \code #include "hdf5_hl.h" \endcode + * Without this include, an application will not have access to + * these functions. + * + * - \ref H5PTappend + * \n Appends packets to the end of a packet table. + * - \ref H5PTclose + * \n Closes an open packet table. + * - \ref H5PTcreate + * \n Creates a packet table to store fixed-length + * or variable-length packets. + * - \ref H5PTcreate_fl + * \n Creates a packet table to store fixed-length packets. + * - \ref H5PTcreate_index + * \n Resets a packet table's index to the first packet. + * - \ref H5PTfree_vlen_buff + * \n Releases memory allocated in the process of + * reading variable-length packets. + * - \ref H5PTget_dataset + * \n Returns the backend dataset of this packet table. + * - \ref H5PTget_index + * \n Gets the current record index for a packet table + * - \ref H5PTget_next + * \n Reads packets from a packet table starting at the + * current index. + * - \ref H5PTget_num_packets + * \n Returns the number of packets in a packet table. + * - \ref H5PTget_type + * \n Returns the backend datatype of this packet table. + * - \ref H5PTis_valid + * \n Determines whether an identifier points to a packet table. + * - \ref H5PTis_varlen + * \n Determines whether a packet table contains variable-length + * or fixed-length packets. + * - \ref H5PTopen + * \n Opens an existing packet table. + * - \ref H5PTread_packets + * \n Reads a number of packets from a packet table. + * - \ref H5PTset_index + * \n Sets a packet table's index. + * . + * + */ + /*------------------------------------------------------------------------- * Create/Open/Close functions *------------------------------------------------------------------------- */ /* NOTE: H5PTcreate is replacing H5PTcreate_fl for better name due to the removal of H5PTcreate_vl. H5PTcreate_fl may be retired in 1.8.19. */ + +/** + * -------------------------------------------------------------------------- + * \ingroup H5PT + * + * \brief Creates a packet table to store fixed-length or + * variable-length packets. + * + * \fg_loc_id + * \param[in] dset_name The name of the packet table to create + * \param[in] dtype_id The datatype of the packet + * \param[in] chunk_size The size in number of table entries per chunk + * \param[in] plist_id Identifier of the property list. Can be used to + * specify the compression of the packet table. + * + * \return Returns an identifier for the new packet table or + * #H5I_INVALID_HID on error. + * + * \details The H5PTcreate() creates and opens a packet table named + * \p dset_name attached to the object specified by the + * identifier \p loc_id. The created packet table should be closed + * with H5PTclose(), eventually. + * + * The datatype, \p dtype_id, may specify any datatype, including + * variable-length data. If \p dtype_id specifies a compound + * datatype, one or more fields in that compound type may be + * variable-length. + * + * \p chunk_size is the size in number of table entries per chunk. + * Packet table datasets use HDF5 chunked storage + * to allow them to grow. This value allows the user + * to set the size of a chunk. The chunk size affects + * performance. + * + * \since 1.10.0 and 1.8.17 + * + */ H5_HLDLL hid_t H5PTcreate(hid_t loc_id, const char *dset_name, hid_t dtype_id, hsize_t chunk_size, hid_t plist_id); +/** + * -------------------------------------------------------------------------- + * \ingroup H5PT + * + * \brief Opens an existing packet table. + * + * \fg_loc_id + * \param[in] dset_name The name of the packet table to open + * + * \return Returns an identifier for the packet table or + * #H5I_INVALID_HID on error. + * + * \details H5PTopen() opens an existing packet table in the file or group + * specified by \p loc_id. \p dset_name is the name of the packet + * table and is used to identify it in the file. This function is + * used to open both fixed-length packet tables and variable-length + * packet tables. The packet table should later be closed with + * H5PTclose(). + * + */ H5_HLDLL hid_t H5PTopen(hid_t loc_id, const char *dset_name); +/** + * -------------------------------------------------------------------------- + * \ingroup H5PT + * + * \brief Closes an open packet table. + * + * \param[in] table_id Identifier of packet table to be closed + * + * \return \herr_t + * + * \details The H5PTclose() ends access to a packet table specified + * by \p table_id. + * + */ H5_HLDLL herr_t H5PTclose(hid_t table_id); +/** + * -------------------------------------------------------------------------- + * \ingroup H5PT + * + * \brief Creates a packet table to store fixed-length packets + * + * \fg_loc_id + * \param[in] dset_name The name of the dataset to create + * \param[in] dtype_id The datatype of a packet. + * \param[in] chunk_size The size in number of table entries per + * chunk. + * \param[in] compression The compression level; + * a value of 0 through 9. + * + * \return Returns an identifier for the packet table or + * #H5I_INVALID_HID on error. + * + * \deprecated This function was deprecated in favor of the function + * H5PTcreate(). + * + * \details The H5PTcreate_fl() creates and opens a packet table + * named \p dset_name attached to the object specified by + * the identifier \p loc_id. It should be closed + * with H5PTclose(). + * + * The datatype, \p dtype_id, may specify any datatype, + * including variable-length data. If \p dtype_id specifies a + * compound datatype, one or more fields in that compound type + * may be variable-length. + * + * \p chunk_size is the size in number of table entries per chunk. + * Packet table datasets use HDF5 chunked storage + * to allow them to grow. This value allows the user + * to set the size of a chunk. The chunk size affects + * performance. + * + * \p compression is the compression level, a value of 0 through 9. + * Level 0 is faster but offers the least compression; + * level 9 is slower but offers maximum compression. + * A setting of -1 indicates that no compression is desired. + + */ /* This function may be removed from the packet table in release 1.8.19. */ H5_HLDLL hid_t H5PTcreate_fl(hid_t loc_id, const char *dset_name, hid_t dtype_id, hsize_t chunk_size, int compression); @@ -39,24 +221,148 @@ H5_HLDLL hid_t H5PTcreate_fl(hid_t loc_id, const char *dset_name, hid_t dtype_id * Write functions *------------------------------------------------------------------------- */ +/** + * -------------------------------------------------------------------------- + * \ingroup H5PT + * + * \brief Appends packets to the end of a packet table. + * + * \param[in] table_id Identifier of packet table to which + * packets should be appended + * \param[in] nrecords Number of packets to be appended + * \param[in] data Buffer holding data to write + * + * \return \herr_t + * + * \details The H5PTappend() writes \p nrecords packets to the end of a + * packet table specified by \p table_id. \p data is a buffer + * containing the data to be written. For a packet table holding + * fixed-length packets, this data should be in the packet + * table's datatype. For a variable-length packet table, + * the data should be in the form of #hvl_t structs. + * + */ H5_HLDLL herr_t H5PTappend(hid_t table_id, size_t nrecords, const void *data); /*------------------------------------------------------------------------- * Read functions *------------------------------------------------------------------------- */ +/** + * -------------------------------------------------------------------------- + * \ingroup H5PT + * + * \brief Reads packets from a packet table starting at the current index. + * + * \param[in] table_id Identifier of packet table to read from + * \param[in] nrecords Number of packets to be read + * \param[out] data Buffer into which to read data + * + * \return \herr_t + * + * \details The H5PTget_next() reads \p nrecords packets starting with + * the "current index" from a packet table specified by \p table_id. + * The packet table's index is set and reset with H5PTset_index() + * and H5PTcreate_index(). \p data is a buffer into which the + * data should be read. + * + * For a packet table holding variable-length records, the data + * returned in the buffer will be in form of a #hvl_t struct + * containing the length of the data and a pointer to it in memory. + * The memory used by this data must be freed using H5PTfree_vlen_buff(). + * + */ H5_HLDLL herr_t H5PTget_next(hid_t table_id, size_t nrecords, void *data); +/** + * -------------------------------------------------------------------------- + * \ingroup H5PT + * + * \brief Reads a number of packets from a packet table. + * + * \param[in] table_id Identifier of packet table to read from + * \param[in] start Packet to start reading from + * \param[in] nrecords Number of packets to be read + * \param[out] data Buffer into which to read data. + * + * \return \herr_t + * + * \details The H5PTread_packets() reads \p nrecords packets starting at + * packet number \p start from a packet table specified by + * \p table_id. \p data is a buffer into which the data should + * be read. + * + * For a packet table holding variable-length records, the data + * returned in the buffer will be in form of #hvl_t structs, + * each containing the length of the data and a pointer to it in + * memory. The memory used by this data must be freed using + * H5PTfree_vlen_buff(). + * + */ H5_HLDLL herr_t H5PTread_packets(hid_t table_id, hsize_t start, size_t nrecords, void *data); /*------------------------------------------------------------------------- * Inquiry functions *------------------------------------------------------------------------- */ + +/** + * -------------------------------------------------------------------------- + * \ingroup H5PT + * + * \brief Returns the number of packets in a packet table. + * + * \param[in] table_id Identifier of packet table to query + * \param[out] nrecords Number of packets in packet table + * + * \return \herr_t + * + * \details The H5PTget_num_packets() returns by reference the number + * of packets in a packet table specified by \p table_id. + * + */ H5_HLDLL herr_t H5PTget_num_packets(hid_t table_id, hsize_t *nrecords); +/** + * -------------------------------------------------------------------------- + * \ingroup H5PT + * + * \brief Determines whether an identifier points to a packet table. + * + * \param[in] table_id Identifier to query + * + * \return Returns a non-negative value if \p table_id is + * a valid packet table, otherwise returns a negative value. + * + * \details The H5PTis_valid() returns a non-negative value if + * \p table_id corresponds to an open packet table, + * and returns a negative value otherwise. + * + */ H5_HLDLL herr_t H5PTis_valid(hid_t table_id); +/** + * -------------------------------------------------------------------------- + * \ingroup H5PT + * + * \brief Determines whether a packet table contains + * variable-length or fixed-length packets. + * + * \param[in] table_id Packet table to query + * + * \return Returns 1 for a variable-length packet table, + * 0 for fixed-length, or a negative value on error. + * + * \details The H5PTis_varlen() returns 1 (TRUE) if \p table_id is + * a packet table containing variable-length records. + * It returns 0 (FALSE) if \p table_id is a packet table + * containing fixed-length records. If \p table_id is not a + * packet table, a negative value is returned. + * + * \version 1.10.0 and 1.8.17 Function re-introduced. + * Function had been removed in 1.8.3. + * + */ H5_HLDLL herr_t H5PTis_varlen(hid_t table_id); /*------------------------------------------------------------------------- @@ -66,8 +372,42 @@ H5_HLDLL herr_t H5PTis_varlen(hid_t table_id); *------------------------------------------------------------------------- */ +/** + * -------------------------------------------------------------------------- + * \ingroup H5PT + * + * \brief Returns the backend dataset of this packet table. + * + * \param[in] table_id Identifier of the packet table + * + * \return Returns a dataset identifier or H5I_INVALID_HID on error. + * + * \details The H5PTget_dataset() returns the identifier of the dataset + * storing the packet table \p table_id. This dataset identifier + * will be closed by H5PTclose(). + * + * \since 1.10.0 and 1.8.17 + * + */ H5_HLDLL hid_t H5PTget_dataset(hid_t table_id); +/** + * -------------------------------------------------------------------------- + * \ingroup H5PT + * + * \brief Returns the backend datatype of this packet table. + * + * \param[in] table_id Identifier of the packet table + * + * \return Returns a datatype identifier or H5I_INVALID_HID on error. + * + * \details The H5PTget_type() returns the identifier of the datatype + * used by the packet table \p table_id. This datatype + * identifier will be closed by H5PTclose(). + * + * \since 1.10.0 and 1.8.17 + * + */ H5_HLDLL hid_t H5PTget_type(hid_t table_id); /*------------------------------------------------------------------------- @@ -77,10 +417,63 @@ H5_HLDLL hid_t H5PTget_type(hid_t table_id); *------------------------------------------------------------------------- */ +/** + * -------------------------------------------------------------------------- + * \ingroup H5PT + * + * \brief Resets a packet table's index to the first packet. + * + * \param[in] table_id Identifier of packet table whose index + * should be initialized. + * + * \return \herr_t + * + * \details Each packet table keeps an index of the "current" packet + * so that \c get_next can iterate through the packets in order. + * H5PTcreate_index() initializes a packet table's index, and + * should be called before using \c get_next. The index must be + * initialized every time a packet table is created or opened; + * this information is lost when the packet table is closed. + * + */ H5_HLDLL herr_t H5PTcreate_index(hid_t table_id); +/** + * -------------------------------------------------------------------------- + * \ingroup H5PT + * + * \brief Sets a packet table's index. + * + * \param[in] table_id Identifier of packet table whose index is to be set + * \param[in] pt_index The packet to which the index should point + * + * \return \herr_t + * + * \details Each packet table keeps an index of the "current" packet + * so that \c get_next can iterate through the packets in order. + * H5PTset_index() sets this index to point to a user-specified + * packet (the packets are zero-indexed). + * + */ H5_HLDLL herr_t H5PTset_index(hid_t table_id, hsize_t pt_index); +/** + * -------------------------------------------------------------------------- + * \ingroup H5PT + * + * \brief Gets the current record index for a packet table. + * + * \param[in] table_id Table identifier + * \param[out] pt_index Current record index + * + * \return \herr_t + * + * \details The H5PTget_index() returns the current record index + * \p pt_index for the table identified by \p table_id. + * + * \since 1.8.0 + * + */ H5_HLDLL herr_t H5PTget_index(hid_t table_id, hsize_t *pt_index); /*------------------------------------------------------------------------- @@ -90,6 +483,29 @@ H5_HLDLL herr_t H5PTget_index(hid_t table_id, hsize_t *pt_index); *------------------------------------------------------------------------- */ +/** + * -------------------------------------------------------------------------- + * \ingroup H5PT + * + * \brief Releases memory allocated in the process of reading + * variable-length packets. + * + * \param[in] table_id Packet table whose memory should be freed. + * \param[in] bufflen Size of \p buff + * \param[in] buff Buffer that was used to read in variable-length + * packets + * + * \return \herr_t + * + * \details When variable-length packets are read, memory is automatically + * allocated to hold them, and must be freed. H5PTfree_vlen_buff() + * frees this memory, and should be called whenever packets are + * read from a variable-length packet table. + * + * \version 1.10.0 and 1.8.17 Function re-introduced. + * Function had been removed in 1.8.3. + * + */ H5_HLDLL herr_t H5PTfree_vlen_buff(hid_t table_id, size_t bufflen, void *buff); #ifdef __cplusplus |