Add documentation for gpuarray/collectives.h and implementation

tsirif · tsirif · commit 89683273cba6 · 2016-06-23T02:49:20.000+03:00
diff --git a/src/gpuarray/collectives.h b/src/gpuarray/collectives.h
@@ -17,65 +17,91 @@ extern "C" {
 ************************************************************************************/
 
 /**
- * \brief TODO
- * \param src [const GpuArray*] TODO
- * \param opcode [int] TODO
- * \param root [int] TODO
- * \param comm [gpucomm*] TODO
- * \return int TODO
+ * \brief Reduce collective operation for non root participant ranks in a
+ * communicator world.
+ * \param src [const GpuArray*] array to be reduced
+ * \param opcode [int] reduce operation code, see \ref enum _gpucomm_reduce_ops
+ * \param root [int] rank in \ref comm which will collect result
+ * \param comm [gpucomm*] gpu communicator world
+ * \note Root rank of reduce operation must call \ref GpuArray_reduce.
+ * \note Must be called separately for each rank in `comm`, except root rank.
+ * \return int error code, GA_NO_ERROR if success
  */
 GPUARRAY_PUBLIC int GpuArray_reduce_from(const GpuArray* src, int opcode, int root,
                                          gpucomm* comm);
 
 /**
- * \brief TODO
- * \param src [const GpuArray*] TODO
- * \param dest [GpuArray*] TODO
- * \param opcode [int] TODO
- * \param root [int] TODO
- * \param comm [gpucomm*] TODO
- * \return int TODO
+ * \brief Reduce collective operation for ranks in a communicator world.
+ * \param src [const GpuArray*] array to be reduced
+ * \param dest [GpuArray*] array to collect reduce operation result
+ * \param opcode [int] reduce operation code, see \ref enum _gpucomm_reduce_ops
+ * \param root [int] rank in `comm` which will collect result
+ * \param comm [gpucomm*] gpu communicator world
+ * \note Can be used by root and non root ranks alike.
+ * \note Non root ranks can call this, using a NULL `dest`.
+ * \note Must be called separately for each rank in `comm` (non root can call \ref
+ * GpuArray_reduce_from instead).
+ * \return int error code, GA_NO_ERROR if success
  */
 GPUARRAY_PUBLIC int GpuArray_reduce(const GpuArray* src, GpuArray* dest, int opcode,
                                     int root, gpucomm* comm);
 
 /**
- * \brief TODO
- * \param src [const GpuArray*] TODO
- * \param dest [GpuArray*] TODO
- * \param opcode [int] TODO
- * \param comm [gpucomm*] TODO
- * \return int TODO
+ * \brief AllReduce collective operation for ranks in a communicator world.
+ *
+ * Reduces `src` using op operation and leaves identical copies of result in `dest`
+ * on each rank of `comm`.
+ *
+ * \param src [const GpuArray*] array to be reduced
+ * \param dest [GpuArray*] array to collect reduce operation result
+ * \param opcode [int] reduce operation code, see \ref enum _gpucomm_reduce_ops
+ * \param comm [gpucomm*] gpu communicator world
+ * \note Must be called separately for each rank in `comm`.
+ * \return int error code, GA_NO_ERROR if success
  */
 GPUARRAY_PUBLIC int GpuArray_all_reduce(const GpuArray* src, GpuArray* dest,
                                         int opcode, gpucomm* comm);
 
 /**
- * \brief TODO
- * \param src [const GpuArray*] TODO
- * \param dest [GpuArray*] TODO
- * \param opcode [int] TODO
- * \param comm [gpucomm*] TODO
- * \return int TODO
+ * \brief ReduceScatter collective operation for ranks in a communicator world.
+ *
+ * Reduces data in `src` using `opcode` operation and leaves reduced result scattered
+ * over `dest` in the user-defined rank order in `comm`.
+ *
+ * \param src [const GpuArray*] array to be reduced
+ * \param dest [GpuArray*] array to collect reduce operation scattered result
+ * \param opcode [int] reduce operation code, see \ref enum _gpucomm_reduce_ops
+ * \param comm [gpucomm*] gpu communicator world
+ * \note Must be called separately for each rank in `comm`.
+ * \return int error code, GA_NO_ERROR if success
  */
 GPUARRAY_PUBLIC int GpuArray_reduce_scatter(const GpuArray* src, GpuArray* dest,
                                             int opcode, gpucomm* comm);
 
 /**
- * \brief TODO
- * \param array [GpuArray*] TODO
- * \param root [int] TODO
- * \param comm [gpucomm*] TODO
- * \return int TODO
+ * \brief Broadcast collective operation for ranks in a communicator world.
+ *
+ * Copies `array` to all ranks in `comm`.
+ *
+ * \param array [GpuArray*] array to be broadcasted, if root rank, else to receive
+ * \param root [int] rank in `comm` which broadcasts its array
+ * \param comm [gpucomm*] gpu communicator world
+ * \note Must be called separately for each rank in `comm`.
+ * \return int error code, GA_NO_ERROR if success
  */
 GPUARRAY_PUBLIC int GpuArray_broadcast(GpuArray* array, int root, gpucomm* comm);
 
 /**
- * \brief TODO
- * \param src [const GpuArray*] TODO
- * \param dest [GpuArray*] TODO
- * \param comm [gpucomm*] TODO
- * \return int TODO
+ * \brief AllGather collective operation for ranks in a communicator world.
+ *
+ * Each rank receives all `src` arrays from every rank in the user-defined rank order
+ * in `comm`.
+ *
+ * \param src [const GpuArray*] array to be gathered
+ * \param dest [GpuArray*] array to receive all gathered arrays from ranks in `comm`
+ * \param comm [gpucomm*] gpu communicator world
+ * \note Must be called separately for each rank in `comm`.
+ * \return int error code, GA_NO_ERROR if success
  */
 GPUARRAY_PUBLIC int GpuArray_all_gather(const GpuArray* src, GpuArray* dest,
                                         gpucomm* comm);
diff --git a/src/gpuarray_array_collectives.c b/src/gpuarray_array_collectives.c
@@ -5,6 +5,9 @@
 
 #include "private.h"
 
+/**
+ * \brief Finds total number of elements contained in `array`.
+ */
 static inline int find_total_elems(const GpuArray* array)
 {
   unsigned int i;
@@ -13,6 +16,15 @@ static inline int find_total_elems(const GpuArray* array)
   return (int)total_elems;
 }
 
+/**
+ * \brief Checks if `src` and `dest` arrays are appropriate to participate in a
+ * collective operation.
+ *
+ * Checks to see if they contain the appropriate number of elements, if they are
+ * properly aligned (contiguous) and writeable (for `dest`) and if they contain
+ * elements of the same datatype. It returns the number of elements of the array with
+ * the less length.
+ */
 static inline int check_gpuarrays(int times_src, const GpuArray* src, int times_dest,
                                   const GpuArray* dest, int* count)
 {
