/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *

 * 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 LICENSE 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.                                                        *

 * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */

/*

 * Purpose:     Hyperslab selection dataspace I/O functions.

 */

/****************/

/* Module Setup */

/****************/

#include "H5Smodule.h" /* This source code file is part of the H5S module */

/***********/

/* Headers */

/***********/

#include "H5private.h"   /* Generic Functions                        */

#include "H5CXprivate.h" /* API Contexts                             */

#include "H5Eprivate.h"  /* Error handling                           */

#include "H5FLprivate.h" /* Free Lists                               */

#include "H5Iprivate.h"  /* ID Functions                             */

#include "H5MMprivate.h" /* Memory management                        */

#include "H5Spkg.h"      /* Dataspace functions                      */

#include "H5VMprivate.h" /* Vector functions                         */

/****************/

/* Local Macros */

/****************/

/* Flags for which hyperslab fragments to compute */

#define H5S_HYPER_COMPUTE_B_NOT_A 0x01

#define H5S_HYPER_COMPUTE_A_AND_B 0x02

#define H5S_HYPER_COMPUTE_A_NOT_B 0x04

/* Macro to advance a span, possibly recycling it first */

#define H5S_HYPER_ADVANCE_SPAN(recover, curr_span, next_span, ERR)                                           \

    do {                                                                                                     \

        H5S_hyper_span_t *saved_next_span = (next_span);                                                     \

                                                                                                             \

        /* Check if the span should be recovered */                                                          \

        if (recover) {                                                                                       \

            if (H5S__hyper_free_span(curr_span) < 0)                                                         \

                HGOTO_ERROR(H5E_DATASPACE, H5E_CANTFREE, ERR, "unable to free span");                        \

            (recover) = false;                                                                               \

        }                                                                                                    \

                                                                                                             \

        /* Set the current span to saved next span */                                                        \

        (curr_span) = saved_next_span;                                                                       \

    } while (0)

/* Macro to add "skipped" elements to projection during the execution of

 * H5S__hyper_project_intersect() */

#define H5S_HYPER_PROJ_INT_ADD_SKIP(UDATA, ADD, ERR)                                                         \

    do {                                                                                                     \

        /* If there are any elements to add, we must add them                                                \

         * to the projection first before adding skip */                                                     \

        if ((UDATA)->nelem > 0)                                                                              \

            if (H5S__hyper_proj_int_build_proj(UDATA) < 0)                                                   \

                HGOTO_ERROR(H5E_DATASPACE, H5E_CANTAPPEND, ERR,                                              \

                            "can't add elements to projected selection");                                    \

        (UDATA)->skip += (ADD);                                                                              \

    } while (0) /* end H5S_HYPER_PROJ_INT_ADD_SKIP() */

/******************/

/* Local Typedefs */

/******************/

/* Define alias for hsize_t, for allocating H5S_hyper_span_info_t + bounds objects */

/* (Makes it easier to understand the alloc / free calls) */

typedef hsize_t hbounds_t;

/* Struct for holding persistent information during iteration for

 * H5S__hyper_project_intersect() */

typedef struct {

    const H5S_hyper_span_t

           *ds_span[H5S_MAX_RANK]; /* Array of the current spans in the destination space in each dimension */

    hsize_t ds_low[H5S_MAX_RANK]; /* Array of current low bounds (of iteration) for each element in ds_span */

    H5S_hyper_span_info_t

            *ps_span_info[H5S_MAX_RANK]; /* Array of span info structs for projected space during iteration */

    uint32_t ps_clean_bitmap; /* Bitmap of whether the nth rank has a clean projected space since the last

                                 time it was set to 1 */

    unsigned ss_rank;         /* Rank of source space */

    unsigned ds_rank;         /* Rank of destination space */

    unsigned depth;           /* Current depth of iterator in destination space */

    hsize_t  skip;            /* Number of elements to skip in projected space */

    hsize_t  nelem;           /* Number of elements to add to projected space (after skip) */

    uint64_t op_gen;          /* Operation generation for counting elements */

    bool     share_selection; /* Whether span trees in dst_space can be shared with proj_space */

} H5S_hyper_project_intersect_ud_t;

/* Assert that H5S_MAX_RANK is <= 32 so our trick with using a 32 bit bitmap

 * (ps_clean_bitmap) works.  If H5S_MAX_RANK increases either increase the size

 * of ps_clean_bitmap or change the algorithm to use an array. */

#if H5S_MAX_RANK > 32

#error H5S_MAX_RANK too large for ps_clean_bitmap field in H5S_hyper_project_intersect_ud_t struct

#endif

/********************/

/* Local Prototypes */

/********************/

static H5S_hyper_span_t      *H5S__hyper_new_span(hsize_t low, hsize_t high, H5S_hyper_span_info_t *down,

                                                  H5S_hyper_span_t *next);

static H5S_hyper_span_info_t *H5S__hyper_new_span_info(unsigned rank);

static H5S_hyper_span_info_t *H5S__hyper_copy_span_helper(H5S_hyper_span_info_t *spans, unsigned rank,

                                                          unsigned op_info_i, uint64_t op_gen);

static H5S_hyper_span_info_t *H5S__hyper_copy_span(H5S_hyper_span_info_t *spans, unsigned rank);

static bool                   H5S__hyper_cmp_spans(const H5S_hyper_span_info_t *span_info1,

                                                   const H5S_hyper_span_info_t *span_info2);

static herr_t                 H5S__hyper_free_span_info(H5S_hyper_span_info_t *span_info);

static herr_t                 H5S__hyper_free_span(H5S_hyper_span_t *span);

static herr_t H5S__hyper_span_blocklist(const H5S_hyper_span_info_t *spans, hsize_t start[], hsize_t end[],

                                        hsize_t rank, hsize_t *startblock, hsize_t *numblocks, hsize_t **buf);

static herr_t H5S__get_select_hyper_blocklist(H5S_t *space, hsize_t startblock, hsize_t numblocks,

                                              hsize_t *buf);

static H5S_hyper_span_t *H5S__hyper_coord_to_span(unsigned rank, const hsize_t *coords);

static herr_t  H5S__hyper_append_span(H5S_hyper_span_info_t **span_tree, unsigned ndims, hsize_t low,

                                      hsize_t high, H5S_hyper_span_info_t *down);

static herr_t  H5S__hyper_clip_spans(H5S_hyper_span_info_t *a_spans, H5S_hyper_span_info_t *b_spans,

                                     unsigned selector, unsigned ndims, H5S_hyper_span_info_t **a_not_b,

                                     H5S_hyper_span_info_t **a_and_b, H5S_hyper_span_info_t **b_not_a);

static herr_t  H5S__hyper_merge_spans(H5S_t *space, H5S_hyper_span_info_t *new_spans);

static hsize_t H5S__hyper_spans_nelem_helper(H5S_hyper_span_info_t *spans, unsigned op_info_i,

                                             uint64_t op_gen);

static hsize_t H5S__hyper_spans_nelem(H5S_hyper_span_info_t *spans);

static herr_t  H5S__hyper_add_disjoint_spans(H5S_t *space, H5S_hyper_span_info_t *new_spans);

static H5S_hyper_span_info_t *H5S__hyper_make_spans(unsigned rank, const hsize_t *start,

                                                    const hsize_t *stride, const hsize_t *count,

                                                    const hsize_t *block);

static herr_t                 H5S__hyper_update_diminfo(H5S_t *space, H5S_seloper_t op,

                                                        const H5S_hyper_dim_t *new_hyper_diminfo);

static herr_t                 H5S__hyper_generate_spans(H5S_t *space);

static bool                   H5S__check_spans_overlap(const H5S_hyper_span_info_t *spans1,

                                                       const H5S_hyper_span_info_t *spans2);

static herr_t  H5S__fill_in_new_space(H5S_t *space1, H5S_seloper_t op, H5S_hyper_span_info_t *space2_span_lst,

                                      bool can_own_span2, bool *span2_owned, bool *updated_spans,

                                      H5S_t **result);

static herr_t  H5S__generate_hyperslab(H5S_t *space, H5S_seloper_t op, const hsize_t start[],

                                       const hsize_t stride[], const hsize_t count[], const hsize_t block[]);

static herr_t  H5S__set_regular_hyperslab(H5S_t *space, const hsize_t start[], const hsize_t *app_stride,

                                          const hsize_t app_count[], const hsize_t *app_block,

                                          const hsize_t *opt_stride, const hsize_t opt_count[],

                                          const hsize_t *opt_block);

static herr_t  H5S__fill_in_select(H5S_t *space1, H5S_seloper_t op, H5S_t *space2, H5S_t **result);

static H5S_t  *H5S__combine_select(H5S_t *space1, H5S_seloper_t op, H5S_t *space2);

static herr_t  H5S__hyper_iter_get_seq_list_gen(H5S_sel_iter_t *iter, size_t maxseq, size_t maxelem,

                                                size_t *nseq, size_t *nelem, hsize_t *off, size_t *len);

static herr_t  H5S__hyper_iter_get_seq_list_opt(H5S_sel_iter_t *iter, size_t maxseq, size_t maxelem,

                                                size_t *nseq, size_t *nelem, hsize_t *off, size_t *len);

static herr_t  H5S__hyper_iter_get_seq_list_single(H5S_sel_iter_t *iter, size_t maxseq, size_t maxelem,

                                                   size_t *nseq, size_t *nelem, hsize_t *off, size_t *len);

static herr_t  H5S__hyper_proj_int_build_proj(H5S_hyper_project_intersect_ud_t *udata);

static herr_t  H5S__hyper_proj_int_iterate(H5S_hyper_span_info_t       *ss_span_info,

                                           const H5S_hyper_span_info_t *sis_span_info, hsize_t count,

                                           unsigned depth, H5S_hyper_project_intersect_ud_t *udata);

static void    H5S__hyper_get_clip_diminfo(hsize_t start, hsize_t stride, hsize_t *count, hsize_t *block,

                                           hsize_t clip_size);

static hsize_t H5S__hyper_get_clip_extent_real(const H5S_t *clip_space, hsize_t num_slices, bool incl_trail);

/* Selection callbacks */

static herr_t   H5S__hyper_copy(H5S_t *dst, const H5S_t *src, bool share_selection);

static herr_t   H5S__hyper_release(H5S_t *space);

static htri_t   H5S__hyper_is_valid(const H5S_t *space);

static hsize_t  H5S__hyper_span_nblocks(H5S_hyper_span_info_t *spans);

static hssize_t H5S__hyper_serial_size(H5S_t *space);

static herr_t   H5S__hyper_serialize(H5S_t *space, uint8_t **p);

static herr_t   H5S__hyper_deserialize(H5S_t **space, const uint8_t **p, const size_t p_size, bool skip);

static herr_t   H5S__hyper_bounds(const H5S_t *space, hsize_t *start, hsize_t *end);

static herr_t   H5S__hyper_offset(const H5S_t *space, hsize_t *offset);

static int      H5S__hyper_unlim_dim(const H5S_t *space);

static herr_t   H5S__hyper_num_elem_non_unlim(const H5S_t *space, hsize_t *num_elem_non_unlim);

static htri_t   H5S__hyper_is_contiguous(const H5S_t *space);

static htri_t   H5S__hyper_is_single(const H5S_t *space);

static htri_t   H5S__hyper_is_regular(H5S_t *space);

static htri_t   H5S__hyper_shape_same(H5S_t *space1, H5S_t *space2);

static htri_t   H5S__hyper_intersect_block(H5S_t *space, const hsize_t *start, const hsize_t *end);

static herr_t   H5S__hyper_adjust_u(H5S_t *space, const hsize_t *offset);

static herr_t   H5S__hyper_adjust_s(H5S_t *space, const hssize_t *offset);

static herr_t   H5S__hyper_project_scalar(const H5S_t *space, hsize_t *offset);

static herr_t   H5S__hyper_project_simple(const H5S_t *space, H5S_t *new_space, hsize_t *offset);

static herr_t   H5S__hyper_iter_init(H5S_t *space, H5S_sel_iter_t *iter);

/* Selection iteration callbacks */

static herr_t  H5S__hyper_iter_coords(const H5S_sel_iter_t *iter, hsize_t *coords);

static herr_t  H5S__hyper_iter_block(const H5S_sel_iter_t *iter, hsize_t *start, hsize_t *end);

static hsize_t H5S__hyper_iter_nelmts(const H5S_sel_iter_t *iter);

static htri_t  H5S__hyper_iter_has_next_block(const H5S_sel_iter_t *sel_iter);

static herr_t  H5S__hyper_iter_next(H5S_sel_iter_t *sel_iter, size_t nelem);

static herr_t  H5S__hyper_iter_next_block(H5S_sel_iter_t *sel_iter);

static herr_t H5S__hyper_iter_get_seq_list(H5S_sel_iter_t *iter, size_t maxseq, size_t maxbytes, size_t *nseq,

                                           size_t *nbytes, hsize_t *off, size_t *len);

static herr_t H5S__hyper_iter_release(H5S_sel_iter_t *sel_iter);

/*****************************/

/* Library Private Variables */

/*****************************/

/*********************/

/* Package Variables */

/*********************/

/* Selection properties for hyperslab selections */

const H5S_select_class_t H5S_sel_hyper[1] = {{

    H5S_SEL_HYPERSLABS,

    /* Methods on selection */

    H5S__hyper_copy,

    H5S__hyper_release,

    H5S__hyper_is_valid,

    H5S__hyper_serial_size,

    H5S__hyper_serialize,

    H5S__hyper_deserialize,

    H5S__hyper_bounds,

    H5S__hyper_offset,

    H5S__hyper_unlim_dim,

    H5S__hyper_num_elem_non_unlim,

    H5S__hyper_is_contiguous,

    H5S__hyper_is_single,

    H5S__hyper_is_regular,

    H5S__hyper_shape_same,

    H5S__hyper_intersect_block,

    H5S__hyper_adjust_u,

    H5S__hyper_adjust_s,

    H5S__hyper_project_scalar,

    H5S__hyper_project_simple,

    H5S__hyper_iter_init,

}};

/* Format version bounds for dataspace hyperslab selection */

static const unsigned H5O_sds_hyper_ver_bounds[] = {

    H5S_HYPER_VERSION_1, /* H5F_LIBVER_EARLIEST */

    H5S_HYPER_VERSION_1, /* H5F_LIBVER_V18 */

    H5S_HYPER_VERSION_2, /* H5F_LIBVER_V110 */

    H5S_HYPER_VERSION_3, /* H5F_LIBVER_V112 */

    H5S_HYPER_VERSION_3, /* H5F_LIBVER_V114 */

    H5S_HYPER_VERSION_3, /* H5F_LIBVER_V200 */

    H5S_HYPER_VERSION_3  /* H5F_LIBVER_LATEST */

};

/*******************/

/* Local Variables */

/*******************/

/* Iteration properties for hyperslab selections */

static const H5S_sel_iter_class_t H5S_sel_iter_hyper[1] = {{

    H5S_SEL_HYPERSLABS,

    /* Methods on selection iterator */

    H5S__hyper_iter_coords,

    H5S__hyper_iter_block,

    H5S__hyper_iter_nelmts,

    H5S__hyper_iter_has_next_block,

    H5S__hyper_iter_next,

    H5S__hyper_iter_next_block,

    H5S__hyper_iter_get_seq_list,

    H5S__hyper_iter_release,

}};

/* Arrays for default stride, block, etc. */

static const hsize_t H5S_hyper_zeros_g[H5S_MAX_RANK] = {0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,

                                                        0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0};

static const hsize_t H5S_hyper_ones_g[H5S_MAX_RANK]  = {1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1,

                                                        1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1};

/* Declare a free list to manage the H5S_hyper_sel_t struct */

H5FL_DEFINE_STATIC(H5S_hyper_sel_t);

/* Declare a free list to manage the H5S_hyper_span_t struct */

H5FL_DEFINE_STATIC(H5S_hyper_span_t);

/* Declare a free list to manage the H5S_hyper_span_info_t + hsize_t array struct */

H5FL_BARR_DEFINE_STATIC(H5S_hyper_span_info_t, hbounds_t, H5S_MAX_RANK * 2);

/* Declare extern free list to manage the H5S_sel_iter_t struct */

H5FL_EXTERN(H5S_sel_iter_t);

/* Current operation generation */

/* (Start with '1' to avoid clashing with '0' value in newly allocated structs) */

static uint64_t H5S_hyper_op_gen_g = 1;

/* Uncomment this to provide the debugging routines for printing selection info */

/* #define H5S_HYPER_DEBUG */

#ifdef H5S_HYPER_DEBUG

static herr_t

H5S__hyper_print_spans_helper(FILE *f, const H5S_hyper_span_t *span, unsigned depth)

{

    FUNC_ENTER_PACKAGE_NOERR

    while (span) {

        fprintf(f, "%s: %*sdepth=%u, span=%p, (%" PRIuHSIZE ", %" PRIuHSIZE "), next=%p\n", __func__,

                depth * 2, "", depth, (void *)span, span->low, span->high, (void *)span->next);

        if (span->down) {

            fprintf(f, "%s: %*sspans=%p, count=%u, bounds[0]={%" PRIuHSIZE ", %" PRIuHSIZE "}, head=%p\n",

                    __func__, (depth + 1) * 2, "", (void *)span->down, span->down->count,

                    span->down->low_bounds[0], span->down->high_bounds[0], (void *)span->down->head);

            H5S__hyper_print_spans_helper(f, span->down->head, depth + 1);

        } /* end if */

        span = span->next;

    } /* end while */

    FUNC_LEAVE_NOAPI(SUCCEED)

}

static herr_t

H5S__hyper_print_spans(FILE *f, const H5S_hyper_span_info_t *span_lst)

{

    FUNC_ENTER_PACKAGE_NOERR

    if (span_lst != NULL) {

        fprintf(f, "%s: spans=%p, count=%u, bounds[0]={%" PRIuHSIZE ", %" PRIuHSIZE "}, head=%p\n", __func__,

                (void *)span_lst, span_lst->count, span_lst->low_bounds[0], span_lst->high_bounds[0],

                (void *)span_lst->head);

        H5S__hyper_print_spans_helper(f, span_lst->head, 0);

    } /* end if */

    FUNC_LEAVE_NOAPI(SUCCEED)

}

static herr_t

H5S__space_print_spans(FILE *f, const H5S_t *space)

{

    FUNC_ENTER_PACKAGE_NOERR

    H5S__hyper_print_spans(f, space->select.sel_info.hslab->span_lst);

    FUNC_LEAVE_NOAPI(SUCCEED)

}

static herr_t

H5S__hyper_print_diminfo_helper(FILE *f, const char *field, unsigned ndims, const H5S_hyper_dim_t *dinfo)

{

    unsigned u; /* Local index variable */

    FUNC_ENTER_PACKAGE_NOERR

    if (dinfo != NULL) {

        fprintf(f, "%s: %s: start=[", __func__, field);

        for (u = 0; u < ndims; u++)

            fprintf(f, "%" PRIuHSIZE "%s", dinfo[u].start, (u < (ndims - 1) ? ", " : "]\n"));

        fprintf(f, "%s: %s: stride=[", __func__, field);

        for (u = 0; u < ndims; u++)

            fprintf(f, "%" PRIuHSIZE "%s", dinfo[u].stride, (u < (ndims - 1) ? ", " : "]\n"));

        fprintf(f, "%s: %s: count=[", __func__, field);

        for (u = 0; u < ndims; u++)

            fprintf(f, "%" PRIuHSIZE "%s", dinfo[u].count, (u < (ndims - 1) ? ", " : "]\n"));

        fprintf(f, "%s: %s: block=[", __func__, field);

        for (u = 0; u < ndims; u++)

            fprintf(f, "%" PRIuHSIZE "%s", dinfo[u].block, (u < (ndims - 1) ? ", " : "]\n"));

    } /* end if */

    else

        fprintf(f, "%s: %s==NULL\n", __func__, field);

    FUNC_LEAVE_NOAPI(SUCCEED)

}

static herr_t

H5S__hyper_print_diminfo(FILE *f, const H5S_t *space)

{

    FUNC_ENTER_PACKAGE_NOERR

    H5S__hyper_print_diminfo_helper(f, "diminfo.opt", space->extent.rank,

                                    space->select.sel_info.hslab->diminfo.opt);

    H5S__hyper_print_diminfo_helper(f, "diminfo.app", space->extent.rank,

                                    space->select.sel_info.hslab->diminfo.app);

    FUNC_LEAVE_NOAPI(SUCCEED)

}

/*--------------------------------------------------------------------------

 NAME

    H5S__hyper_print_spans_dfs

 PURPOSE

    Output the span elements for one span list in depth-first order

 USAGE

    herr_t H5S__hyper_print_spans_dfs(f, span_lst, depth)

        FILE *f;                                  IN: the file to output

        const H5S_hyper_span_info_t *span_lst;    IN: the span list to output

        unsigned depth;                           IN: the level of this span list

 RETURNS

    non-negative on success, negative on failure

 GLOBAL VARIABLES

 COMMENTS, BUGS, ASSUMPTIONS

 EXAMPLES

 REVISION LOG

--------------------------------------------------------------------------*/

static herr_t

H5S__hyper_print_spans_dfs(FILE *f, const H5S_hyper_span_info_t *span_lst, unsigned depth, unsigned dims)

{

    H5S_hyper_span_t *actual_tail = NULL;

    H5S_hyper_span_t *cur_elem;

    unsigned          num_elems = 0;

    unsigned          u, elem_idx;

    FUNC_ENTER_PACKAGE_NOERR

    /* get the actual tail from head */

    cur_elem = span_lst->head;

    assert(cur_elem); /* at least 1 element */

    while (cur_elem) {

        actual_tail = cur_elem;

        cur_elem    = cur_elem->next;

        num_elems++;

    } /* end while */

    for (u = 0; u < depth; u++)

        fprintf(f, "\t");

    fprintf(f, "DIM[%u]: ref_count=%u, #elems=%u, head=%p, tail=%p, actual_tail=%p, matched=%d\n", depth,

            span_lst->count, num_elems, (void *)span_lst->head, (void *)span_lst->tail, (void *)actual_tail,

            (span_lst->tail == actual_tail));

    for (u = 0; u < depth; u++)

        fprintf(f, "\t");

    fprintf(f, "low_bounds=[");

    for (u = 0; u < dims - 1; u++)

        fprintf(f, "%" PRIuHSIZE ",", span_lst->low_bounds[u]);

    fprintf(f, "%" PRIuHSIZE "]\n", span_lst->low_bounds[dims - 1]);

    for (u = 0; u < depth; u++)

        fprintf(f, "\t");

    fprintf(f, "high_bounds=[");

    for (u = 0; u < dims - 1; u++)

        fprintf(f, "%" PRIuHSIZE ",", span_lst->high_bounds[u]);

    fprintf(f, "%" PRIuHSIZE "]\n", span_lst->high_bounds[dims - 1]);

    cur_elem = span_lst->head;

    elem_idx = 0;

    while (cur_elem) {

        for (u = 0; u < depth; u++)

            fprintf(f, "\t");

        fprintf(f, "ELEM[%u]: ptr=%p, low=%" PRIuHSIZE ", high=%" PRIuHSIZE ", down=%p\n", elem_idx++,

                (void *)cur_elem, cur_elem->low, cur_elem->high, (void *)cur_elem->down);

        if (cur_elem->down)

            H5S__hyper_print_spans_dfs(f, cur_elem->down, depth + 1, dims);

        cur_elem = cur_elem->next;

    } /* end while */

    FUNC_LEAVE_NOAPI(SUCCEED)

} /* end H5S__hyper_print_spans_dfs() */

/*--------------------------------------------------------------------------

 NAME

    H5S__hyper_print_space_dfs

 PURPOSE

    Output the span elements for one hyperslab selection space in depth-first order

 USAGE

    herr_t H5S__hyper_print_space_dfs(f, space)

        FILE *f;               IN: the file to output

        const H5S_t *space;    IN: the selection space to output

 RETURNS

    non-negative on success, negative on failure

 GLOBAL VARIABLES

 COMMENTS, BUGS, ASSUMPTIONS

 EXAMPLES

 REVISION LOG

--------------------------------------------------------------------------*/

static herr_t

H5S__hyper_print_space_dfs(FILE *f, const H5S_t *space)

{

    const H5S_hyper_sel_t *hslab = space->select.sel_info.hslab;

    const unsigned         dims  = space->extent.rank;

    unsigned               u;

    FUNC_ENTER_PACKAGE_NOERR

    assert(hslab);

    fprintf(f, "=======================\n");

    fprintf(f, "SPACE: span_lst=%p, #dims=%u, offset_changed=%d\n", (void *)hslab->span_lst, dims,

            space->select.offset_changed);

    fprintf(f, "       offset=[");

    for (u = 0; u < dims - 1; u++)

        fprintf(f, "%lld,", space->select.offset[u]);

    fprintf(f, "%lld]\n", space->select.offset[dims - 1]);

    fprintf(f, "       low_bounds=[");

    if (space->select.sel_info.hslab->diminfo_valid == H5S_DIMINFO_VALID_YES) {

        for (u = 0; u < dims - 1; u++)

            fprintf(f, "%" PRIuHSIZE ",", space->select.sel_info.hslab->diminfo.low_bounds[u]);

        fprintf(f, "%" PRIuHSIZE "]\n", space->select.sel_info.hslab->diminfo.low_bounds[dims - 1]);

    } /* end if */

    else {

        for (u = 0; u < dims - 1; u++)

            fprintf(f, "%" PRIuHSIZE ",", space->select.sel_info.hslab->span_lst->low_bounds[u]);

        fprintf(f, "%" PRIuHSIZE "]\n", space->select.sel_info.hslab->span_lst->low_bounds[dims - 1]);

    } /* end else */

    fprintf(f, "       high_bounds=[");

    if (space->select.sel_info.hslab->diminfo_valid == H5S_DIMINFO_VALID_YES) {

        for (u = 0; u < dims - 1; u++)

            fprintf(f, "%" PRIuHSIZE ",", space->select.sel_info.hslab->diminfo.high_bounds[u]);

        fprintf(f, "%" PRIuHSIZE "]\n", space->select.sel_info.hslab->diminfo.high_bounds[dims - 1]);

    } /* end if */

    else {

        for (u = 0; u < dims - 1; u++)

            fprintf(f, "%" PRIuHSIZE ",", space->select.sel_info.hslab->span_lst->high_bounds[u]);

        fprintf(f, "%" PRIuHSIZE "]\n", space->select.sel_info.hslab->span_lst->high_bounds[dims - 1]);

    } /* end else */

    /* Print out diminfo, if it's valid */

    if (space->select.sel_info.hslab->diminfo_valid == H5S_DIMINFO_VALID_YES)

        H5S__hyper_print_diminfo(f, space);

    /* Start print out the highest-order of dimension */

    if (hslab->span_lst)

        H5S__hyper_print_spans_dfs(f, hslab->span_lst, 0, dims);

    fprintf(f, "=======================\n\n");

    FUNC_LEAVE_NOAPI(SUCCEED)

} /* end H5S__hyper_print_space_dfs() */

#endif /* H5S_HYPER_DEBUG */

/*-------------------------------------------------------------------------

 * Function:    H5S__hyper_get_op_gen

 *

 * Purpose:    Acquire a unique operation generation value

 *

 * Return:    Operation generation value (can't fail)

 *

 * Notes:       Assumes that a 64-bit value will not wrap around during

 *              the lifespan of the process.

 *

 *-------------------------------------------------------------------------

 */

uint64_t

H5S__hyper_get_op_gen(void)

{

    FUNC_ENTER_PACKAGE_NOERR

    FUNC_LEAVE_NOAPI(H5S_hyper_op_gen_g++)

} /* end H5S__hyper_op_gen() */

/*-------------------------------------------------------------------------

 * Function:    H5S__hyper_iter_init

 *

 * Purpose:     Initializes iteration information for hyperslab selection.

 *

 * Return:      Non-negative on success, negative on failure.

 *

 * Notes:       If the 'iter->elmt_size' field is set to zero, the regular

 *              hyperslab selection iterator will not be 'flattened'.  This

 *              is used by the H5S_select_shape_same() code to avoid changing

 *              the rank and appearance of the selection.

 *

 *-------------------------------------------------------------------------

 */

static herr_t

H5S__hyper_iter_init(H5S_t *space, H5S_sel_iter_t *iter)

{

    hsize_t *slab_size;           /* Pointer to the dataspace dimensions to use for calc. slab */

    hsize_t  acc;                 /* Accumulator for computing cumulative sizes */

    unsigned slab_dim;            /* Rank of the fastest changing dimension for calc. slab */

    unsigned rank;                /* Dataspace's dimension rank */

    unsigned u;                   /* Index variable */

    int      i;                   /* Index variable */

    herr_t   ret_value = SUCCEED; /* return value */

    FUNC_ENTER_PACKAGE

    /* Check args */

    assert(space && H5S_SEL_HYPERSLABS == H5S_GET_SELECT_TYPE(space));

    assert(iter);

    assert(space->select.sel_info.hslab->unlim_dim < 0);

    /* Initialize the hyperslab iterator's rank */

    iter->u.hyp.iter_rank = 0;

    /* Get the rank of the dataspace */

    rank = iter->rank;

    /* Attempt to rebuild diminfo if it is invalid and has not been confirmed

     * to be impossible.

     */

    if (space->select.sel_info.hslab->diminfo_valid == H5S_DIMINFO_VALID_NO)

        H5S__hyper_rebuild(space);

    /* Check for the special case of just one H5Sselect_hyperslab call made */

    if (space->select.sel_info.hslab->diminfo_valid == H5S_DIMINFO_VALID_YES) {

        /* Initialize the information needed for regular hyperslab I/O */

        const H5S_hyper_dim_t *tdiminfo;     /* Temporary pointer to diminfo information */

        const hsize_t         *mem_size;     /* Temporary pointer to dataspace extent's dimension sizes */

        unsigned               cont_dim = 0; /* # of contiguous dimensions */

        /* Set the temporary pointer to the dimension information */

        tdiminfo = space->select.sel_info.hslab->diminfo.opt;

        /* Set the temporary pointer to the dataspace extent's dimension sizes */

        mem_size = iter->dims;

        /*

         * For a regular hyperslab to be contiguous up to some dimension, it

         * must have only one block (i.e. count==1 in all dimensions up to that

         * dimension) and the block size must be the same as the dataspace's

         * extent in that dimension and all dimensions up to that dimension.

         */

        /* Don't flatten adjacent elements into contiguous block if the

         * element size is 0.  This is for the H5S_select_shape_same() code.

         */

        if (iter->elmt_size > 0) {

            /* Check for any "contiguous" blocks that can be flattened */

            for (u = (rank - 1); u > 0; u--) {

                if (tdiminfo[u].count == 1 && tdiminfo[u].block == mem_size[u]) {

                    cont_dim++;

                    iter->u.hyp.flattened[u] = true;

                } /* end if */

                else

                    iter->u.hyp.flattened[u] = false;

            } /* end for */

            iter->u.hyp.flattened[0] = false;

        } /* end if */

        /* Check if the regular selection can be "flattened" */

        if (cont_dim > 0) {

            bool     last_dim_flattened = true; /* Flag to indicate that the last dimension was flattened */

            unsigned flat_rank          = rank - cont_dim; /* Number of dimensions after flattening */

            unsigned curr_dim;                             /* Current dimension */

            /* Set the iterator's rank to the contiguous dimensions */

            iter->u.hyp.iter_rank = flat_rank;

            /* "Flatten" dataspace extent and selection information */

            curr_dim = flat_rank - 1;

            for (i = (int)rank - 1, acc = 1; i >= 0; i--) {

                if (tdiminfo[i].block == mem_size[i] && i > 0) {

                    /* "Flatten" this dimension */

                    assert(tdiminfo[i].start == 0);

                    acc *= mem_size[i];

                    /* Indicate that the dimension was flattened */

                    last_dim_flattened = true;

                } /* end if */

                else {

                    if (last_dim_flattened) {

                        /* First dimension after flattened dimensions */

                        iter->u.hyp.diminfo[curr_dim].start = tdiminfo[i].start * acc;

                        /* Special case for single block regular selections */

                        if (tdiminfo[i].count == 1)

                            iter->u.hyp.diminfo[curr_dim].stride = 1;

                        else

                            iter->u.hyp.diminfo[curr_dim].stride = tdiminfo[i].stride * acc;

                        iter->u.hyp.diminfo[curr_dim].count = tdiminfo[i].count;

                        iter->u.hyp.diminfo[curr_dim].block = tdiminfo[i].block * acc;

                        iter->u.hyp.size[curr_dim]          = mem_size[i] * acc;

                        iter->u.hyp.sel_off[curr_dim]       = iter->sel_off[i] * (hssize_t)acc;

                        /* Reset the "last dim flattened" flag to avoid flattened any further dimensions */

                        last_dim_flattened = false;

                        /* Reset the "accumulator" for possible further dimension flattening */

                        acc = 1;

                    } /* end if */

                    else {

                        /* All other dimensions */

                        iter->u.hyp.diminfo[curr_dim].start  = tdiminfo[i].start;

                        iter->u.hyp.diminfo[curr_dim].stride = tdiminfo[i].stride;

                        iter->u.hyp.diminfo[curr_dim].count  = tdiminfo[i].count;

                        iter->u.hyp.diminfo[curr_dim].block  = tdiminfo[i].block;

                        iter->u.hyp.size[curr_dim]           = mem_size[i];

                        iter->u.hyp.sel_off[curr_dim]        = iter->sel_off[i];

                    } /* end else */

                    /* Decrement "current" flattened dimension */

                    curr_dim--;

                } /* end if */

            }     /* end for */

            /* Initialize "flattened" iterator offset to initial location and dataspace extent and selection

             * information to correct values */

            for (u = 0; u < flat_rank; u++)

                iter->u.hyp.off[u] = iter->u.hyp.diminfo[u].start;

            /* Set up information for computing slab sizes */

            slab_dim  = iter->u.hyp.iter_rank - 1;

            slab_size = iter->u.hyp.size;

        } /* end if */

        else {

            /* Make local copy of the regular selection information */

            HDcompile_assert(sizeof(iter->u.hyp.diminfo) ==

                             sizeof(space->select.sel_info.hslab->diminfo.opt));

            H5MM_memcpy(iter->u.hyp.diminfo, tdiminfo, sizeof(iter->u.hyp.diminfo));

            /* Initialize position to initial location */

            for (u = 0; u < rank; u++)

                iter->u.hyp.off[u] = tdiminfo[u].start;

            /* Set up information for computing slab sizes */

            slab_dim  = iter->rank - 1;

            slab_size = iter->dims;

        } /* end else */

        /* Flag the diminfo information as valid in the iterator */

        iter->u.hyp.diminfo_valid = true;

        /* Initialize irregular region information also (for release) */

        iter->u.hyp.spans = NULL;

    }                                 /* end if */

    else {                            /* Initialize the information needed for non-regular hyperslab I/O */

        H5S_hyper_span_info_t *spans; /* Pointer to hyperslab span info node */

        /* If this iterator is created from an API call, by default we clone the

         *  selection now, as the dataspace could be modified or go out of scope.

         *

         *  However, if the H5S_SEL_ITER_SHARE_WITH_DATASPACE flag is given,

         *  the selection is shared between the selection iterator and the

         *  dataspace.  In this case, the application _must_not_ modify or

         *  close the dataspace that the iterator is operating on, or undefined

         *  behavior will occur.

         */

        if ((iter->flags & H5S_SEL_ITER_API_CALL) && !(iter->flags & H5S_SEL_ITER_SHARE_WITH_DATASPACE)) {

            /* Copy the span tree */

            if (NULL == (iter->u.hyp.spans = H5S__hyper_copy_span(space->select.sel_info.hslab->span_lst,

                                                                  space->extent.rank)))

                HGOTO_ERROR(H5E_DATASPACE, H5E_CANTCOPY, FAIL, "can't copy span tree");

        } /* end if */

        else {

            /* Share the source dataspace's span tree by incrementing the reference count on it */

            assert(space->select.sel_info.hslab->span_lst);

            iter->u.hyp.spans = space->select.sel_info.hslab->span_lst;

            iter->u.hyp.spans->count++;

        } /* end else */

        /* Initialize the starting span_info's and spans */

        spans = iter->u.hyp.spans;

        for (u = 0; u < rank; u++) {

            /* Set the pointers to the initial span in each dimension */

            assert(spans);

            assert(spans->head);

            /* Set the pointer to the first span in the list for this node */

            iter->u.hyp.span[u] = spans->head;

            /* Set the initial offset to low bound of span */

            iter->u.hyp.off[u] = iter->u.hyp.span[u]->low;

            /* Get the pointer to the next level down */

            spans = spans->head->down;

        } /* end for */

        /* Set up information for computing slab sizes */

        slab_dim  = iter->rank - 1;

        slab_size = iter->dims;

        /* Flag the diminfo information as not valid in the iterator */

        iter->u.hyp.diminfo_valid = false;

    } /* end else */

    /* Compute the cumulative size of dataspace dimensions */

    for (i = (int)slab_dim, acc = iter->elmt_size; i >= 0; i--) {

        iter->u.hyp.slab[i] = acc;

        acc *= slab_size[i];

    } /* end for */

    /* Initialize more information for irregular hyperslab selections */

    if (!iter->u.hyp.diminfo_valid) {

        /* Set the offset of the first element iterated on, in each dimension */

        for (u = 0; u < rank; u++)

            /* Compute the sequential element offset */

            iter->u.hyp.loc_off[u] =

                ((hsize_t)((hssize_t)iter->u.hyp.off[u] + iter->sel_off[u])) * iter->u.hyp.slab[u];

    } /* end if */

    /* Initialize type of selection iterator */

    iter->type = H5S_sel_iter_hyper;

done:

    FUNC_LEAVE_NOAPI(ret_value)

} /* end H5S__hyper_iter_init() */

/*-------------------------------------------------------------------------

 * Function:    H5S__hyper_iter_coords

 *

 * Purpose:     Retrieve the current coordinates of iterator for current

 *              selection

 *

 * Return:      Non-negative on success, negative on failure

 *

 *-------------------------------------------------------------------------

 */

static herr_t

H5S__hyper_iter_coords(const H5S_sel_iter_t *iter, hsize_t *coords)

{

    FUNC_ENTER_PACKAGE_NOERR

    /* Check args */

    assert(iter);

    assert(coords);

    /* Copy the offset of the current point */

    /* Check for a single "regular" hyperslab */

    if (iter->u.hyp.diminfo_valid) {

        /* Check if this is a "flattened" regular hyperslab selection */

        if (iter->u.hyp.iter_rank != 0 && iter->u.hyp.iter_rank < iter->rank) {

            int u, v; /* Dimension indices */

            /* Set the starting rank of both the "natural" & "flattened" dimensions */

            u = (int)iter->rank - 1;

            v = (int)iter->u.hyp.iter_rank - 1;

            /* Construct the "natural" dimensions from a set of flattened coordinates */

            while (u >= 0) {

                if (iter->u.hyp.flattened[u]) {

                    int begin = u; /* The rank of the first flattened dimension */

                    /* Walk up through as many flattened dimensions as possible */

                    do {

                        u--;

                    } while (u >= 0 && iter->u.hyp.flattened[u]);

                    /* Compensate for possibly overshooting dim 0 */

                    if (u < 0)

                        u = 0;

                    /* Sanity check */

                    assert(v >= 0);

                    /* Compute the coords for the flattened dimensions */

                    H5VM_array_calc(iter->u.hyp.off[v], (unsigned)((begin - u) + 1), &(iter->dims[u]),

                                    &(coords[u]));

                    /* Continue to faster dimension in both indices */

                    u--;

                    v--;

                } /* end if */

                else {

                    /* Walk up through as many non-flattened dimensions as possible */

                    while (u >= 0 && !iter->u.hyp.flattened[u]) {

                        /* Sanity check */

                        assert(v >= 0);

                        /* Copy the coordinate */

                        coords[u] = iter->u.hyp.off[v];

                        /* Continue to faster dimension in both indices */

                        u--;

                        v--;

                    } /* end while */

                }     /* end else */

            }         /* end while */

            assert(v < 0);

        } /* end if */

        else

            H5MM_memcpy(coords, iter->u.hyp.off, sizeof(hsize_t) * iter->rank);

    } /* end if */

    else

        H5MM_memcpy(coords, iter->u.hyp.off, sizeof(hsize_t) * iter->rank);

    FUNC_LEAVE_NOAPI(SUCCEED)

} /* end H5S__hyper_iter_coords() */

/*-------------------------------------------------------------------------

 * Function:    H5S__hyper_iter_block

 *

 * Purpose:     Retrieve the current block of iterator for current

 *              selection

 *

 * Return:      Non-negative on success, negative on failure

 *

 * Notes:       This routine assumes that the iterator is always located at

 *              the beginning of a block.

 *

 *-------------------------------------------------------------------------

 */

static herr_t

H5S__hyper_iter_block(const H5S_sel_iter_t *iter, hsize_t *start, hsize_t *end)

{

    unsigned u; /* Local index variable */

    FUNC_ENTER_PACKAGE_NOERR

    /* Check args */

    assert(iter);

    assert(start);

    assert(end);

    /* Copy the offset of the current point */

    /* Check for a single "regular" hyperslab */

    if (iter->u.hyp.diminfo_valid) {

        /* Copy the start and compute the end of the block */

        for (u = 0; u < iter->rank; u++) {

            start[u] = iter->u.hyp.off[u];

            end[u]   = (start[u] + iter->u.hyp.diminfo[u].block) - 1;

        }

    } /* end if */

    else {

        /* Copy the start & end of the block */

        for (u = 0; u < iter->rank; u++) {

            start[u] = iter->u.hyp.span[u]->low;

            end[u]   = iter->u.hyp.span[u]->high;

        }

    } /* end else */

    FUNC_LEAVE_NOAPI(SUCCEED)

} /* end H5S__hyper_iter_block() */

/*-------------------------------------------------------------------------

 * Function:    H5S__hyper_iter_nelmts

 *

 * Purpose:     Return number of elements left to process in iterator

 *

 * Return:      Non-negative number of elements on success, zero on failure

 *

 *-------------------------------------------------------------------------

 */

static hsize_t

H5S__hyper_iter_nelmts(const H5S_sel_iter_t *iter)

{

    FUNC_ENTER_PACKAGE_NOERR

    /* Check args */

    assert(iter);

    FUNC_LEAVE_NOAPI(iter->elmt_left)

} /* end H5S__hyper_iter_nelmts() */

/*--------------------------------------------------------------------------

 NAME

    H5S__hyper_iter_has_next_block

 PURPOSE

    Check if there is another block left in the current iterator

 USAGE

    htri_t H5S__hyper_iter_has_next_block(iter)

        const H5S_sel_iter_t *iter;       IN: Pointer to selection iterator

 RETURNS

    Non-negative (true/false) on success/Negative on failure

 DESCRIPTION

    Check if there is another block available in the selection iterator.

 GLOBAL VARIABLES

 COMMENTS, BUGS, ASSUMPTIONS

 EXAMPLES

 REVISION LOG

--------------------------------------------------------------------------*/

static H5_ATTR_PURE htri_t

H5S__hyper_iter_has_next_block(const H5S_sel_iter_t *iter)

{

    unsigned u;                 /* Local index variable */

    htri_t   ret_value = false; /* Return value */

    FUNC_ENTER_PACKAGE_NOERR

    /* Check args */

    assert(iter);

    /* Check for a single "regular" hyperslab */

    if (iter->u.hyp.diminfo_valid) {

        const H5S_hyper_dim_t *tdiminfo; /* Temporary pointer to diminfo information */

        const hsize_t         *toff;     /* Temporary offset in selection */

        /* Check if the offset of the iterator is at the last location in all dimensions */

        tdiminfo = iter->u.hyp.diminfo;

        toff     = iter->u.hyp.off;

        for (u = 0; u < iter->rank; u++) {

            /* If there is only one block, continue */

            if (tdiminfo[u].count == 1)

                continue;

            if (toff[u] != (tdiminfo[u].start + ((tdiminfo[u].count - 1) * tdiminfo[u].stride)))

                HGOTO_DONE(true);

        } /* end for */

    }     /* end if */

    else {

        /* Check for any levels of the tree with more sequences in them */

        for (u = 0; u < iter->rank; u++)

            if (iter->u.hyp.span[u]->next != NULL)

                HGOTO_DONE(true);

    } /* end else */

done:

    FUNC_LEAVE_NOAPI(ret_value)

} /* end H5S__hyper_iter_has_next_block() */

/*-------------------------------------------------------------------------

 * Function:    H5S__hyper_iter_next

 *

 * Purpose:     Moves a hyperslab iterator to the beginning of the next sequence

 *              of elements to read.  Handles walking off the end in all dimensions.

 *

 * Return:      Success:    non-negative

 *              Failure:    negative

 *

 *-------------------------------------------------------------------------

 */

static herr_t

H5S__hyper_iter_next(H5S_sel_iter_t *iter, size_t nelem)

{

    unsigned ndims;    /* Number of dimensions of dataset */

    int      fast_dim; /* Rank of the fastest changing dimension for the dataspace */

    unsigned u;        /* Counters */

    FUNC_ENTER_PACKAGE_NOERR

    /* Check for the special case of just one H5Sselect_hyperslab call made */

    /* (i.e. a regular hyperslab selection */

    if (iter->u.hyp.diminfo_valid) {

        const H5S_hyper_dim_t *tdiminfo; /* Temporary pointer to diminfo information */

        hsize_t                iter_offset[H5S_MAX_RANK];

        hsize_t                iter_count[H5S_MAX_RANK];

        int                    temp_dim; /* Temporary rank holder */

        /* Check if this is a "flattened" regular hyperslab selection */

        if (iter->u.hyp.iter_rank != 0 && iter->u.hyp.iter_rank < iter->rank)

            /* Set the aliases for the dimension rank */

            ndims = iter->u.hyp.iter_rank;

        else

            /* Set the aliases for the dimension rank */

            ndims = iter->rank;