[svn-r24193] - add Software marking.

- update some comments in examples.

5 files changed, 92 insertions, 46 deletions

diff --git a/examples/h5ff_client_dset.c b/examples/h5ff_client_dset.c
index 8890fa7..f9e2367 100644
--- a/examples/h5ff_client_dset.c
+++ b/examples/h5ff_client_dset.c
@@ -94,7 +94,9 @@ int main(int argc, char **argv) {
 
     dtid = H5Tcopy(H5T_STD_I32LE);
 
-    /* acquire container version 0 - EXACT */
+    /* acquire container version 0 - EXACT.  
+       This can be asynchronous, but here we need the acquired ID 
+       right after the call to start the transaction so we make synchronous. */
     version = 0;
     rid1 = H5RCacquire(file_id, &version, H5P_DEFAULT, H5_EVENT_QUEUE_NULL);
     assert(0 == version);
@@ -103,22 +105,39 @@ int main(int argc, char **argv) {
     tid1 = H5TRcreate(file_id, rid1, (uint64_t)1);
     assert(tid1);
 
-    /* start transaction 1 with default num_peers (= 0). */
+    /* start transaction 1 with default Leader/Delegate model. Leader
+       which is rank 0 here starts the transaction. It can be
+       asynchronous, but we make it synchronous here so that the
+       Leader can tell its delegates that the transaction is
+       started. */
     if(0 == my_rank) {
         ret = H5TRstart(tid1, H5P_DEFAULT, H5_EVENT_QUEUE_NULL);
         assert(0 == ret);
     }
 
-    /* Tell other procs that transaction 1 is started */
+    /* Tell Delegates that transaction 1 is started */
     trans_num = 1;
     MPI_Ibcast(&trans_num, 1, MPI_UINT64_T, 0, MPI_COMM_WORLD, &mpi_req);
 
-    /* Process 0 can continue writing to transaction 1, 
-       while others wait for the bcast to complete */
+    /* Leader can continue writing to transaction 1, 
+       while others wait for the ibcast to complete */
     if(0 != my_rank)
         MPI_Wait(&mpi_req, MPI_STATUS_IGNORE);
 
-    /* create group hierarchy /G1/G2/G3 */
+    /* 
+       Assume the following object create calls are collective.
+
+       In a real world scenario, the following create calls are
+       independent by default; i.e. only 1 process, typically a leader
+       process, calls them. The user does the local-to-global,
+       global-to-local thing to get the objects accessible to all delegates. 
+
+       This will not fail here because IOD used for now is skeletal,
+       so it does not matter if the calls are collective or
+       independent.
+    */
+
+  /* create group hierarchy /G1/G2/G3 */
     gid1 = H5Gcreate_ff(file_id, "G1", H5P_DEFAULT, H5P_DEFAULT, H5P_DEFAULT, tid1, event_q);
     assert(gid1 > 0);
     gid2 = H5Gcreate_ff(gid1, "G2", H5P_DEFAULT, H5P_DEFAULT, H5P_DEFAULT, tid1, event_q);
@@ -197,9 +216,6 @@ int main(int argc, char **argv) {
         assert(0 == ret);
     }
 
-    /* another barrier so other processes know that container version is acquried */
-    MPI_Barrier(MPI_COMM_WORLD);
-
     /* Local op */
     ret = H5TRclose(tid1);
     assert(0 == ret);
diff --git a/examples/h5ff_client_map.c b/examples/h5ff_client_map.c
index b471e63..459ebed 100644
--- a/examples/h5ff_client_map.c
+++ b/examples/h5ff_client_map.c
@@ -83,11 +83,13 @@ int main(int argc, char **argv) {
     event_q = H5EQcreate(fapl_id);

     assert(event_q);

 

-    /* create the file. This is asynchronous, but the file_id can be used. */

+    /* create the file. */

     file_id = H5Fcreate(file_name, H5F_ACC_TRUNC, H5P_DEFAULT, fapl_id);

     assert(file_id);

 

-    /* acquire container version 0 - EXACT */

+    /* acquire container version 0 - EXACT.  

+       This can be asynchronous, but here we need the acquired ID 

+       right after the call to start the transaction so we make synchronous. */

     version = 0;

     rid1 = H5RCacquire(file_id, &version, H5P_DEFAULT, H5_EVENT_QUEUE_NULL);

     assert(0 == version);

@@ -96,31 +98,49 @@ int main(int argc, char **argv) {
     tid1 = H5TRcreate(file_id, rid1, (uint64_t)1);

     assert(tid1);

 

-    /* start transaction 1 with default num_peers (= 0). */

+    /* start transaction 1 with default Leader/Delegate model. Leader

+       which is rank 0 here starts the transaction. It can be

+       asynchronous, but we make it synchronous here so that the

+       Leader can tell its delegates that the transaction is

+       started. */

     if(0 == my_rank) {

         ret = H5TRstart(tid1, H5P_DEFAULT, H5_EVENT_QUEUE_NULL);

         assert(0 == ret);

     }

 

-    /* Tell other procs that transaction 1 is started */

+    /* Tell Delegates that transaction 1 is started */

     trans_num = 1;

     MPI_Ibcast(&trans_num, 1, MPI_UINT64_T, 0, MPI_COMM_WORLD, &mpi_req);

 

-    /* Process 0 can continue writing to transaction 1, 

-       while others wait for the bcast to complete */

+    /* Leader can continue writing to transaction 1, 

+       while others wait for the ibcast to complete */

     if(0 != my_rank)

         MPI_Wait(&mpi_req, MPI_STATUS_IGNORE);

 

+    /* 

+       Assume the following object create calls are collective.

+

+       In a real world scenario, the following create calls are

+       independent by default; i.e. only 1 process, typically a leader

+       process, calls them. The user does the local-to-global,

+       global-to-local thing to get the objects accessible to all delegates. 

+

+       This will not fail here because IOD used for now is skeletal,

+       so it does not matter if the calls are collective or

+       independent.

+    */

+

     /* create two groups */

     gid1 = H5Gcreate_ff(file_id, "G1", H5P_DEFAULT, H5P_DEFAULT, H5P_DEFAULT, tid1, event_q);

     gid2 = H5Gcreate_ff(gid1, "G2", H5P_DEFAULT, H5P_DEFAULT, H5P_DEFAULT, tid1, event_q);

 

-    /* Create Map objects with the key type being 32 bit LE integer */

-    /* Val type, 32 bit LE integer */

+    /* Create 3 Map objects with the key type being 32 bit LE integer */

+

+    /* First Map object with a Value type a 32 bit LE integer */

     map1 = H5Mcreate_ff(file_id, "MAP_1", H5T_STD_I32LE, H5T_STD_I32LE, 

                         H5P_DEFAULT,H5P_DEFAULT,H5P_DEFAULT, tid1, event_q);

 

-    /* Val type: VL datatype */

+    /* Second Map object with a Value type being an HDF5 VL datatype */

     {

         int increment, j, n;

 

@@ -143,7 +163,7 @@ int main(int argc, char **argv) {
                             H5P_DEFAULT,H5P_DEFAULT,H5P_DEFAULT, tid1, event_q);

     }

 

-    /* Val type: VL string */

+    /* Third Map object with a Value type being an HDF5 VL string */

     {

         hid_t dtid;

 

@@ -152,10 +172,11 @@ int main(int argc, char **argv) {
         H5Tset_size(dtid2,H5T_VARIABLE);

 

         /* Val type, VL string */

-        map3 = H5Mcreate_ff(gid2, "MAP_3", H5T_STD_I32LE, dtid1, 

+        map3 = H5Mcreate_ff(gid2, "MAP_3", H5T_STD_I32LE, dtid2, 

                             H5P_DEFAULT,H5P_DEFAULT,H5P_DEFAULT, tid1, event_q);

     }

 

+    /* write some KV pairs to each map object. */

     {

         key = 1;

         value = 1000;

@@ -192,6 +213,8 @@ int main(int argc, char **argv) {
        0 can finish transaction 1 and acquire a read context on it. */

     MPI_Barrier(MPI_COMM_WORLD);

 

+    /* Leader process finishes/commits the transaction and acquires a

+       read context on it */

     if(0 == my_rank) {

         MPI_Wait(&mpi_req, MPI_STATUS_IGNORE);

 

@@ -202,7 +225,7 @@ int main(int argc, char **argv) {
     /* another barrier so other processes know that container version is acquried */

     MPI_Barrier(MPI_COMM_WORLD);

 

-    /* Close transaction object. Local op */

+    /* Close the first transaction object. Local op */

     ret = H5TRclose(tid1);

     assert(0 == ret);

 

@@ -217,17 +240,19 @@ int main(int argc, char **argv) {
     fprintf(stderr, "\n");

     free(status);

 

-    /* Process 0 tells other procs that container version 1 is acquired */

+    /* Leader process tells delegates that container version 1 is acquired */

     version = 1;

     MPI_Bcast(&version, 1, MPI_UINT64_T, 0, MPI_COMM_WORLD);

 

-    /* other processes just create a read context object; no need to

-       acquire it */

+    /* delegates just create a read context object; no need to acquire

+       it, since it has been acquired by the leader. */

     if(0 != my_rank) {

         rid2 = H5RCcreate(file_id, version);

         assert(rid2 > 0);

     }

 

+    /* issue some read operations using the read context acquired */

+

     ret = H5Mget_count_ff(map3, &count, rid2, event_q);

     assert(ret == 0);

 

@@ -235,7 +260,7 @@ int main(int argc, char **argv) {
     ret = H5Mexists_ff(map3, H5T_STD_I32LE, &key, &exists, rid2, event_q);

     assert(ret == 0);

 

-    /* create & start transaction 2 with num_peers = n */

+    /* create & start transaction 2 with Multiple Leader - No Delegate Model. */

     tid2 = H5TRcreate(file_id, rid2, (uint64_t)2);

     assert(tid2);

     trspl_id = H5Pcreate (H5P_TR_START);

@@ -246,6 +271,7 @@ int main(int argc, char **argv) {
     ret = H5Pclose(trspl_id);

     assert(0 == ret);

 

+    /* modify container contents using transaction started. */

     key = 1;

     ret = H5Mdelete_ff(map3, H5T_STD_I32LE, &key, tid2, event_q);

     assert(ret == 0);

@@ -278,11 +304,13 @@ int main(int argc, char **argv) {
     ret = H5TRclose(tid2);

     assert(0 == ret);

 

-    /* acquire container version 0 - EXACT */

+    /* acquire container version 2 - EXACT */

     version = 2;

     rid3 = H5RCacquire(file_id, &version, H5P_DEFAULT, H5_EVENT_QUEUE_NULL);

     assert(2 == version);

 

+    /* Now read some data from the container */

+

     map1 = H5Mopen_ff(file_id, "MAP_1", H5P_DEFAULT, rid3, event_q);

     map2 = H5Mopen_ff(file_id, "G1/MAP_2", H5P_DEFAULT, rid3, event_q);

     map3 = H5Mopen_ff(file_id, "G1/G2/MAP_3", H5P_DEFAULT, rid3, event_q);

diff --git a/examples/h5ff_client_paths.c b/examples/h5ff_client_paths.c
index 57542a1..fb8ece4 100644
--- a/examples/h5ff_client_paths.c
+++ b/examples/h5ff_client_paths.c
@@ -72,7 +72,7 @@ int main(int argc, char **argv) {
     event_q = H5EQcreate(fapl_id);

     assert(event_q);

 

-    /* create the file. This is asynchronous, but the file_id can be used. */

+    /* create the file. */

     file_id = H5Fcreate(file_name, H5F_ACC_TRUNC, H5P_DEFAULT, fapl_id);

     assert(file_id);

 

diff --git a/examples/h5ff_client_trans.c b/examples/h5ff_client_trans.c
index 7ae0c1c..05e78d3 100644
--- a/examples/h5ff_client_trans.c
+++ b/examples/h5ff_client_trans.c
@@ -66,17 +66,19 @@ int main(int argc, char **argv) {
     /* acquire container version 0 - EXACT */

     rid1 = H5RCacquire(file_id, &version, H5P_DEFAULT, H5_EVENT_QUEUE_NULL);

 

-    /* create 2 transactions objects (does not start transactions). Local call. */

-    tid1 = H5TRcreate(file_id, rid1, (uint64_t)1);

-    assert(tid1);

+    /* create transactions object (does not start transactions). Local call. */

     tid2 = H5TRcreate(file_id, rid1, (uint64_t)555);

     assert(tid2);

 

-    /* start transaction 1 with default num_peers (= 0). 

-       This is asynchronous. */

     if(my_rank == 0) {

         hid_t gid1, gid2;

 

+        /* create transactions object (does not start transactions). Local call. */

+        tid1 = H5TRcreate(file_id, rid1, (uint64_t)1);

+        assert(tid1);

+

+        /* start transaction 1 with default Leader/Delegate model. Leader

+           which is rank 0 here starts the transaction. */

         ret = H5TRstart(tid1, H5P_DEFAULT, event_q);

         assert(0 == ret);

 

@@ -87,13 +89,22 @@ int main(int argc, char **argv) {
 

         assert(H5Gclose_ff(gid1, event_q) == 0);

         assert(H5Gclose_ff(gid2, event_q) == 0);

+

+        /* finish transaction 1. 

+           This is asynchronous, but has a dependency on H5TRstart() of tid1. */

+        ret = H5TRfinish(tid1, H5P_DEFAULT, NULL, event_q);

+        assert(0 == ret);

+

+        /* Local op */

+        ret = H5TRclose(tid1);

+        assert(0 == ret);

     }

 

     /* skip transactions 2 till 554. This is asynchronous. */

     ret = H5TRskip(file_id, (uint64_t)2, (uint64_t)553, event_q);

     assert(0 == ret);

 

-    /* start transaction 555 with num_peers = n */

+    /* Start transaction 555 with Multiple Leader - No Delegate Model. */

     trspl_id = H5Pcreate (H5P_TR_START);

     ret = H5Pset_trspl_num_peers(trspl_id, my_size);

     assert(0 == ret);

@@ -102,22 +113,11 @@ int main(int argc, char **argv) {
     ret = H5Pclose(trspl_id);

     assert(0 == ret);

 

-    /* set dependency from transaction 555 on 2. 

+    /* set dependency from transaction 555 on 1. 

        This is asynchronous but has a dependency on H5TRstart() of tid2. */

     ret = H5TRset_dependency(tid2, (uint64_t)1, event_q);

     assert(0 == ret);

 

-    /* finish transaction 1. 

-       This is asynchronous, but has a dependency on H5TRstart() of tid1. */

-    if(my_rank == 0) {

-        ret = H5TRfinish(tid1, H5P_DEFAULT, NULL, event_q);

-        assert(0 == ret);

-    }

-

-    /* Local op */

-    ret = H5TRclose(tid1);

-    assert(0 == ret);

-

     /* finish transaction 555 and acquire a read context for it */

     ret = H5TRfinish(tid2, H5P_DEFAULT, &rid2, event_q);

     assert(0 == ret);

diff --git a/examples/run_ff_tests.sh.in b/examples/run_ff_tests.sh.in
index d7b414e..05f2377 100755
--- a/examples/run_ff_tests.sh.in
+++ b/examples/run_ff_tests.sh.in
@@ -1,6 +1,8 @@
 #!/bin/bash
 
-mkdir ff_output
+if [ ! -d "ff_output" ]; then
+    mkdir ff_output
+fi
 
 echo "Starting attribute (H5A) test-----------------------------------------"
 mpiexec -np 1 ./h5ff_server &> ff_output/server_attr &