From cba340ebe9a419e6d112bf84b584fd5350b425a6 Mon Sep 17 00:00:00 2001
From: Andres Freund <andres@anarazel.de>
Date: Fri, 7 Oct 2016 19:20:35 -0700
Subject: [PATCH] Add overview instructions to transaction_management.c's
 header.

---
 .../transaction/transaction_management.c      | 37 +++++++++++++++++++
 1 file changed, 37 insertions(+)

diff --git a/src/backend/distributed/transaction/transaction_management.c b/src/backend/distributed/transaction/transaction_management.c
index 36d030fa3..9dfd29ec8 100644
--- a/src/backend/distributed/transaction/transaction_management.c
+++ b/src/backend/distributed/transaction/transaction_management.c
@@ -6,6 +6,43 @@
  *   subsystems, this files, and especially CoordinatedTransactionCallback,
  *   coordinates the work between them.
  *
+ *
+ *   The standard pattern to perform work spanning this and remote nodes, is to:
+ *
+ *   1) Call BeginOrContinueCoordinatedTransaction(). This signals that work
+ *      on remote nodes should be done inside explicit transactions. If that's
+ *      not desired, e.g. inside router executor, this step should be skipped.
+ *
+ *   2) Acquire a connection to either the remote node (using
+ *      GetNodeConnection() or similar) or one associated with a placement
+ *      (using GetPlacementConnection() or similar). Always use the latter
+ *      when performing work associated with a placement.  Use the
+ *      FOR_DML/FOR_DDL flags if appropriate.
+ *
+ *   3) Call AdjustRemoteTransactionState() or AdjustRemoteTransactionStates()
+ *      on all connections used. The latter should be used if multiple
+ *      connections are in use, since it is considerably faster.
+ *
+ *   4) Perform work on the connection, either using MultiConnection->conn
+ *      directly via libpq, or using some of the remote_command.h helpers.
+ *
+ *   5) Done.  If the local transaction commits/aborts, the remote
+ *      transaction(s) are going to be committed/aborted as well.  If a
+ *      placement has been modified (DML or DDL flag to
+ *      GetPlacementConnnection()) and the remote transaction failed,
+ *      placements will be marked as invalid, or the entire transaction will
+ *      be aborted, as appropriate.
+ *
+ *
+ *   This subsystem delegates work to several subsystems:
+ *   - connection lifecycle management is handled in connection_management.[ch]
+ *   - transaction on remote nodes are managed via remote_transaction.[ch]
+ *   - per-placement visibility, locking and invalidation resides in
+ *     placement_connection.[ch]
+ *   - simple and complex commands on other nodes can be executed via
+ *     remote_commands.[ch]
+ *
+ *
  * Copyright (c) 2016, Citus Data, Inc.
  *
  *-------------------------------------------------------------------------