Improve the description of Output Plugin Callbacks.

We were inconsistently specifying the required and optional marking for
plugin callbacks. Additionally, this patch improves the description for
stream_prepare callback.

Author: Wang wei
Reviewed-by: Amit Kapila
Discussion: https://postgr.es/m/OS3PR01MB627553DAFD39ECDADD08DC909EFC9@OS3PR01MB6275.jpnprd01.prod.outlook.com

diff --git a/doc/src/sgml/logicaldecoding.sgml b/doc/src/sgml/logicaldecoding.sgml
index 4cf863a76f3ae59978b3b24d0b820ab65a19bafe..4e912b4bd4815189305264e6df5a85e8365d776f 100644 (file)
--- a/doc/src/sgml/logicaldecoding.sgml
+++ b/doc/src/sgml/logicaldecoding.sgml
@@ -479,8 +479,8 @@ typedef void (*LogicalOutputPluginInit) (struct OutputPluginCallbacks *cb);
 
      The begin_cb, change_cb
      and commit_cb callbacks are required,
-     while startup_cb,
-     filter_by_origin_cb, truncate_cb,
+     while startup_cb, truncate_cb,
+     message_cb, filter_by_origin_cb,
      and shutdown_cb are optional.
      If truncate_cb is not set but a
      TRUNCATE is to be decoded, the action will be ignored.
@@ -490,19 +490,21 @@ typedef void (*LogicalOutputPluginInit) (struct OutputPluginCallbacks *cb);
      An output plugin may also define functions to support streaming of large,
      in-progress transactions. The stream_start_cb,
      stream_stop_cb, stream_abort_cb,
-     stream_commit_cb, stream_change_cb,
-     and stream_prepare_cb
+     stream_commit_cb, and stream_change_cb
      are required, while stream_message_cb and
-     stream_truncate_cb are optional.
+     stream_truncate_cb are optional. The
+     stream_prepare_cb is also required if the output
+     plugin also support two-phase commits.
     
 
     
     An output plugin may also define functions to support two-phase commits,
     which allows actions to be decoded on the PREPARE TRANSACTION.
     The begin_prepare_cb, prepare_cb,
-    stream_prepare_cb,
     commit_prepared_cb and rollback_prepared_cb
     callbacks are required, while filter_prepare_cb is optional.
+    The stream_prepare_cb is also required if the output plugin
+    also supports the streaming of large in-progress transactions.
     
    
 
@@ -721,7 +723,7 @@ typedef void (*LogicalDecodeChangeCB) (struct LogicalDecodingContext *ctx,
      Truncate Callback
 
      
-      The truncate_cb callback is called for a
+      The optional truncate_cb callback is called for a
       TRUNCATE command.
 
 typedef void (*LogicalDecodeTruncateCB) (struct LogicalDecodingContext *ctx,
@@ -919,8 +921,8 @@ typedef void (*LogicalDecodeRollbackPreparedCB) (struct LogicalDecodingContext *
     
      Stream Start Callback
      
-      The stream_start_cb callback is called when opening
-      a block of streamed changes from an in-progress transaction.
+      The required stream_start_cb callback is called when
+      opening a block of streamed changes from an in-progress transaction.
 
 typedef void (*LogicalDecodeStreamStartCB) (struct LogicalDecodingContext *ctx,
                                             ReorderBufferTXN *txn);
@@ -931,8 +933,8 @@ typedef void (*LogicalDecodeStreamStartCB) (struct LogicalDecodingContext *ctx,
     
      Stream Stop Callback
      
-      The stream_stop_cb callback is called when closing
-      a block of streamed changes from an in-progress transaction.
+      The required stream_stop_cb callback is called when
+      closing a block of streamed changes from an in-progress transaction.
 
 typedef void (*LogicalDecodeStreamStopCB) (struct LogicalDecodingContext *ctx,
                                            ReorderBufferTXN *txn);
@@ -943,8 +945,8 @@ typedef void (*LogicalDecodeStreamStopCB) (struct LogicalDecodingContext *ctx,
     
      Stream Abort Callback
      
-      The stream_abort_cb callback is called to abort
-      a previously streamed transaction.
+      The required stream_abort_cb callback is called to
+      abort a previously streamed transaction.
 
 typedef void (*LogicalDecodeStreamAbortCB) (struct LogicalDecodingContext *ctx,
                                             ReorderBufferTXN *txn,
@@ -957,8 +959,10 @@ typedef void (*LogicalDecodeStreamAbortCB) (struct LogicalDecodingContext *ctx,
      Stream Prepare Callback
      
       The stream_prepare_cb callback is called to prepare
-      a previously streamed transaction as part of a two-phase commit.
-
+      a previously streamed transaction as part of a two-phase commit. This
+      callback is required when the output plugin supports both the streaming
+      of large in-progress transactions and two-phase commits.
+      
 typedef void (*LogicalDecodeStreamPrepareCB) (struct LogicalDecodingContext *ctx,
                                               ReorderBufferTXN *txn,
                                               XLogRecPtr prepare_lsn);
@@ -969,8 +973,8 @@ typedef void (*LogicalDecodeStreamPrepareCB) (struct LogicalDecodingContext *ctx
     
      Stream Commit Callback
      
-      The stream_commit_cb callback is called to commit
-      a previously streamed transaction.
+      The required stream_commit_cb callback is called to
+      commit a previously streamed transaction.
 
 typedef void (*LogicalDecodeStreamCommitCB) (struct LogicalDecodingContext *ctx,
                                              ReorderBufferTXN *txn,
@@ -982,8 +986,8 @@ typedef void (*LogicalDecodeStreamCommitCB) (struct LogicalDecodingContext *ctx,
     
      Stream Change Callback
      
-      The stream_change_cb callback is called when sending
-      a change in a block of streamed changes (demarcated by
+      The required stream_change_cb callback is called
+      when sending a change in a block of streamed changes (demarcated by
       stream_start_cb and stream_stop_cb calls).
       The actual changes are not displayed as the transaction can abort at a later
       point in time and we don't decode changes for aborted transactions.
@@ -999,8 +1003,8 @@ typedef void (*LogicalDecodeStreamChangeCB) (struct LogicalDecodingContext *ctx,
     
      Stream Message Callback
      
-      The stream_message_cb callback is called when sending
-      a generic message in a block of streamed changes (demarcated by
+      The optional stream_message_cb callback is called when
+      sending a generic message in a block of streamed changes (demarcated by
       stream_start_cb and stream_stop_cb calls).
       The message contents for transactional messages are not displayed as the transaction
       can abort at a later point in time and we don't decode changes for aborted
@@ -1020,8 +1024,8 @@ typedef void (*LogicalDecodeStreamMessageCB) (struct LogicalDecodingContext *ctx
     
      Stream Truncate Callback
      
-      The stream_truncate_cb callback is called for a
-      TRUNCATE command in a block of streamed changes
+      The optional stream_truncate_cb callback is called
+      for a TRUNCATE command in a block of streamed changes
       (demarcated by stream_start_cb and
       stream_stop_cb calls).