1 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * 2 * Copyright by The HDF Group. * 3 * Copyright by the Board of Trustees of the University of Illinois. * 4 * All rights reserved. * 5 * * 6 * This file is part of HDF5. The full HDF5 copyright notice, including * 7 * terms governing use, modification, and redistribution, is contained in * 8 * the COPYING file, which can be found at the root of the source code * 9 * distribution tree, or in https://support.hdfgroup.org/ftp/HDF5/releases. * 10 * If you do not have access to either file, you may request a copy from * 11 * help@hdfgroup.org. * 12 * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ 13 14 /* 15 * This file contains private information about the H5S module 16 */ 17 #ifndef _H5Sprivate_H 18 #define _H5Sprivate_H 19 20 /* Include package's public header */ 21 #include "H5Spublic.h" 22 23 /* Public headers needed by this file */ 24 #include "H5Dpublic.h" /* Datasets */ 25 26 /* Private headers needed by this file */ 27 #include "H5private.h" /* Generic Functions */ 28 #include "H5Fprivate.h" /* Files */ 29 #include "H5Gprivate.h" /* Groups */ 30 #include "H5Oprivate.h" /* Object headers */ 31 #include "H5Pprivate.h" /* Property lists */ 32 #include "H5Tprivate.h" /* Datatypes */ 33 34 /* Flags for H5S_find */ 35 #define H5S_CONV_PAR_IO_POSSIBLE 0x0001 36 /* The storage options are mutually exclusive */ 37 /* (2-bits reserved for storage type currently) */ 38 #define H5S_CONV_STORAGE_COMPACT 0x0000 /* i.e. '0' */ 39 #define H5S_CONV_STORAGE_CONTIGUOUS 0x0002 /* i.e. '1' */ 40 #define H5S_CONV_STORAGE_CHUNKED 0x0004 /* i.e. '2' */ 41 #define H5S_CONV_STORAGE_MASK 0x0006 42 43 /* Flags for "get_seq_list" methods */ 44 #define H5S_GET_SEQ_LIST_SORTED 0x0001 45 46 /* Forward references of package typedefs */ 47 typedef struct H5S_t H5S_t; 48 typedef struct H5S_extent_t H5S_extent_t; 49 typedef struct H5S_pnt_node_t H5S_pnt_node_t; 50 typedef struct H5S_hyper_span_t H5S_hyper_span_t; 51 typedef struct H5S_hyper_span_info_t H5S_hyper_span_info_t; 52 53 /* Information about one dimension in a hyperslab selection */ 54 typedef struct H5S_hyper_dim_t { 55 hsize_t start; 56 hsize_t stride; 57 hsize_t count; 58 hsize_t block; 59 } H5S_hyper_dim_t; 60 61 /* Point selection iteration container */ 62 typedef struct { 63 H5S_pnt_node_t *curr; /* Pointer to next node to output */ 64 } H5S_point_iter_t; 65 66 /* Hyperslab selection iteration container */ 67 typedef struct { 68 /* Common fields for all hyperslab selections */ 69 hsize_t off[H5S_MAX_RANK]; /* Offset in span node (used as position for regular hyperslabs) */ 70 unsigned iter_rank; /* Rank of iterator information */ 71 /* (This should always be the same as the dataspace 72 * rank, except for regular hyperslab selections in 73 * which there are contiguous regions in the lower 74 * dimensions which have been "flattened" out 75 */ 76 hbool_t diminfo_valid; /* Whether the dimension information is valid */ 77 78 /* "Flattened" regular hyperslab selection fields */ 79 H5S_hyper_dim_t diminfo[H5S_MAX_RANK]; /* "Flattened" regular selection information */ 80 hsize_t size[H5S_MAX_RANK]; /* "Flattened" dataspace extent information */ 81 hssize_t sel_off[H5S_MAX_RANK]; /* "Flattened" selection offset information */ 82 hbool_t flattened[H5S_MAX_RANK]; /* Whether this dimension has been flattened */ 83 84 /* Irregular hyperslab selection fields */ 85 H5S_hyper_span_info_t *spans; /* Pointer to copy of the span tree */ 86 H5S_hyper_span_t *span[H5S_MAX_RANK];/* Array of pointers to span nodes */ 87 } H5S_hyper_iter_t; 88 89 /* "All" selection iteration container */ 90 typedef struct { 91 hsize_t elmt_offset; /* Next element to output */ 92 hsize_t byte_offset; /* Next byte to output */ 93 } H5S_all_iter_t; 94 95 /* Forward declaration of selection iteration class */ 96 struct H5S_sel_iter_class_t; 97 98 /* Selection iteration container */ 99 typedef struct H5S_sel_iter_t { 100 /* Selection class */ 101 const struct H5S_sel_iter_class_t *type; /* Selection iteration class info */ 102 103 /* Information common to all iterators */ 104 unsigned rank; /* Rank of dataspace the selection iterator is operating on */ 105 hsize_t *dims; /* Dimensions of dataspace the selection is operating on */ 106 hsize_t elmt_left; /* Number of elements left to iterate over */ 107 size_t elmt_size; /* Size of elements to iterate over */ 108 109 /* Information specific to each type of iterator */ 110 union { 111 H5S_point_iter_t pnt; /* Point selection iteration information */ 112 H5S_hyper_iter_t hyp; /* New Hyperslab selection iteration information */ 113 H5S_all_iter_t all; /* "All" selection iteration information */ 114 } u; 115 } H5S_sel_iter_t; 116 117 /* Selection iteration operator for internal library callbacks */ 118 typedef herr_t (*H5S_sel_iter_lib_op_t)(void *elem, const H5T_t *type, 119 unsigned ndim, const hsize_t *point, void *op_data); 120 121 /* Describe kind of callback to make */ 122 typedef enum H5S_sel_iter_op_type_t { 123 H5S_SEL_ITER_OP_APP, /* Application callback */ 124 H5S_SEL_ITER_OP_LIB /* Library internal callback */ 125 } H5S_sel_iter_op_type_t; 126 127 typedef struct H5S_sel_iter_app_op_t { 128 H5D_operator_t op; /* Callback */ 129 hid_t type_id; /* Type ID to be passed to callback */ 130 } H5S_sel_iter_app_op_t; 131 132 typedef struct H5S_sel_iter_op_t { 133 H5S_sel_iter_op_type_t op_type; 134 union { 135 H5S_sel_iter_app_op_t app_op; /* Application callback */ 136 H5S_sel_iter_lib_op_t lib_op; /* Library internal callback */ 137 } u; 138 } H5S_sel_iter_op_t; 139 140 /* If the module using this macro is allowed access to the private variables, access them directly */ 141 #ifdef H5S_MODULE 142 #define H5S_GET_EXTENT_TYPE(S) ((S)->extent.type) 143 #define H5S_GET_EXTENT_NDIMS(S) ((S)->extent.rank) 144 #define H5S_GET_EXTENT_NPOINTS(S) ((S)->extent.nelem) 145 #define H5S_GET_SELECT_NPOINTS(S) ((S)->select.num_elem) 146 #define H5S_GET_SELECT_TYPE(S) ((S)->select.type->type) 147 #define H5S_SELECT_GET_SEQ_LIST(S,FLAGS,ITER,MAXSEQ,MAXBYTES,NSEQ,NBYTES,OFF,LEN) ((*(S)->select.type->get_seq_list)(S,FLAGS,ITER,MAXSEQ,MAXBYTES,NSEQ,NBYTES,OFF,LEN)) 148 #define H5S_SELECT_VALID(S) ((*(S)->select.type->is_valid)(S)) 149 #define H5S_SELECT_RELEASE(S) ((*(S)->select.type->release)(S)) 150 #define H5S_SELECT_SERIAL_SIZE(S) ((*(S)->select.type->serial_size)(S)) 151 #define H5S_SELECT_SERIALIZE(S,BUF) ((*(S)->select.type->serialize)(S,BUF)) 152 #define H5S_SELECT_BOUNDS(S,START,END) ((*(S)->select.type->bounds)(S,START,END)) 153 #define H5S_SELECT_OFFSET(S, OFFSET) ((*(S)->select.type->offset)(S, OFFSET)) 154 #define H5S_SELECT_IS_CONTIGUOUS(S) ((*(S)->select.type->is_contiguous)(S)) 155 #define H5S_SELECT_IS_SINGLE(S) ((*(S)->select.type->is_single)(S)) 156 #define H5S_SELECT_IS_REGULAR(S) ((*(S)->select.type->is_regular)(S)) 157 #define H5S_SELECT_ADJUST_U(S,O) ((*(S)->select.type->adjust_u)(S, O)) 158 #define H5S_SELECT_PROJECT_SCALAR(S,O) ((*(S)->select.type->project_scalar)(S, O)) 159 #define H5S_SELECT_PROJECT_SIMPLE(S,NS, O) ((*(S)->select.type->project_simple)(S, NS, O)) 160 #define H5S_SELECT_ITER_COORDS(ITER,COORDS) ((*(ITER)->type->iter_coords)(ITER,COORDS)) 161 #define H5S_SELECT_ITER_BLOCK(ITER,START,END) ((*(ITER)->type->iter_block)(ITER,START,END)) 162 #define H5S_SELECT_ITER_NELMTS(ITER) ((*(ITER)->type->iter_nelmts)(ITER)) 163 #define H5S_SELECT_ITER_HAS_NEXT_BLOCK(ITER) ((*(ITER)->type->iter_has_next_block)(ITER)) 164 #define H5S_SELECT_ITER_NEXT(ITER,NELEM)((*(ITER)->type->iter_next)(ITER,NELEM)) 165 #define H5S_SELECT_ITER_NEXT_BLOCK(ITER) ((*(ITER)->type->iter_next_block)(ITER)) 166 #define H5S_SELECT_ITER_RELEASE(ITER) ((*(ITER)->type->iter_release)(ITER)) 167 #else /* H5S_MODULE */ 168 #define H5S_GET_EXTENT_TYPE(S) (H5S_get_simple_extent_type(S)) 169 #define H5S_GET_EXTENT_NDIMS(S) (H5S_get_simple_extent_ndims(S)) 170 #define H5S_GET_EXTENT_NPOINTS(S) (H5S_get_simple_extent_npoints(S)) 171 #define H5S_GET_SELECT_NPOINTS(S) (H5S_get_select_npoints(S)) 172 #define H5S_GET_SELECT_TYPE(S) (H5S_get_select_type(S)) 173 #define H5S_SELECT_GET_SEQ_LIST(S,FLAGS,ITER,MAXSEQ,MAXBYTES,NSEQ,NBYTES,OFF,LEN) (H5S_select_get_seq_list(S,FLAGS,ITER,MAXSEQ,MAXBYTES,NSEQ,NBYTES,OFF,LEN)) 174 #define H5S_SELECT_VALID(S) (H5S_select_valid(S)) 175 #define H5S_SELECT_RELEASE(S) (H5S_select_release(S)) 176 #define H5S_SELECT_SERIAL_SIZE(S) (H5S_select_serial_size(S)) 177 #define H5S_SELECT_SERIALIZE(S,BUF) (H5S_select_serialize(S,BUF)) 178 #define H5S_SELECT_BOUNDS(S,START,END) (H5S_get_select_bounds(S,START,END)) 179 #define H5S_SELECT_OFFSET(S, OFFSET) (H5S_get_select_offset(S, OFFSET)) 180 #define H5S_SELECT_IS_CONTIGUOUS(S) (H5S_select_is_contiguous(S)) 181 #define H5S_SELECT_IS_SINGLE(S) (H5S_select_is_single(S)) 182 #define H5S_SELECT_IS_REGULAR(S) (H5S_select_is_regular(S)) 183 #define H5S_SELECT_ADJUST_U(S,O) (H5S_select_adjust_u(S, O)) 184 #define H5S_SELECT_PROJECT_SCALAR(S,O) (H5S_select_project_scalar(S, O)) 185 #define H5S_SELECT_PROJECT_SIMPLE(S,NS,O) (H5S_select_project_simple(S, NS, O)) 186 #define H5S_SELECT_ITER_COORDS(ITER,COORDS) (H5S_select_iter_coords(ITER,COORDS)) 187 #define H5S_SELECT_ITER_BLOCK(ITER,START,END) (H5S_select_iter_block(ITER,START,END)) 188 #define H5S_SELECT_ITER_NELMTS(ITER) (H5S_select_iter_nelmts(ITER)) 189 #define H5S_SELECT_ITER_HAS_NEXT_BLOCK(ITER) (H5S_select_iter_has_next_block(ITER)) 190 #define H5S_SELECT_ITER_NEXT(ITER,NELEM)(H5S_select_iter_next(ITER,NELEM)) 191 #define H5S_SELECT_ITER_NEXT_BLOCK(ITER) (H5S_select_iter_next_block(ITER)) 192 #define H5S_SELECT_ITER_RELEASE(ITER) (H5S_select_iter_release(ITER)) 193 #endif /* H5S_MODULE */ 194 /* Handle these two callbacks in a special way, since they have prologs that need to be executed */ 195 #define H5S_SELECT_COPY(DST,SRC,SHARE) (H5S_select_copy(DST,SRC,SHARE)) 196 #define H5S_SELECT_DESERIALIZE(S,BUF) (H5S_select_deserialize(S,BUF)) 197 198 199 /* Operations on dataspaces */ 200 H5_DLL H5S_t *H5S_copy(const H5S_t *src, hbool_t share_selection, hbool_t copy_max); 201 H5_DLL herr_t H5S_close(H5S_t *ds); 202 H5_DLL H5S_class_t H5S_get_simple_extent_type(const H5S_t *ds); 203 H5_DLL hssize_t H5S_get_simple_extent_npoints(const H5S_t *ds); 204 H5_DLL hsize_t H5S_get_npoints_max(const H5S_t *ds); 205 H5_DLL hbool_t H5S_has_extent(const H5S_t *ds); 206 H5_DLL int H5S_get_simple_extent_ndims(const H5S_t *ds); 207 H5_DLL int H5S_get_simple_extent_dims(const H5S_t *ds, hsize_t dims[]/*out*/, 208 hsize_t max_dims[]/*out*/); 209 H5_DLL herr_t H5S_write(H5F_t *f, hid_t dxpl_id, H5O_t *oh, unsigned update_flags, 210 H5S_t *ds); 211 H5_DLL herr_t H5S_append(H5F_t *f, hid_t dxpl_id, struct H5O_t *oh, H5S_t *ds); 212 H5_DLL H5S_t *H5S_read(const struct H5O_loc_t *loc, hid_t dxpl_id); 213 H5_DLL htri_t H5S_set_extent(H5S_t *space, const hsize_t *size); 214 H5_DLL herr_t H5S_set_extent_real(H5S_t *space, const hsize_t *size); 215 H5_DLL herr_t H5S_set_extent_simple(H5S_t *space, unsigned rank, 216 const hsize_t *dims, const hsize_t *max); 217 H5_DLL H5S_t *H5S_create(H5S_class_t type); 218 H5_DLL H5S_t *H5S_create_simple(unsigned rank, const hsize_t dims[/*rank*/], 219 const hsize_t maxdims[/*rank*/]); 220 H5_DLL herr_t H5S_set_latest_version(H5S_t *ds); 221 H5_DLL herr_t H5S_encode(H5S_t *obj, unsigned char **p, size_t *nalloc); 222 H5_DLL H5S_t *H5S_decode(const unsigned char **p); 223 H5_DLL herr_t H5S_debug(H5F_t *f, hid_t dxpl_id, const void *_mesg, FILE *stream, 224 int indent, int fwidth); 225 #ifndef H5_NO_DEPRECATED_SYMBOLS 226 H5_DLL int H5S_extend(H5S_t *space, const hsize_t *size); 227 #endif /* H5_NO_DEPRECATED_SYMBOLS */ 228 229 /* Operations on dataspace extents */ 230 H5_DLL hsize_t H5S_extent_nelem(const H5S_extent_t *ext); 231 H5_DLL int H5S_extent_get_dims(const H5S_extent_t *ext, hsize_t dims[], hsize_t max_dims[]); 232 H5_DLL htri_t H5S_extent_equal(const H5S_t *ds1, const H5S_t *ds2); 233 H5_DLL herr_t H5S_extent_copy(H5S_t *dst, const H5S_t *src); 234 235 /* Operations on selections */ 236 H5_DLL herr_t H5S_select_deserialize(H5S_t **space, const uint8_t **p); 237 H5_DLL H5S_sel_type H5S_get_select_type(const H5S_t *space); 238 H5_DLL herr_t H5S_select_iterate(void *buf, const H5T_t *type, const H5S_t *space, 239 const H5S_sel_iter_op_t *op, void *op_data); 240 H5_DLL herr_t H5S_select_fill(const void *fill, size_t fill_size, 241 const H5S_t *space, void *buf); 242 H5_DLL htri_t H5S_select_valid(const H5S_t *space); 243 H5_DLL hssize_t H5S_get_select_npoints(const H5S_t *space); 244 H5_DLL herr_t H5S_get_select_bounds(const H5S_t *space, hsize_t *start, hsize_t *end); 245 H5_DLL herr_t H5S_get_select_offset(const H5S_t *space, hsize_t *offset); 246 H5_DLL int H5S_get_select_unlim_dim(const H5S_t *space); 247 H5_DLL herr_t H5S_get_select_num_elem_non_unlim(const H5S_t *space, 248 hsize_t *num_elem_non_unlim); 249 H5_DLL herr_t H5S_select_offset(H5S_t *space, const hssize_t *offset); 250 H5_DLL herr_t H5S_select_copy(H5S_t *dst, const H5S_t *src, hbool_t share_selection); 251 H5_DLL htri_t H5S_select_shape_same(const H5S_t *space1, const H5S_t *space2); 252 H5_DLL herr_t H5S_select_construct_projection(const H5S_t *base_space, 253 H5S_t **new_space_ptr, unsigned new_space_rank, const void *buf, 254 void const **adj_buf_ptr, hsize_t element_size); 255 H5_DLL herr_t H5S_select_release(H5S_t *ds); 256 H5_DLL herr_t H5S_select_get_seq_list(const H5S_t *space, unsigned flags, 257 H5S_sel_iter_t *iter, size_t maxseq, size_t maxbytes, 258 size_t *nseq, size_t *nbytes, hsize_t *off, size_t *len); 259 H5_DLL hssize_t H5S_select_serial_size(const H5S_t *space); 260 H5_DLL herr_t H5S_select_serialize(const H5S_t *space, uint8_t **p); 261 H5_DLL htri_t H5S_select_is_contiguous(const H5S_t *space); 262 H5_DLL htri_t H5S_select_is_single(const H5S_t *space); 263 H5_DLL htri_t H5S_select_is_regular(const H5S_t *space); 264 H5_DLL herr_t H5S_select_adjust_u(H5S_t *space, const hsize_t *offset); 265 H5_DLL herr_t H5S_select_project_scalar(const H5S_t *space, hsize_t *offset); 266 H5_DLL herr_t H5S_select_project_simple(const H5S_t *space, H5S_t *new_space, hsize_t *offset); 267 H5_DLL herr_t H5S_select_project_intersection(const H5S_t *src_space, 268 const H5S_t *dst_space, const H5S_t *src_intersect_space, 269 H5S_t **new_space_ptr); 270 H5_DLL herr_t H5S_select_subtract(H5S_t *space, H5S_t *subtract_space); 271 272 /* Operations on all selections */ 273 H5_DLL herr_t H5S_select_all(H5S_t *space, hbool_t rel_prev); 274 275 /* Operations on none selections */ 276 H5_DLL herr_t H5S_select_none(H5S_t *space); 277 278 /* Operations on point selections */ 279 H5_DLL herr_t H5S_select_elements(H5S_t *space, H5S_seloper_t op, 280 size_t num_elem, const hsize_t *coord); 281 282 /* Operations on hyperslab selections */ 283 H5_DLL herr_t H5S_select_hyperslab (H5S_t *space, H5S_seloper_t op, const hsize_t start[], 284 const hsize_t *stride, const hsize_t count[], const hsize_t *block); 285 H5_DLL herr_t H5S_hyper_add_span_element(H5S_t *space, unsigned rank, 286 hsize_t *coords); 287 H5_DLL herr_t H5S_hyper_reset_scratch(H5S_t *space); 288 H5_DLL herr_t H5S_hyper_convert(H5S_t *space); 289 #ifdef LATER 290 H5_DLL htri_t H5S_hyper_intersect (H5S_t *space1, H5S_t *space2); 291 #endif /* LATER */ 292 H5_DLL htri_t H5S_hyper_intersect_block (H5S_t *space, hsize_t *start, hsize_t *end); 293 H5_DLL herr_t H5S_hyper_adjust_s(H5S_t *space, const hssize_t *offset); 294 H5_DLL htri_t H5S_hyper_normalize_offset(H5S_t *space, hssize_t *old_offset); 295 H5_DLL herr_t H5S_hyper_denormalize_offset(H5S_t *space, const hssize_t *old_offset); 296 H5_DLL herr_t H5S_hyper_clip_unlim(H5S_t *space, hsize_t clip_size); 297 H5_DLL hsize_t H5S_hyper_get_clip_extent(const H5S_t *clip_space, 298 const H5S_t *match_space, hbool_t incl_trail); 299 H5_DLL hsize_t H5S_hyper_get_clip_extent_match(const H5S_t *clip_space, 300 const H5S_t *match_space, hsize_t match_clip_size, hbool_t incl_trail); 301 H5_DLL H5S_t *H5S_hyper_get_unlim_block(const H5S_t *space, 302 hsize_t block_index); 303 H5_DLL hsize_t H5S_hyper_get_first_inc_block(const H5S_t *space, 304 hsize_t clip_size, hbool_t *partial); 305 306 /* Operations on selection iterators */ 307 H5_DLL herr_t H5S_select_iter_init(H5S_sel_iter_t *iter, const H5S_t *space, size_t elmt_size); 308 H5_DLL herr_t H5S_select_iter_coords(const H5S_sel_iter_t *sel_iter, hsize_t *coords); 309 H5_DLL hsize_t H5S_select_iter_nelmts(const H5S_sel_iter_t *sel_iter); 310 H5_DLL herr_t H5S_select_iter_next(H5S_sel_iter_t *sel_iter, size_t nelem); 311 H5_DLL herr_t H5S_select_iter_release(H5S_sel_iter_t *sel_iter); 312 313 #ifdef H5_HAVE_PARALLEL 314 H5_DLL herr_t H5S_mpio_space_type(const H5S_t *space, size_t elmt_size, 315 /* out: */ MPI_Datatype *new_type, 316 int *count, 317 hbool_t *is_derived_type, 318 hbool_t do_permute, 319 hsize_t **permute_map, 320 hbool_t * is_permuted); 321 #endif /* H5_HAVE_PARALLEL */ 322 323 #endif /* _H5Sprivate_H */ 324 325