Add H5S_SEL_ITER_SHARE_WITH_DATASPACE selection iterator creation flag, to

share dataspace's selection with iterator (and with caution about not modifying
or closing the dataspace while the iterator is open).

4 files changed, 35 insertions, 7 deletions

diff --git a/src/H5Shyper.c b/src/H5Shyper.c
index 49d7cb3..6df368d 100644
--- a/src/H5Shyper.c
+++ b/src/H5Shyper.c
@@ -726,10 +726,17 @@ H5S__hyper_iter_init(const H5S_t *space, H5S_sel_iter_t *iter)
     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, we must clone the
+        /* 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) {
+        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")
diff --git a/src/H5Spoint.c b/src/H5Spoint.c
index 7fa232d..875c018 100644
--- a/src/H5Spoint.c
+++ b/src/H5Spoint.c
@@ -188,10 +188,17 @@ H5S__point_iter_init(const H5S_t *space, H5S_sel_iter_t *iter)
     HDassert(space && H5S_SEL_POINTS == H5S_GET_SELECT_TYPE(space));
     HDassert(iter);
 
-    /* If this iterator is created from an API call, we must clone the
+    /* 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) {
+    if((iter->flags & H5S_SEL_ITER_API_CALL) && 
+            !(iter->flags & H5S_SEL_ITER_SHARE_WITH_DATASPACE)) {
         /* Copy the point list */
         if(NULL == (iter->u.pnt.pnt_lst = H5S__copy_pnt_list(space->select.sel_info.pnt_lst, space->extent.rank)))
             HGOTO_ERROR(H5E_DATASPACE, H5E_CANTCOPY, FAIL, "can't copy point list")
@@ -556,8 +563,9 @@ H5S__point_iter_release(H5S_sel_iter_t * iter)
     /* Check args */
     HDassert(iter);
 
-    /* If this iterator is created from an API call, we must free the point list */
-    if(iter->flags & H5S_SEL_ITER_API_CALL)
+    /* If this iterator copied the point list, we must free it */
+    if((iter->flags & H5S_SEL_ITER_API_CALL) && 
+            !(iter->flags & H5S_SEL_ITER_SHARE_WITH_DATASPACE))
         H5S__free_pnt_list(iter->u.pnt.pnt_lst);
 
     FUNC_LEAVE_NOAPI(SUCCEED)
diff --git a/src/H5Spublic.h b/src/H5Spublic.h
index 3763ec3..23e6846 100644
--- a/src/H5Spublic.h
+++ b/src/H5Spublic.h
@@ -44,6 +44,18 @@
                                                  * earlier offset than the previous
                                                  * one.
                                                  */
+#define H5S_SEL_ITER_SHARE_WITH_DATASPACE 0x0002 /* Don't copy the dataspace
+                                                 * selection when creating the
+                                                 * selection iterator.
+                                                 * 
+                                                 * This can improve performance
+                                                 * of creating the iterator, but
+                                                 * the dataspace _MUST_NOT_ be
+                                                 * modified or closed until the
+                                                 * selection iterator is closed
+                                                 * or the iterator's behavior
+                                                 * will be undefined.
+                                                 */
 
 /* Different types of dataspaces */
 typedef enum H5S_class_t {
diff --git a/src/H5Sselect.c b/src/H5Sselect.c
index 4d0038c..c40ff69 100644
--- a/src/H5Sselect.c
+++ b/src/H5Sselect.c
@@ -41,7 +41,8 @@
 /****************/
 
 /* All the valid public flags to H5Ssel_iter_create() */
-#define H5S_SEL_ITER_ALL_PUBLIC_FLAGS (H5S_SEL_ITER_GET_SEQ_LIST_SORTED)
+#define H5S_SEL_ITER_ALL_PUBLIC_FLAGS (H5S_SEL_ITER_GET_SEQ_LIST_SORTED | \
+                H5S_SEL_ITER_SHARE_WITH_DATASPACE)
 
 
 /******************/