From 11f8f1f046f6eb7f4d49213e88ccaa73330db5ae Mon Sep 17 00:00:00 2001
From: Jelte Fennema <github-tech@jeltef.nl>
Date: Thu, 22 Jul 2021 14:52:14 +0200
Subject: [PATCH] Update comments

---
 .../commands/create_distributed_table.c       |  4 ++++
 src/backend/distributed/metadata/distobject.c |  9 +++++++--
 .../distributed/metadata/metadata_sync.c      | 20 ++++++++++++-------
 src/include/distributed/metadata_sync.h       |  1 -
 4 files changed, 24 insertions(+), 10 deletions(-)

diff --git a/src/backend/distributed/commands/create_distributed_table.c b/src/backend/distributed/commands/create_distributed_table.c
index b320bafa7..2ca1bee54 100644
--- a/src/backend/distributed/commands/create_distributed_table.c
+++ b/src/backend/distributed/commands/create_distributed_table.c
@@ -557,6 +557,10 @@ CreateDistributedTable(Oid relationId, Var *distributionColumn, char distributio
 	{
 		if (ClusterHasKnownMetadataWorkers())
 		{
+			/*
+			 * Now that we have created the sequence on the worker we can mark
+			 * it as distributed.
+			 */
 			MarkSequenceListDistributed(dependentSequenceList);
 		}
 	}
diff --git a/src/backend/distributed/metadata/distobject.c b/src/backend/distributed/metadata/distobject.c
index 8ec87cba8..686ab07c6 100644
--- a/src/backend/distributed/metadata/distobject.c
+++ b/src/backend/distributed/metadata/distobject.c
@@ -137,8 +137,13 @@ ObjectExists(const ObjectAddress *address)
 
 
 /*
- * MarkObjectDistributed marks an object as a distributed object by citus. Marking is done
- * by adding appropriate entries to citus.pg_dist_object.
+ * MarkObjectDistributed marks an object as a distributed object by citus.
+ * Marking is done by adding appropriate entries to citus.pg_dist_object.
+ *
+ * This also marks the object as distributed on all of the workers with
+ * metadata (unless localOnly is true). This means that the object should
+ * actually be created on those workers already, otherwise the oid of the
+ * object cannot be looked up.
  */
 void
 MarkObjectDistributed(const ObjectAddress *distAddress, bool localOnly)
diff --git a/src/backend/distributed/metadata/metadata_sync.c b/src/backend/distributed/metadata/metadata_sync.c
index e34684f98..e059aa386 100644
--- a/src/backend/distributed/metadata/metadata_sync.c
+++ b/src/backend/distributed/metadata/metadata_sync.c
@@ -440,6 +440,15 @@ DropMetadataSnapshotOnNode(WorkerNode *workerNode)
  * (iii) Queries that populate pg_dist_partition table referenced by (ii)
  * (iv)  Queries that populate pg_dist_shard table referenced by (iii)
  * (v)   Queries that populate pg_dist_placement table referenced by (iv)
+ * (vi)  Queries that populate pg_dist_object
+ *
+ * The first argument will be filled with a list of objects that are after the
+ * returned commands have been run. These objects should then be marked
+ * distributed afterwards. This function does not mark them as distributed
+ * directly. The reason for that is marking as distributed is also done on the
+ * metadata workers, and thus can only be done safely once all nodes their
+ * metadata is up to date. Since this function is only called when at least one
+ * node is out of sync, doing it in this function would always fail.
  */
 List *
 MetadataCreateCommands(List **newDistributedObjects)
@@ -818,6 +827,10 @@ NodeListInsertCommand(List *workerNodeList)
 }
 
 
+/*
+ * DistributedObjectCreateCommand generates a command that can be executed to
+ * insert the provided object into pg_dist_object on a worker node.
+ */
 char *
 DistributedObjectCreateCommand(const ObjectAddress *address,
 							   int32 *distributionArgumentIndex,
@@ -891,13 +904,6 @@ DistributedObjectCreateCommand(const ObjectAddress *address,
 }
 
 
-char *
-DistributedObjectDeleteCommand(const ObjectAddress *address)
-{
-	return NULL;
-}
-
-
 /*
  * DistributionCreateCommands generates a commands that can be
  * executed to replicate the metadata for a distributed table.
diff --git a/src/include/distributed/metadata_sync.h b/src/include/distributed/metadata_sync.h
index 390b24192..1267d245f 100644
--- a/src/include/distributed/metadata_sync.h
+++ b/src/include/distributed/metadata_sync.h
@@ -36,7 +36,6 @@ extern List * MetadataDropCommands(void);
 extern char * DistributedObjectCreateCommand(const ObjectAddress *address,
 											 int32 *distributionArgumentIndex,
 											 int32 *colocationId);
-extern char * DistributedObjectDeleteCommand(const ObjectAddress *address);
 extern char * DistributionCreateCommand(CitusTableCacheEntry *cacheEntry);
 extern char * DistributionDeleteCommand(const char *schemaName,
 										const char *tableName);