H5Sprivate.h

00001 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
00002  * Copyright by The HDF Group.                                               *
00003  * Copyright by the Board of Trustees of the University of Illinois.         *
00004  * All rights reserved.                                                      *
00005  *                                                                           *
00006  * This file is part of HDF5.  The full HDF5 copyright notice, including     *
00007  * terms governing use, modification, and redistribution, is contained in    *
00008  * the files COPYING and Copyright.html.  COPYING can be found at the root   *
00009  * of the source code distribution tree; Copyright.html can be found at the  *
00010  * root level of an installed copy of the electronic HDF5 document set and   *
00011  * is linked from the top-level documents page.  It can also be found at     *
00012  * http://hdfgroup.org/HDF5/doc/Copyright.html.  If you do not have          *
00013  * access to either file, you may request a copy from help@hdfgroup.org.     *
00014  * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
00015 
00016 /*
00017  * This file contains private information about the H5S module
00018  */
00019 #ifndef _H5Sprivate_H
00020 #define _H5Sprivate_H
00021 
00022 /* Include package's public header */
00023 #include "H5Spublic.h"
00024 
00025 /* Public headers needed by this file */
00026 #include "H5Dpublic.h"          /* Datasets                             */
00027 
00028 /* Private headers needed by this file */
00029 #include "H5private.h"          /* Generic Functions                    */
00030 #include "H5Fprivate.h"         /* Files                                */
00031 #include "H5Gprivate.h"         /* Groups                               */
00032 #include "H5Oprivate.h"         /* Object headers                       */
00033 #include "H5Pprivate.h"         /* Property lists                       */
00034 
00035 /* Flags for H5S_find */
00036 #define H5S_CONV_PAR_IO_POSSIBLE        0x0001
00037 /* The storage options are mutually exclusive */
00038 /* (2-bits reserved for storage type currently) */
00039 #define H5S_CONV_STORAGE_COMPACT        0x0000  /* i.e. '0' */
00040 #define H5S_CONV_STORAGE_CONTIGUOUS     0x0002  /* i.e. '1' */
00041 #define H5S_CONV_STORAGE_CHUNKED        0x0004  /* i.e. '2' */
00042 #define H5S_CONV_STORAGE_MASK           0x0006
00043 
00044 /* Flags for "get_seq_list" methods */
00045 #define H5S_GET_SEQ_LIST_SORTED         0x0001
00046 
00047 /* Forward references of package typedefs */
00048 typedef struct H5S_t H5S_t;
00049 typedef struct H5S_extent_t H5S_extent_t;
00050 typedef struct H5S_pnt_node_t H5S_pnt_node_t;
00051 typedef struct H5S_hyper_span_t H5S_hyper_span_t;
00052 typedef struct H5S_hyper_span_info_t H5S_hyper_span_info_t;
00053 
00054 /* Information about one dimension in a hyperslab selection */
00055 typedef struct H5S_hyper_dim_t {
00056     hsize_t start;
00057     hsize_t stride;
00058     hsize_t count;
00059     hsize_t block;
00060 } H5S_hyper_dim_t;
00061 
00062 /* Point selection iteration container */
00063 typedef struct {
00064     H5S_pnt_node_t *curr;   /* Pointer to next node to output */
00065 } H5S_point_iter_t;
00066 
00067 /* Hyperslab selection iteration container */
00068 typedef struct {
00069     /* Common fields for all hyperslab selections */
00070     hsize_t off[H5S_MAX_RANK];          /* Offset in span node (used as position for regular hyperslabs) */
00071     unsigned iter_rank;     /* Rank of iterator information */
00072                             /* (This should always be the same as the dataspace
00073                              * rank, except for regular hyperslab selections in
00074                              * which there are contiguous regions in the lower
00075                              * dimensions which have been "flattened" out
00076                              */
00077     hbool_t diminfo_valid;         /* Whether the dimension information is valid */
00078 
00079     /* "Flattened" regular hyperslab selection fields */
00080     H5S_hyper_dim_t diminfo[H5S_MAX_RANK];   /* "Flattened" regular selection information */
00081     hsize_t size[H5S_MAX_RANK];         /* "Flattened" dataspace extent information */
00082     hssize_t sel_off[H5S_MAX_RANK];     /* "Flattened" selection offset information */
00083     hbool_t flattened[H5S_MAX_RANK];    /* Whether this dimension has been flattened */
00084 
00085     /* Irregular hyperslab selection fields */
00086     H5S_hyper_span_info_t *spans;  /* Pointer to copy of the span tree */
00087     H5S_hyper_span_t *span[H5S_MAX_RANK];/* Array of pointers to span nodes */
00088 } H5S_hyper_iter_t;
00089 
00090 /* "All" selection iteration container */
00091 typedef struct {
00092     hsize_t elmt_offset;         /* Next element to output */
00093     hsize_t byte_offset;         /* Next byte to output */
00094 } H5S_all_iter_t;
00095 
00096 /* Forward declaration of selection iteration class */
00097 struct H5S_sel_iter_class_t;
00098 
00099 /* Selection iteration container */
00100 typedef struct H5S_sel_iter_t {
00101     /* Selection class */
00102     const struct H5S_sel_iter_class_t *type; /* Selection iteration class info */
00103 
00104     /* Information common to all iterators */
00105     unsigned rank;              /* Rank of dataspace the selection iterator is operating on */
00106     hsize_t *dims;              /* Dimensions of dataspace the selection is operating on */
00107     hsize_t elmt_left;          /* Number of elements left to iterate over */
00108     size_t elmt_size;           /* Size of elements to iterate over */
00109 
00110     /* Information specific to each type of iterator */
00111     union {
00112         H5S_point_iter_t pnt;   /* Point selection iteration information */
00113         H5S_hyper_iter_t hyp;   /* New Hyperslab selection iteration information */
00114         H5S_all_iter_t all;     /* "All" selection iteration information */
00115     } u;
00116 } H5S_sel_iter_t;
00117 
00118 /* If the module using this macro is allowed access to the private variables, access them directly */
00119 #ifdef H5S_PACKAGE
00120 #define H5S_GET_EXTENT_TYPE(S)          ((S)->extent.type)
00121 #define H5S_GET_EXTENT_NDIMS(S)         ((S)->extent.rank)
00122 #define H5S_GET_EXTENT_NPOINTS(S)       ((S)->extent.nelem)
00123 #define H5S_GET_SELECT_NPOINTS(S)       ((S)->select.num_elem)
00124 #define H5S_GET_SELECT_TYPE(S)          ((S)->select.type->type)
00125 #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))
00126 #define H5S_SELECT_VALID(S)             ((*(S)->select.type->is_valid)(S))
00127 #define H5S_SELECT_RELEASE(S)           ((*(S)->select.type->release)(S))
00128 #define H5S_SELECT_SERIAL_SIZE(S)       ((*(S)->select.type->serial_size)(S))
00129 #define H5S_SELECT_SERIALIZE(S,BUF)     ((*(S)->select.type->serialize)(S,BUF))
00130 #define H5S_SELECT_BOUNDS(S,START,END)  ((*(S)->select.type->bounds)(S,START,END))
00131 #define H5S_SELECT_OFFSET(S, OFFSET)    ((*(S)->select.type->offset)(S, OFFSET))
00132 #define H5S_SELECT_IS_CONTIGUOUS(S)     ((*(S)->select.type->is_contiguous)(S))
00133 #define H5S_SELECT_IS_SINGLE(S)         ((*(S)->select.type->is_single)(S))
00134 #define H5S_SELECT_IS_REGULAR(S)        ((*(S)->select.type->is_regular)(S))
00135 #define H5S_SELECT_ADJUST_U(S,O)        ((*(S)->select.type->adjust_u)(S, O))
00136 #define H5S_SELECT_ITER_COORDS(ITER,COORDS)     ((*(ITER)->type->iter_coords)(ITER,COORDS))
00137 #define H5S_SELECT_ITER_BLOCK(ITER,START,END)   ((*(ITER)->type->iter_block)(ITER,START,END))
00138 #define H5S_SELECT_ITER_NELMTS(ITER)    ((*(ITER)->type->iter_nelmts)(ITER))
00139 #define H5S_SELECT_ITER_HAS_NEXT_BLOCK(ITER)    ((*(ITER)->type->iter_has_next_block)(ITER))
00140 #define H5S_SELECT_ITER_NEXT(ITER,NELEM)((*(ITER)->type->iter_next)(ITER,NELEM))
00141 #define H5S_SELECT_ITER_NEXT_BLOCK(ITER)        ((*(ITER)->type->iter_next_block)(ITER))
00142 #define H5S_SELECT_ITER_RELEASE(ITER)   ((*(ITER)->type->iter_release)(ITER))
00143 #else /* H5S_PACKAGE */
00144 #define H5S_GET_EXTENT_TYPE(S)          (H5S_get_simple_extent_type(S))
00145 #define H5S_GET_EXTENT_NDIMS(S)         (H5S_get_simple_extent_ndims(S))
00146 #define H5S_GET_EXTENT_NPOINTS(S)       (H5S_get_simple_extent_npoints(S))
00147 #define H5S_GET_SELECT_NPOINTS(S)       (H5S_get_select_npoints(S))
00148 #define H5S_GET_SELECT_TYPE(S)          (H5S_get_select_type(S))
00149 #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))
00150 #define H5S_SELECT_VALID(S)             (H5S_select_valid(S))
00151 #define H5S_SELECT_RELEASE(S)           (H5S_select_release(S))
00152 #define H5S_SELECT_SERIAL_SIZE(S)       (H5S_select_serial_size(S))
00153 #define H5S_SELECT_SERIALIZE(S,BUF)     (H5S_select_serialize(S,BUF))
00154 #define H5S_SELECT_BOUNDS(S,START,END)  (H5S_get_select_bounds(S,START,END))
00155 #define H5S_SELECT_OFFSET(S, OFFSET)    (H5S_get_select_offset(S, OFFSET))
00156 #define H5S_SELECT_IS_CONTIGUOUS(S)     (H5S_select_is_contiguous(S))
00157 #define H5S_SELECT_IS_SINGLE(S)         (H5S_select_is_single(S))
00158 #define H5S_SELECT_IS_REGULAR(S)        (H5S_select_is_regular(S))
00159 #define H5S_SELECT_ADJUST_U(S,O)        (H5S_select_adjust_u(S, O))
00160 #define H5S_SELECT_ITER_COORDS(ITER,COORDS)     (H5S_select_iter_coords(ITER,COORDS))
00161 #define H5S_SELECT_ITER_BLOCK(ITER,START,END)   (H5S_select_iter_block(ITER,START,END))
00162 #define H5S_SELECT_ITER_NELMTS(ITER)    (H5S_select_iter_nelmts(ITER))
00163 #define H5S_SELECT_ITER_HAS_NEXT_BLOCK(ITER)    (H5S_select_iter_has_next_block(ITER))
00164 #define H5S_SELECT_ITER_NEXT(ITER,NELEM)(H5S_select_iter_next(ITER,NELEM))
00165 #define H5S_SELECT_ITER_NEXT_BLOCK(ITER)        (H5S_select_iter_next_block(ITER))
00166 #define H5S_SELECT_ITER_RELEASE(ITER)   (H5S_select_iter_release(ITER))
00167 #endif /* H5S_PACKAGE */
00168 /* Handle these two callbacks in a special way, since they have prologs that need to be executed */
00169 #define H5S_SELECT_COPY(DST,SRC,SHARE)  (H5S_select_copy(DST,SRC,SHARE))
00170 #define H5S_SELECT_DESERIALIZE(S,BUF)   (H5S_select_deserialize(S,BUF))
00171 
00172 
00173 /* Operations on dataspaces */
00174 H5_DLL H5S_t *H5S_copy(const H5S_t *src, hbool_t share_selection, hbool_t copy_max);
00175 H5_DLL herr_t H5S_close(H5S_t *ds);
00176 H5_DLL H5S_class_t H5S_get_simple_extent_type(const H5S_t *ds);
00177 H5_DLL hssize_t H5S_get_simple_extent_npoints(const H5S_t *ds);
00178 H5_DLL hsize_t H5S_get_npoints_max(const H5S_t *ds);
00179 H5_DLL hbool_t H5S_has_extent(const H5S_t *ds);
00180 H5_DLL int H5S_get_simple_extent_ndims(const H5S_t *ds);
00181 H5_DLL int H5S_get_simple_extent_dims(const H5S_t *ds, hsize_t dims[]/*out*/,
00182     hsize_t max_dims[]/*out*/);
00183 H5_DLL herr_t H5S_write(H5F_t *f, hid_t dxpl_id, H5O_t *oh, unsigned update_flags,
00184     H5S_t *ds);
00185 H5_DLL herr_t H5S_append(H5F_t *f, hid_t dxpl_id, struct H5O_t *oh, H5S_t *ds);
00186 H5_DLL H5S_t *H5S_read(const struct H5O_loc_t *loc, hid_t dxpl_id);
00187 H5_DLL htri_t H5S_set_extent(H5S_t *space, const hsize_t *size);
00188 H5_DLL herr_t H5S_set_extent_real(H5S_t *space, const hsize_t *size);
00189 H5_DLL H5S_t *H5S_create(H5S_class_t type);
00190 H5_DLL H5S_t *H5S_create_simple(unsigned rank, const hsize_t dims[/*rank*/],
00191     const hsize_t maxdims[/*rank*/]);
00192 H5_DLL herr_t H5S_set_latest_version(H5S_t *ds);
00193 H5_DLL herr_t H5S_debug(H5F_t *f, hid_t dxpl_id, const void *_mesg, FILE *stream,
00194     int indent, int fwidth);
00195 #ifndef H5_NO_DEPRECATED_SYMBOLS
00196 H5_DLL int H5S_extend(H5S_t *space, const hsize_t *size);
00197 #endif /* H5_NO_DEPRECATED_SYMBOLS */
00198 
00199 /* Operations on dataspace extents */
00200 H5_DLL hsize_t H5S_extent_nelem(const H5S_extent_t *ext);
00201 H5_DLL int H5S_extent_get_dims(const H5S_extent_t *ext, hsize_t dims[], hsize_t max_dims[]);
00202 H5_DLL htri_t H5S_extent_equal(const H5S_t *ds1, const H5S_t *ds2);
00203 
00204 /* Operations on selections */
00205 H5_DLL herr_t H5S_select_deserialize(H5S_t *space, const uint8_t *buf);
00206 H5_DLL H5S_sel_type H5S_get_select_type(const H5S_t *space);
00207 H5_DLL herr_t H5S_select_iterate(void *buf, hid_t type_id, const H5S_t *space,
00208     H5D_operator_t op, void *operator_data);
00209 H5_DLL herr_t H5S_select_fill(const void *fill, size_t fill_size,
00210     const H5S_t *space, void *buf);
00211 H5_DLL htri_t H5S_select_valid(const H5S_t *space);
00212 H5_DLL hssize_t H5S_get_select_npoints(const H5S_t *space);
00213 H5_DLL herr_t H5S_get_select_bounds(const H5S_t *space, hsize_t *start, hsize_t *end);
00214 H5_DLL herr_t H5S_get_select_offset(const H5S_t *space, hsize_t *offset);
00215 H5_DLL herr_t H5S_select_offset(H5S_t *space, const hssize_t *offset);
00216 H5_DLL herr_t H5S_select_copy(H5S_t *dst, const H5S_t *src, hbool_t share_selection);
00217 H5_DLL htri_t H5S_select_shape_same(const H5S_t *space1, const H5S_t *space2);
00218 H5_DLL herr_t H5S_select_release(H5S_t *ds);
00219 H5_DLL herr_t H5S_select_get_seq_list(const H5S_t *space, unsigned flags,
00220     H5S_sel_iter_t *iter, size_t maxseq, size_t maxbytes,
00221     size_t *nseq, size_t *nbytes, hsize_t *off, size_t *len);
00222 H5_DLL hssize_t H5S_select_serial_size(const H5S_t *space);
00223 H5_DLL herr_t H5S_select_serialize(const H5S_t *space, uint8_t *buf);
00224 H5_DLL htri_t H5S_select_is_contiguous(const H5S_t *space);
00225 H5_DLL htri_t H5S_select_is_single(const H5S_t *space);
00226 H5_DLL htri_t H5S_select_is_regular(const H5S_t *space);
00227 H5_DLL herr_t H5S_select_adjust_u(H5S_t *space, const hsize_t *offset);
00228 
00229 /* Operations on all selections */
00230 H5_DLL herr_t H5S_select_all(H5S_t *space, hbool_t rel_prev);
00231 
00232 /* Operations on none selections */
00233 H5_DLL herr_t H5S_select_none(H5S_t *space);
00234 
00235 /* Operations on point selections */
00236 H5_DLL herr_t H5S_select_elements(H5S_t *space, H5S_seloper_t op,
00237     size_t num_elem, const hsize_t *coord);
00238 
00239 /* Operations on hyperslab selections */
00240 H5_DLL herr_t H5S_select_hyperslab (H5S_t *space, H5S_seloper_t op, const hsize_t start[],
00241     const hsize_t *stride, const hsize_t count[], const hsize_t *block);
00242 H5_DLL herr_t H5S_hyper_add_span_element(H5S_t *space, unsigned rank,
00243     hsize_t *coords);
00244 H5_DLL herr_t H5S_hyper_reset_scratch(H5S_t *space);
00245 H5_DLL herr_t H5S_hyper_convert(H5S_t *space);
00246 #ifdef LATER
00247 H5_DLL htri_t H5S_hyper_intersect (H5S_t *space1, H5S_t *space2);
00248 #endif /* LATER */
00249 H5_DLL htri_t H5S_hyper_intersect_block (H5S_t *space, hsize_t *start, hsize_t *end);
00250 H5_DLL herr_t H5S_hyper_adjust_s(H5S_t *space, const hssize_t *offset);
00251 H5_DLL herr_t H5S_hyper_move(H5S_t *space, const hssize_t *offset);
00252 H5_DLL htri_t H5S_hyper_normalize_offset(H5S_t *space, hssize_t *old_offset);
00253 H5_DLL herr_t H5S_hyper_denormalize_offset(H5S_t *space, const hssize_t *old_offset);
00254 
00255 /* Operations on selection iterators */
00256 H5_DLL herr_t H5S_select_iter_init(H5S_sel_iter_t *iter, const H5S_t *space, size_t elmt_size);
00257 H5_DLL herr_t H5S_select_iter_coords(const H5S_sel_iter_t *sel_iter, hsize_t *coords);
00258 H5_DLL hsize_t H5S_select_iter_nelmts(const H5S_sel_iter_t *sel_iter);
00259 H5_DLL herr_t H5S_select_iter_next(H5S_sel_iter_t *sel_iter, size_t nelem);
00260 H5_DLL herr_t H5S_select_iter_release(H5S_sel_iter_t *sel_iter);
00261 
00262 #ifdef H5_HAVE_PARALLEL
00263 /* Global vars whose value comes from environment variable */
00264 /* (Defined in H5S.c) */
00265 H5_DLLVAR hbool_t               H5S_mpi_opt_types_g;
00266 
00267 H5_DLL herr_t
00268 H5S_mpio_space_type( const H5S_t *space, size_t elmt_size,
00269      /* out: */
00270      MPI_Datatype *new_type,
00271      size_t *count,
00272      hsize_t *extra_offset,
00273      hbool_t *is_derived_type );
00274 
00275 H5_DLL herr_t
00276 H5S_mpio_space_span_type( const H5S_t *space, size_t elmt_size,
00277      /* out: */
00278      MPI_Datatype *new_type,
00279      size_t *count,
00280      hsize_t *extra_offset,
00281      hbool_t *is_derived_type );
00282 
00283 #endif /* H5_HAVE_PARALLEL */
00284 
00285 #endif /* _H5Sprivate_H */
00286