Re: Allow substitute allocators for PGresult. - Mailing list pgsql-hackers

Hello,
The documentation had slipped my mind.
This is the patch to add the documentation of PGresult customstorage. It shows in section '31.19. Alternative
resultstorage'.
regards,

-- 
Kyotaro Horiguchi
NTT Open Source Software Center
diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml
index 252ff8c..dc2acb6 100644
--- a/doc/src/sgml/libpq.sgml
+++ b/doc/src/sgml/libpq.sgml
@@ -7229,6 +7229,325 @@ int PQisthreadsafe(); </sect1>
+ <sect1 id="libpq-alterstorage">
+  <title>Alternative result storage</title>
+
+  <indexterm zone="libpq-alterstorage">
+   <primary>PGresult</primary>
+   <secondary>PGconn</secondary>
+  </indexterm>
+
+  <para>
+   As the standard usage, users can get the result of command
+   execution from <structname>PGresult</structname> aquired
+   with <function>PGgetResult</function>
+   from <structname>PGConn</structname>. While the memory areas for
+   the PGresult are allocated with malloc() internally within calls of
+   command execution functions such as <function>PQexec</function>
+   and <function>PQgetResult</function>. If you have difficulties to
+   handle the result records in the form of PGresult, you can instruct
+   PGconn to store them into your own storage instead of PGresult.
+  </para>
+
+  <variablelist>
+   <varlistentry id="libpq-registertupleadder">
+    <term>
+     <function>PQregisterTupleAdder</function>
+     <indexterm>
+      <primary>PQregisterTupleAdder</primary>
+     </indexterm>
+    </term>
+
+    <listitem>
+     <para>
+       Sets a function to allocate memory for each tuple and column
+       values, and add the completed tuple into your storage.
+<synopsis>
+void PQregisterTupleAdder(PGconn *conn,
+                          addTupleFunction func,
+                          void *param);
+</synopsis>
+     </para>
+     
+     <para>
+       <variablelist>
+     <varlistentry>
+       <term><parameter>conn</parameter></term>
+       <listitem>
+         <para>
+           The connection object to set the tuple adder
+           function. PGresult created from this connection calles
+           this function to store the result tuples instead of
+           storing into its internal storage.
+         </para>
+       </listitem>
+     </varlistentry>
+     <varlistentry>
+       <term><parameter>func</parameter></term>
+       <listitem>
+         <para>
+           Tuple adder function to set. NULL means to use the
+           default storage.
+         </para>
+       </listitem>
+     </varlistentry>
+     <varlistentry>
+       <term><parameter>param</parameter></term>
+       <listitem>
+         <para>
+           A pointer to contextual parameter passed
+           to <parameter>func</parameter>.
+         </para>
+       </listitem>
+     </varlistentry>
+       </variablelist>
+     </para>
+    </listitem>
+   </varlistentry>
+  </variablelist>
+
+  <variablelist>
+   <varlistentry id="libpq-addtuplefunction">
+    <term>
+     <type>addTupleFunction</type>
+     <indexterm>
+      <primary>addTupleFunction</primary>
+     </indexterm>
+    </term>
+
+    <listitem>
+     <para>
+       The type for the callback function to serve memory blocks for
+       each tuple and its column values, and to add the constructed
+       tuple into your own storage.
+<synopsis>
+typedef enum 
+{
+  ADDTUP_ALLOC_TEXT,
+  ADDTUP_ALLOC_BINARY,
+  ADDTUP_ADD_TUPLE
+} AddTupFunc;
+
+void *(*addTupleFunction)(PGresult *res,
+                          AddTupFunc func,
+                          int id,
+                          size_t size);
+</synopsis>
+     </para>
+
+     <para>
+       Generally this function must return NULL for failure and should
+       set the error message
+       with <function>PGsetAddTupleErrMes</function> if the cause is
+       other than out of memory. This funcion must not throw any
+       exception. This function is called in the sequence following.
+
+       <itemizedlist spacing="compact">
+     <listitem>
+       <simpara>Call with <parameter>func</parameter>
+       = <firstterm>ADDTUP_ALLOC_BINARY</firstterm>
+       and <parameter>id</parameter> = -1 to request the memory
+       for tuple used as an array
+       of <type>PGresAttValue</type> </simpara>
+     </listitem>
+     <listitem>
+       <simpara>Call with <parameter>func</parameter>
+       = <firstterm>ADDTUP_ALLOC_TEXT</firstterm>
+       or <firstterm>ADDTUP_ALLOC_TEXT</firstterm>
+       and <parameter>id</parameter> is zero or positive number
+       to request the memory for each column value in current
+       tuple.</simpara>
+     </listitem>
+     <listitem>
+       <simpara>Call with <parameter>func</parameter>
+       = <firstterm>ADDTUP_ADD_TUPLE</firstterm> to request the
+       constructed tuple to store.</simpara>
+     </listitem>
+       </itemizedlist>
+     </para>
+     <para>
+       Calling <type>addTupleFunction</type>
+       with <parameter>func</parameter> =
+       <firstterm>ADDTUP_ALLOC_TEXT</firstterm> is telling to return a
+        memory block with at least <parameter>size</parameter> bytes
+        which may not be aligned to the word boundary.
+       <parameter>id</parameter> is a zero or positive number
+       distinguishes the usage of requested memory block, that is the
+       position of the column for which the memory block is used.
+     </para>
+     <para>
+       When <parameter>func</parameter>
+       = <firstterm>ADDTUP_ALLOC_BINARY</firstterm>, this function is
+       telled to return a memory block with at
+       least <parameter>size</parameter> bytes which is aligned to the
+       word boundary.
+       <parameter>id</parameter> is the identifier distinguishes the
+       usage of requested memory block. -1 means that it is used as an
+       array of <type>PGresAttValue</type> to store the tuple. Zero or
+       positive numbers have the same meanings as for
+       <firstterm>ADDTUP_ALLOC_BINARY</firstterm>.
+     </para>
+     <para>When <parameter>func</parameter>
+       = <firstterm>ADDTUP_ADD_TUPLE</firstterm>, this function is
+       telled to store the <type>PGresAttValue</type> structure
+       constructed by the caller into your storage. The pointer to the
+       tuple structure is not passed so you should memorize the
+       pointer to the memory block passed the caller on
+       <parameter>func</parameter>
+       = <parameter>ADDTUP_ALLOC_BINARY</parameter>
+       with <parameter>id</parameter> is -1. This function must return
+       any non-NULL values for success. You must properly put back the
+       memory blocks passed to the caller for this function if needed.
+     </para>
+     <variablelist>
+       <varlistentry>
+     <term><parameter>res</parameter></term>
+     <listitem>
+       <para>
+         A pointer to the <type>PGresult</type> object.
+       </para>
+     </listitem>
+       </varlistentry>
+       <varlistentry>
+     <term><parameter>func</parameter></term>
+     <listitem>
+       <para>
+         An <type>enum</type> value telling the function to perform.
+       </para>
+     </listitem>
+       </varlistentry>
+       <varlistentry>
+     <term><parameter>param</parameter></term>
+     <listitem>
+       <para>
+         A pointer to contextual parameter passed to func.
+       </para>
+     </listitem>
+       </varlistentry>
+     </variablelist>
+    </listitem>
+   </varlistentry>
+  </variablelist>
+
+  <variablelist>
+   <varlistentry id="libpq-pqgestasctring">
+    <term>
+     <function>PQgetAsCstring</function>
+     <indexterm>
+      <primary>PQgetAsCstring</primary>
+     </indexterm>
+    </term>
+    <listitem>
+      <para>
+    Get the value of the column pointed
+    by <parameter>attval</parameter> in the form of
+    zero-terminated C string. Returns NULL if the value is null.
+<synopsis>
+char *PQgetAsCstring(PGresAttValue *attval)
+</synopsis>
+      </para>
+      <para>
+    <variablelist>
+      <varlistentry>
+        <term><parameter>attval</parameter></term>
+        <listitem>
+          <para>
+        A pointer to the <type>PGresAttValue</type> object
+        to retrieve the value.
+          </para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+      </para>
+    </listitem>
+   </varlistentry>
+  </variablelist>
+
+  <variablelist>
+   <varlistentry id="libpq-pqgetaddtupleparam">
+    <term>
+     <function>PQgetAddTupleParam</function>
+     <indexterm>
+      <primary>PQgetAddTupleParam</primary>
+     </indexterm>
+    </term>
+    <listitem>
+      <para>
+    Get the pointer passed to <function>PQregisterTupleAdder</function>
+    as <parameter>param</parameter>.
+<synopsis>
+void *PQgetTupleParam(PGresult *res)
+</synopsis>
+      </para>
+      <para>
+    <variablelist>
+      <varlistentry>
+        <term><parameter>res</parameter></term>
+        <listitem>
+          <para>
+        A pointer to the <type>PGresult</type> object.
+          </para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+      </para>
+    </listitem>
+   </varlistentry>
+  </variablelist>
+
+  <variablelist>
+   <varlistentry id="libpq-pqsetaddtupleerrmes">
+    <term>
+     <function>PQsetAddTupleErrMes</function>
+     <indexterm>
+      <primary>PQsetAddTupleErrMes</primary>
+     </indexterm>
+    </term>
+    <listitem>
+      <para>
+    Set the message for the error occurred in <type>addTupleFunction</type>.
+    If this message is not set, the error is assumed to be out of
+    memory.
+<synopsis>
+void PQsetAddTupleErrMes(PGresult *res, char *mes)
+</synopsis>
+      </para>
+      <para>
+    <variablelist>
+      <varlistentry>
+        <term><parameter>res</parameter></term>
+        <listitem>
+          <para>
+        A pointer to the <type>PGresult</type> object
+        in <type>addTupleFunction</type>.
+          </para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term><parameter>mes</parameter></term>
+        <listitem>
+          <para>
+        A pointer to the memory block containing the error
+        message, which must be allocated by alloc(). The
+        memory block will be freed with free() in the caller
+        of
+        <type>addTupleFunction</type> only if it returns NULL.
+          </para>
+          <para>
+        If <parameter>res</parameter> already has a message
+        previously set, it is freed and the given message is
+        set. Set NULL to cancel the the costom message.
+          </para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+      </para>
+    </listitem>
+   </varlistentry>
+  </variablelist>
+ </sect1>
+
+ <sect1 id="libpq-build">  <title>Building <application>libpq</application> Programs</title>