v1-0001-Add-another-way-to-build-TupleDesc-in-documentati.patch

From 3ee0c4a402bcf2d25a7c544ddd60d3e9742b9048 Mon Sep 17 00:00:00 2001
From: Bharath Rupireddy <bharath.rupireddyforpostgres@gmail.com>
Date: Wed, 21 Dec 2022 06:38:27 +0000
Subject: [PATCH v1] Add another way to build TupleDesc in documentation

---
 doc/src/sgml/xfunc.sgml | 44 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 44 insertions(+)

diff --git a/doc/src/sgml/xfunc.sgml b/doc/src/sgml/xfunc.sgml
index cf5810b3c1..8b9c718fdf 100644
--- a/doc/src/sgml/xfunc.sgml
+++ b/doc/src/sgml/xfunc.sgml
@@ -2839,6 +2839,35 @@ TypeFuncClass get_call_result_type(FunctionCallInfo fcinfo,
      cannot accept type record</quote>.)
     </para>
 
+    <para>
+     Another way to setup <structname>TupleDesc</structname> is to use the
+     following functions:
+<programlisting>
+TupleDesc CreateTemplateTupleDesc(int natts);
+void TupleDescInitEntry(TupleDesc desc,
+                        AttrNumber attributeNumber,
+                        const char *attributeName,
+                        Oid oidtypeid,
+                        int32 typmod,
+                        int attdim);
+TupleDesc BlessTupleDesc(TupleDesc tupdesc);
+</programlisting>
+    For example:
+<programlisting>
+    /*
+     * Construct a tuple descriptor for the result row.  The number of output
+     * columns, column names and types must match the function's pg_proc entry
+     * or function's definition.
+     */
+    tupdesc = CreateTemplateTupleDesc(4);
+    TupleDescInitEntry(tupdesc, (AttrNumber) 1, "foo", INT4OID, -1, 0);
+    TupleDescInitEntry(tupdesc, (AttrNumber) 2, "bar", BOOLOID, -1, 0);
+    TupleDescInitEntry(tupdesc, (AttrNumber) 3, "baz", TEXTOID, -1, 0);
+    TupleDescInitEntry(tupdesc, (AttrNumber) 4, "qux", TIMESTAMPTZOID, -1, 0);
+    tupdesc = BlessTupleDesc(tupdesc);
+</programlisting>
+    </para>
+
     <tip>
      <para>
       <function>get_call_result_type</function> can resolve the actual type of a
@@ -2849,6 +2878,21 @@ TypeFuncClass get_call_result_type(FunctionCallInfo fcinfo,
      </para>
     </tip>
 
+    <note>
+     <para>
+        <function>get_call_result_type</function> is relatively expensive
+        as it has to look up system catalogs and do other things to setup
+        <structname>TupleDesc</structname>. While it is recommended
+        in most of the cases, remember to consider setting up
+        <structname>TupleDesc</structname> with
+        <function>CreateTemplateTupleDesc</function>,
+        <function>TupleDescInitEntry</function> and
+        <function>BlessTupleDesc</function> as shown above, if the function
+        returns set or the function is possible used repeatedly
+        (monitoring purposes, for instance).
+     </para>
+    </note>
+
     <note>
      <para>
       <function>get_call_result_type</function> has a sibling
-- 
2.34.1