Update documentation

Ensure all functions have comments, etc.

src/backend/distributed/executor/multi_router_executor.c

@@ -869,6 +869,12 @@ ExecuteModifyTasksWithoutResults(List *taskList)
 }
 
 
+/*
+ * ExecuteSequentialTasksWithoutResults basically calls ExecuteModifyTasks in a
+ * loop in order to simulate sequential execution of a list of tasks. Useful in
+ * cases where issuing commands in parallel before waiting for results could
+ * result in deadlocks (such as CREATE INDEX CONCURRENTLY).
+ */
 int64
 ExecuteSequentialTasksWithoutResults(List *taskList)
 {

src/backend/distributed/executor/multi_utility.c

@@ -2090,8 +2090,8 @@ DDLTaskList(Oid relationId, const char *commandString)
 
 
 /*
- * DDLTaskList builds a list of tasks to execute a DDL command on a
- * given list of shards.
+ * IndexTaskList builds a list of tasks to execute a CREATE INDEX command
+ * against a specified distributed table.
  */
 static List *
 IndexTaskList(Oid relationId, IndexStmt *indexStmt)
@@ -2144,8 +2144,8 @@ IndexTaskList(Oid relationId, IndexStmt *indexStmt)
 
 
 /*
- * DDLTaskList builds a list of tasks to execute a DDL command on a
- * given list of shards.
+ * DropIndexTaskList builds a list of tasks to execute a DROP INDEX command
+ * against a specified distributed table.
  */
 static List *
 DropIndexTaskList(Oid relationId, Oid indexId, DropStmt *dropStmt)
@@ -2174,6 +2174,7 @@ DropIndexTaskList(Oid relationId, Oid indexId, DropStmt *dropStmt)
 
 		AppendShardIdToName(&shardIndexName, shardId);
 
+		/* deparse shard-specific DROP INDEX command */
 		appendStringInfo(&ddlString, "DROP INDEX %s %s %s %s",
 						 (dropStmt->concurrent ? "CONCURRENTLY" : ""),
 						 (dropStmt->missing_ok ? "IF EXISTS" : ""),

src/backend/distributed/transaction/worker_transaction.c

@@ -68,6 +68,13 @@ SendCommandToWorkers(TargetWorkerSet targetWorkerSet, char *command)
 }
 
 
+/*
+ * SendBareCommandListToWorkers sends a list of commands to a set of target
+ * workers in serial. Commands are committed immediately: new connections are
+ * always used and no transaction block is used (hence "bare"). The connections
+ * are made as the extension owner to ensure write access to the Citus metadata
+ * tables. Primarly useful for INDEX commands using CONCURRENTLY.
+ */
 void
 SendBareCommandListToWorkers(TargetWorkerSet targetWorkerSet, List *commandList)
 {

src/backend/distributed/utils/citus_ruleutils.c

@@ -590,7 +590,12 @@ pg_get_tablecolumnoptionsdef_string(Oid tableRelationId)
 }
 
 
-char *
+/*
+ * deparse_shard_index_statement uses the provided CREATE INDEX node, dist.
+ * relation, and shard identifier to populate a provided buffer with a string
+ * representation of a shard-extended version of that command.
+ */
+void
 deparse_shard_index_statement(IndexStmt *origStmt, Oid distrelid, int64 shardid,
 							  StringInfo buffer)
 {
@@ -680,8 +685,6 @@ deparse_shard_index_statement(IndexStmt *origStmt, Oid distrelid, int64 shardid,
 																deparseContext, false,
 																false));
 	}
-
-	return buffer->data;
 }
 
 

src/include/distributed/citus_ruleutils.h

@@ -32,15 +32,15 @@ extern char * pg_get_sequencedef_string(Oid sequenceRelid);
 extern Form_pg_sequence pg_get_sequencedef(Oid sequenceRelationId);
 extern char * pg_get_tableschemadef_string(Oid tableRelationId, bool forShardCreation);
 extern char * pg_get_tablecolumnoptionsdef_string(Oid tableRelationId);
-extern char * deparse_shard_index_statement(IndexStmt *origStmt, Oid distrelid, int64
-											shardid, StringInfo buffer);
+extern void deparse_shard_index_statement(IndexStmt *origStmt, Oid distrelid,
+										  int64 shardid, StringInfo buffer);
 extern char * pg_get_indexclusterdef_string(Oid indexRelationId);
 extern List * pg_get_table_grants(Oid relationId);
 
 /* Function declarations for version dependent PostgreSQL ruleutils functions */
 extern void pg_get_query_def(Query *query, StringInfo buffer);
-extern void deparse_shard_query(Query *query, Oid distrelid, int64 shardid, StringInfo
-								buffer);
+extern void deparse_shard_query(Query *query, Oid distrelid, int64 shardid,
+								StringInfo buffer);
 extern char * generate_relation_name(Oid relid, List *namespaces);
 extern char * generate_qualified_relation_name(Oid relid);
 

src/include/distributed/multi_utility.h

@@ -23,7 +23,7 @@ extern bool EnableDDLPropagation;
 typedef struct DDLJob
 {
 	Oid targetRelationId;      /* oid of the target distributed relation */
-	bool preventTransaction;
+	bool preventTransaction;   /* prevent use of worker transactions? */
 	const char *commandString; /* initial (coordinator) DDL command string */
 	List *taskList;            /* worker DDL tasks to execute */
 } DDLJob;