Update the docs and comments for decoding of prepared xacts.

Commit a271a1b introduced decoding at prepare time in ReorderBuffer.
This can lead to deadlock for out-of-core logical replication solutions
that uses this feature to build distributed 2PC in case such transactions
lock [user] catalog tables exclusively. They need to inform users to not
have locks on catalog tables (via explicit LOCK command) in such
transactions.

Reported-by: Andres Freund
Discussion: https://postgr.es/m/20210222222847.tpnb6eg3yiykzpky@alap3.anarazel.de

Author: Amit Kapila

doc/src/sgml/logicaldecoding.sgml

@@ -1228,5 +1228,29 @@ stream_commit_cb(...);  <-- commit of the streamed transaction
     that name pattern will not be decoded as a two-phase commit transaction.
    </para>
 
+   <para>
+    The users that want to decode prepared transactions need to be careful about
+    below mentioned points:
+
+    <itemizedlist>
+     <listitem>
+      <para>
+       If the prepared transaction has locked [user] catalog tables exclusively
+       then decoding prepare can block till the main transaction is committed.
+      </para>
+     </listitem>
+
+     <listitem>
+      <para>
+       The logical replication solution that builds distributed two phase commit
+       using this feature can deadlock if the prepared transaction has locked
+       [user] catalog tables exclusively. They need to inform users to not have
+       locks on catalog tables (via explicit <command>LOCK</command> command) in
+       such transactions.
+      </para>
+     </listitem>
+    </itemizedlist>
+   </para>
+
   </sect1>
  </chapter>

src/backend/replication/logical/decode.c

@@ -362,6 +362,20 @@ DecodeXactOp(LogicalDecodingContext *ctx, XLogRecordBuffer *buf)
 					break;
 				}
 
+				/*
+				 * Note that if the prepared transaction has locked [user]
+				 * catalog tables exclusively then decoding prepare can block
+				 * till the main transaction is committed because it needs to
+				 * lock the catalog tables.
+				 *
+				 * XXX Now, this can even lead to a deadlock if the prepare
+				 * transaction is waiting to get it logically replicated for
+				 * distributed 2PC. Currently, we don't have an in-core
+				 * implementation of prepares for distributed 2PC but some
+				 * out-of-core logical replication solution can have such an
+				 * implementation. They need to inform users to not have locks
+				 * on catalog tables in such transactions.
+				 */
 				DecodePrepare(ctx, buf, &parsed);
 				break;
 			}