oneCCL: corrections for error_handling and generic_workflow pages (#250)

Author: mshiryaev

source/elements/oneCCL/source/spec/error_handling.rst

@@ -29,9 +29,9 @@ Common exceptions
     ".. _oneccl_exception:
 
     ``ccl::exception``", "Reports general unspecified error"
-    ".. _oneccl_exception_unsupported_device:
+    ".. _oneccl_exception_invalid_argument:
 
-    ``ccl::unsupported_device``", "Reports an error when the operation is not supported on a specific device"
+    ``ccl::invalid_argument``", "Reports an error when arguments to the operation were rejected"
     ".. _oneccl_exception_host_bad_alloc:
 
     ``ccl::host_bad_alloc``", "Reports an error that occurred during memory allocation on the host"
@@ -40,7 +40,7 @@ Common exceptions
     ``ccl::device_bad_alloc``", "Reports an error that occurred during memory allocation on a specific device"
     ".. _oneccl_exception_unimplemented:
 
-    ``ccl::unimplemented``", "Reports an error when an algorithm or a method is not implemented"
-    ".. _oneccl_exception_invalid_argument:
+    ``ccl::unimplemented``", "Reports an error when the requested operation is not implemented"
+    ".. _oneccl_exception_unsupported:
 
-    ``ccl::invalid_argument``", "Reports an error when arguments to the operation were rejected"
+    ``ccl::unsupported``", "Reports an error when the requested operation is not supported"

source/elements/oneCCL/source/spec/generic_workflow.rst

@@ -13,6 +13,8 @@ using an out-of-band communication mechanism and be used to create key-value sto
 
 .. code:: cpp
 
+    using namespace std;
+
     /* for example use MPI as an out-of-band communication mechanism */
 
     int mpi_rank, mpi_size;
@@ -21,29 +23,29 @@ using an out-of-band communication mechanism and be used to create key-value sto
     MPI_Comm_rank(MPI_COMM_WORLD, &mpi_rank);
     MPI_Comm_size(MPI_COMM_WORLD, &mpi_size);
 
-    kvs_interface kvs;
-    kvs::address_type kvs_addr;
+    ccl::shared_ptr_class<ccl::kvs> kvs;
+    ccl::kvs::address_type kvs_addr;
 
     if (mpi_rank == 0) {
         kvs = ccl::create_main_kvs();
         kvs_addr = kvs->get_address();
-        MPI_Bcast((void*)kvs_addr.data(), kvs::address_max_size, MPI_BYTE, 0, MPI_COMM_WORLD);
+        MPI_Bcast((void*)kvs_addr.data(), ccl::kvs::address_max_size, MPI_BYTE, 0, MPI_COMM_WORLD);
     }
     else {
-        MPI_Bcast((void*)kvs_addr.data(), kvs::address_max_size, MPI_BYTE, 0, MPI_COMM_WORLD);
+        MPI_Bcast((void*)kvs_addr.data(), ccl::kvs::address_max_size, MPI_BYTE, 0, MPI_COMM_WORLD);
         kvs = ccl::create_kvs(kvs_addr);
     }
 
 2. Create communicator(s):
 
 .. code:: cpp
 
-    /* for host communications */
+    /* host communications */
     auto comm = ccl::create_communicator(mpi_size, mpi_rank, kvs);
 
 .. code:: cpp
 
-    /* for SYCL devices communications, for example with multiple devices per process */
+    /* SYCL devices communications, for example with multiple devices per process */
 
     /* sycl_context -> cl::sycl::context */
     /* sycl_devices -> vector<cl::sycl::device> */
@@ -53,18 +55,19 @@ using an out-of-band communication mechanism and be used to create key-value sto
     auto ccl_context = ccl::create_context(sycl_context);
 
     /* create ccl::device objects from cl::sycl::device objects */
-    std::vector<device> ccl_devices;
+    vector<ccl::device> ccl_devices;
     for (size_t idx = 0; idx < sycl_devices.size(); idx++) {
         ccl_devices.push_back(ccl::create_device(sycl_devices[idx]));
     }
 
-    std::vector<std::pair<size_t, device>> r2d_map;
+    map<size_t, ccl::device> r2d_map;
     for (auto& dev : ccl_devices) {
-        r2d_map.push_back(<rank>, dev);
+        size_t rank = /* generate a globally unique rank for a specific device */
+        r2d_map[rank] = dev;
     }
 
     /* create ccl::stream objects from cl::sycl::queue objects */
-    std::vector<stream> ccl_streams;
+    vector<ccl::stream> ccl_streams;
     for (size_t idx = 0; idx < sycl_queues.size(); idx++) {
         ccl_streams.push_back(ccl::create_stream(sycl_queues[idx]));
     }
@@ -78,13 +81,13 @@ using an out-of-band communication mechanism and be used to create key-value sto
 
 .. code:: cpp
 
-    /* for host communications */
+    /* host communications */
     allreduce(..., comm).wait();
 
 .. code:: cpp
 
-    /* for SYCL devices communications */
-    std::vector<event> events;
+    /* SYCL devices communications */
+    vector<ccl::event> events;
     for (auto& comm : comms) {
         events.push_back(allreduce(..., comm, ccl_streams[comm.rank()]));
     }

source/elements/oneCCL/source/spec/main_objects.rst

@@ -180,21 +180,21 @@ and be used to create key-value stores on other ranks:
 
 .. code:: cpp
 
-    kvs ccl::create_main_kvs() const;
+    shared_ptr_class<kvs> ccl::create_main_kvs() const;
 
-return ``kvs``
+return ``shared_ptr_class<kvs>``
     the main key-value store object
 
 
 Creating a new key-value store from main kvs address:
 
 .. code:: cpp
 
-    kvs ccl::create_kvs(const kvs::address_type& addr) const;
+    shared_ptr_class<kvs> ccl::create_kvs(const kvs::address_type& addr) const;
 
 addr
     the address of the main kvs
-return ``kvs``
+return ``shared_ptr_class<kvs>``
     key-value store object