From 8a990c2b641b844d623c645b78fb9deb4a4b9b96 Mon Sep 17 00:00:00 2001
From: Artem Polyakov <artpol84@gmail.com>
Date: Sun, 6 Jan 2019 04:59:46 -0800
Subject: [PATCH] opal/common/ucx: Add comments clarifying data structures

Signed-off-by: Artem Polyakov <artpol84@gmail.com>
---
 opal/mca/common/ucx/common_ucx_wpool.h | 28 ++++++++++++++++++++++++++
 1 file changed, 28 insertions(+)

diff --git a/opal/mca/common/ucx/common_ucx_wpool.h b/opal/mca/common/ucx/common_ucx_wpool.h
index 59362a2380..3739a0773c 100644
--- a/opal/mca/common/ucx/common_ucx_wpool.h
+++ b/opal/mca/common/ucx/common_ucx_wpool.h
@@ -19,6 +19,11 @@
 
 BEGIN_C_DECLS
 
+/* Worker pool is a global object that that is allocated per component or can be
+ * shared between multiple compatible components.
+ * The lifetime of this object is normally equal to the lifetime of a component[s].
+ * It is expected to be initialized in MPI_Init and finalized in MPI_Finalize.
+ */
 typedef struct {
     /* Ref counting & locking*/
     int refcnt;
@@ -41,6 +46,15 @@ typedef struct {
     opal_list_t tls_list;
 } opal_common_ucx_wpool_t;
 
+/* Worker Pool Context (wpctx) is an object that is comprised of a set of UCP
+ * workers that are considered as one logical communication entity.
+ * One UCP worker per "active" thread is used.
+ * Thread is considered "active" if it performs communication operations on this
+ * Wpool context.
+ * A lifetime of this object is dynamic and determined by the application
+ * (the object is created and destroyed with corresponding functions).
+ * Context is bound to a particular Worker Pool object.
+ */
 typedef struct {
     opal_recursive_mutex_t mutex;
     opal_atomic_int32_t refcntr;
@@ -59,6 +73,11 @@ typedef struct {
     size_t comm_size;
 } opal_common_ucx_ctx_t;
 
+/* Worker Pool memory (wpmem) is an object that represents a remotely accessible
+ * distributed memory.
+ * It has dynamic lifetime (created and destroyed by corresponding functions).
+ * It depends on particular Wpool context
+ */
 typedef struct {
     /* reference context to which memory region belongs */
     opal_common_ucx_ctx_t *ctx;
@@ -78,6 +97,11 @@ typedef struct {
     opal_tsd_key_t mem_tls_key;
 } opal_common_ucx_wpmem_t;
 
+/* The structure that wraps UCP worker and holds the state that is required
+ * for its use.
+ * The structure is allocated along with UCP worker on demand and is being held
+ * in the Worker Pool lists (either active or idle)
+ */
 typedef struct opal_common_ucx_winfo {
     opal_recursive_mutex_t mutex;
     volatile int released;
@@ -96,6 +120,10 @@ typedef struct {
 
 typedef void (*opal_common_ucx_user_req_handler_t)(void *request);
 
+/* A fast-path structure that gathers all pointers that are required to
+ * perform RMA operation
+ * wpmem's mem_tls_key holds the pointer to this structure
+ */
 typedef struct {
     void *ext_req;
     opal_common_ucx_user_req_handler_t ext_cb;