1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
|
/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
* Copyright by The HDF Group. *
* All rights reserved. *
* *
* This file is part of HDF5. The full HDF5 copyright notice, including *
* terms governing use, modification, and redistribution, is contained in *
* the COPYING file, which can be found at the root of the source code *
* distribution tree, or in https://www.hdfgroup.org/licenses. *
* If you do not have access to either file, you may request a copy from *
* help@hdfgroup.org. *
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
#ifndef H5DOpublic_H
#define H5DOpublic_H
#ifdef __cplusplus
extern "C" {
#endif
/** \page H5DO_UG The HDF5 High Level Optimizations
* @todo Under Construction
*/
/**\defgroup H5DO HDF5 Optimizations APIs (H5DO)
*
* <em>Bypassing default HDF5 behavior in order to optimize for specific
* use cases (H5DO)</em>
*
* HDF5 functions described is this section are implemented in the HDF5 High-level
* library as optimized functions. These functions generally require careful setup
* and testing as they enable an application to bypass portions of the HDF5
* library's I/O pipeline for performance purposes.
*
* These functions are distributed in the standard HDF5 distribution and are
* available any time the HDF5 High-level library is available.
*
* - \ref H5DOappend
* \n Appends data to a dataset along a specified dimension.
* - \ref H5DOread_chunk
* \n Reads a raw data chunk directly from a dataset in a file into a buffer (DEPRECATED)
* - \ref H5DOwrite_chunk
* \n Writes a raw data chunk from a buffer directly to a dataset in a file (DEPRECATED)
*
*/
/*-------------------------------------------------------------------------
*
* "Optimized dataset" routines.
*
*-------------------------------------------------------------------------
*/
/**
* --------------------------------------------------------------------------
* \ingroup H5DO
*
* \brief Appends data to a dataset along a specified dimension.
*
* \param[in] dset_id Dataset identifier
* \param[in] dxpl_id Dataset transfer property list identifier
* \param[in] axis Dataset Dimension (0-based) for the append
* \param[in] extension Number of elements to append for the
* axis-th dimension
* \param[in] memtype The memory datatype identifier
* \param[in] buf Buffer with data for the append
*
* \return \herr_t
*
* \details The H5DOappend() routine extends a dataset by \p extension
* number of elements along a dimension specified by a
* dimension \p axis and writes \p buf of elements to the
* dataset. Dimension \p axis is 0-based. Elements’ type
* is described by \p memtype.
*
* This routine combines calling H5Dset_extent(),
* H5Sselect_hyperslab(), and H5Dwrite() into a single routine
* that simplifies application development for the common case
* of appending elements to an existing dataset.
*
* For a multi-dimensional dataset, appending to one dimension
* will write a contiguous hyperslab over the other dimensions.
* For example, if a 3-D dataset has dimension sizes (3, 5, 8),
* extending the 0th dimension (currently of size 3) by 3 will
* append 3*5*8 = 120 elements (which must be pointed to by the
* \p buffer parameter) to the dataset, making its final
* dimension sizes (6, 5, 8).
*
* If a dataset has more than one unlimited dimension, any of
* those dimensions may be appended to, although only along
* one dimension per call to H5DOappend().
*
* \since 1.10.0
*
*/
H5_HLDLL herr_t H5DOappend(hid_t dset_id, hid_t dxpl_id, unsigned axis, size_t extension, hid_t memtype,
const void *buf);
/* Symbols defined for compatibility with previous versions of the HDF5 API.
*
* Use of these symbols is deprecated.
*/
#ifndef H5_NO_DEPRECATED_SYMBOLS
/* Compatibility wrappers for functionality moved to H5D */
/**
* --------------------------------------------------------------------------
* \ingroup H5DO
*
* \brief Writes a raw data chunk from a buffer directly to a dataset in a file.
*
* \param[in] dset_id Identifier for the dataset to write to
* \param[in] dxpl_id Transfer property list identifier for
* this I/O operation
* \param[in] filters Mask for identifying the filters in use
* \param[in] offset Logical position of the chunk's first element
* in the dataspace
* \param[in] data_size Size of the actual data to be written in bytes
* \param[in] buf Buffer containing data to be written to the chunk
*
* \return \herr_t
*
* \deprecated This function was deprecated in favor of the function
* H5Dwrite_chunk() of HDF5-1.10.3.
* The functionality of H5DOwrite_chunk() was moved
* to H5Dwrite_chunk().
* \deprecated For compatibility, this API call has been left as a stub which
* simply calls H5Dwrite_chunk(). New code should use H5Dwrite_chunk().
*
* \details The H5DOwrite_chunk() writes a raw data chunk as specified by its
* logical \p offset in a chunked dataset \p dset_id from the application
* memory buffer \p buf to the dataset in the file. Typically, the data
* in \p buf is preprocessed in memory by a custom transformation, such as
* compression. The chunk will bypass the library's internal data
* transfer pipeline, including filters, and will be written directly to the file.
*
* \p dxpl_id is a data transfer property list identifier.
*
* \p filters is a mask providing a record of which filters are used
* with the chunk. The default value of the mask is zero (\c 0),
* indicating that all enabled filters are applied. A filter is skipped
* if the bit corresponding to the filter's position in the pipeline
* (<tt>0 ≤ position < 32</tt>) is turned on. This mask is saved
* with the chunk in the file.
*
* \p offset is an array specifying the logical position of the first
* element of the chunk in the dataset's dataspace. The length of the
* offset array must equal the number of dimensions, or rank, of the
* dataspace. The values in \p offset must not exceed the dimension limits
* and must specify a point that falls on a dataset chunk boundary.
*
* \p data_size is the size in bytes of the chunk, representing the number of
* bytes to be read from the buffer \p buf. If the data chunk has been
* precompressed, \p data_size should be the size of the compressed data.
*
* \p buf is the memory buffer containing data to be written to the chunk in the file.
*
* \attention Exercise caution when using H5DOread_chunk() and H5DOwrite_chunk(),
* as they read and write data chunks directly in a file.
* H5DOwrite_chunk() bypasses hyperslab selection, the conversion of data
* from one datatype to another, and the filter pipeline to write the chunk.
* Developers should have experience with these processes before
* using this function. Please see
* <a href="https://portal.hdfgroup.org/display/HDF5/Using+the+Direct+Chunk+Write+Function">
* Using the Direct Chunk Write Function</a>
* for more information.
*
* \note H5DOread_chunk() and H5DOwrite_chunk() are not
* supported under parallel and do not support variable length types.
*
* \par Example
* The following code illustrates the use of H5DOwrite_chunk to write
* an entire dataset, chunk by chunk:
* \snippet H5DO_examples.c H5DOwrite
*
* \version 1.10.3 Function deprecated in favor of H5Dwrite_chunk.
*
* \since 1.8.11
*/
H5_HLDLL herr_t H5DOwrite_chunk(hid_t dset_id, hid_t dxpl_id, uint32_t filters, const hsize_t *offset,
size_t data_size, const void *buf);
/**
* --------------------------------------------------------------------------
* \ingroup H5DO
*
* \brief Reads a raw data chunk directly from a dataset in a file into a buffer.
*
* \param[in] dset_id Identifier for the dataset to be read
* \param[in] dxpl_id Transfer property list identifier for
* this I/O operation
* \param[in] offset Logical position of the chunk's first
element in the dataspace
* \param[in,out] filters Mask for identifying the filters used
* with the chunk
* \param[in] buf Buffer containing the chunk read from
* the dataset
*
* \return \herr_t
*
* \deprecated This function was deprecated in favor of the function
* H5Dread_chunk() as of HDF5-1.10.3.
* In HDF5 1.10.3, the functionality of H5DOread_chunk()
* was moved to H5Dread_chunk().
* \deprecated For compatibility, this API call has been left as a stub which
* simply calls H5Dread_chunk(). New code should use H5Dread_chunk().
*
* \details The H5DOread_chunk() reads a raw data chunk as specified
* by its logical \p offset in a chunked dataset \p dset_id
* from the dataset in the file into the application memory
* buffer \p buf. The data in \p buf is read directly from the file
* bypassing the library's internal data transfer pipeline,
* including filters.
*
* \p dxpl_id is a data transfer property list identifier.
*
* The mask \p filters indicates which filters are used with the
* chunk when written. A zero value indicates that all enabled filters
* are applied on the chunk. A filter is skipped if the bit corresponding
* to the filter's position in the pipeline
* (<tt>0 ≤ position < 32</tt>) is turned on.
*
* \p offset is an array specifying the logical position of the first
* element of the chunk in the dataset's dataspace. The length of the
* offset array must equal the number of dimensions, or rank, of the
* dataspace. The values in \p offset must not exceed the dimension
* limits and must specify a point that falls on a dataset chunk boundary.
*
* \p buf is the memory buffer containing the chunk read from the dataset
* in the file.
*
* \par Example
* The following code illustrates the use of H5DOread_chunk()
* to read a chunk from a dataset:
* \snippet H5DO_examples.c H5DOread
*
* \version 1.10.3 Function deprecated in favor of H5Dread_chunk.
*
* \since 1.10.2, 1.8.19
*/
H5_HLDLL herr_t H5DOread_chunk(hid_t dset_id, hid_t dxpl_id, const hsize_t *offset, uint32_t *filters /*out*/,
void *buf /*out*/);
#endif /* H5_NO_DEPRECATED_SYMBOLS */
#ifdef __cplusplus
}
#endif
#endif
|
