I have been working with user defined types and user defined c

functions.  One problem that I have encountered with the function
manager is that it does not allow the user to define type conversion
functions that convert between user types. For instance if mytype1,
mytype2, and mytype3 are three Postgresql user types, and if I wish to
define Postgresql conversion functions like

I run into problems, because the Postgresql dynamic loader would look
for a single link symbol, mytype3, for both pieces of object code.  If
I just change the name of one of the Postgresql functions (to make the
symbols distinct), the automatic type conversion that Postgresql uses,
for example, when matching operators to arguments no longer finds the
type conversion function.

The solution that I propose, and have implemented in the attatched
patch extends the CREATE FUNCTION syntax as follows. In the first case
above I use the link symbol mytype2_to_mytype3 for the link object
that implements the first conversion function, and define the
Postgresql operator with the following syntax

The patch includes changes to the parser to include the altered
syntax, changes to the ProcedureStmt node in nodes/parsenodes.h,
changes to commands/define.c to handle the extra information in the AS
clause, and changes to utils/fmgr/dfmgr.c that alter the way that the
dynamic loader figures out what link symbol to use.  I store the
string for the link symbol in the prosrc text attribute of the pg_proc
table which is currently unused in rows that reference dynamically
loaded
functions.


Bernie Frankpitt

2 files changed, 111 insertions, 40 deletions

diff --git a/doc/src/sgml/ref/create_function.sgml b/doc/src/sgml/ref/create_function.sgml
index 84f4f5c958f..b22b9e4088f 100644
--- a/doc/src/sgml/ref/create_function.sgml
+++ b/doc/src/sgml/ref/create_function.sgml
@@ -1,5 +1,5 @@
 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_function.sgml,v 1.9 1999/07/22 15:09:07 thomas Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_function.sgml,v 1.10 1999/09/28 04:34:39 momjian Exp $
 Postgres documentation
 -->
 
@@ -25,8 +25,14 @@ Postgres documentation
   <synopsis>
 CREATE FUNCTION <replaceable class="parameter">name</replaceable> ( [ <replaceable class="parameter">ftype</replaceable> [, ...] ] )
     RETURNS <replaceable class="parameter">rtype</replaceable>
-    AS <replaceable class="parameter">definition</replaceable>
+    AS <replaceable class="parameter">definition</replaceable>   
     LANGUAGE '<replaceable class="parameter">langname</replaceable>'
+
+
+CREATE FUNCTION <replaceable class="parameter">name</replaceable> ( [ <replaceable class="parameter">ftype</replaceable> [, ...] ] )
+    RETURNS <replaceable class="parameter">rtype</replaceable>
+    AS <replaceable class="parameter">obj_file</replaceable> , <replaceable class="parameter">link_symbol</replaceable>  
+    LANGUAGE 'c'
   </synopsis>
   
   <refsect2 id="R2-SQL-CREATEFUNCTION-1">
@@ -84,6 +90,22 @@ CREATE FUNCTION <replaceable class="parameter">name</replaceable> ( [ <replaceab
       </listitem>
      </varlistentry>
      <varlistentry>
+      <term><replaceable class="parameter">obj_file</replaceable> , <replaceable class="parameter">link_symbol</replaceable></term>
+      <listitem>
+       <para>
+	This form of the <command>AS</command> clause is used for
+	dynamically-linked, C language functions when the function name in
+	the C language source code is not the same as the name of the SQL
+	function. The string <replaceable
+	class="parameter">obj_file</replaceable> is the name of the file
+	containing the dynamically loadable object, and <replaceable
+	class="parameter">link_symbol</replaceable>, is the object's link
+	symbol which is the same as the name of the function in the C
+	language source code.
+       </para>
+      </listitem>
+     </varlistentry>
+     <varlistentry>
       <term><replaceable class="parameter">langname</replaceable></term>
       <listitem>
        <para>
@@ -165,10 +187,10 @@ CREATE
    <para>
     <productname>Postgres</productname> allows function "overloading";
     that is, the same name can be used for several different functions
-    so long as they have distinct argument types.  This facility must be
-    used with caution for <literal>internal</literal>
-    and C-language functions, however.
-   </para>
+    so long as they have distinct argument types.  This facility must
+    be used with caution for <literal>internal</literal> and
+    C-language functions, however.    
+	</para>
 
    <para>
     Two <literal>internal</literal>
@@ -181,18 +203,15 @@ CREATE
    </para>
 
    <para>
-    For dynamically-loaded C functions, the SQL name of the function must
-    be the same as the C function name, because the AS clause is used to
-    give the path name of the object file containing the C code.  In this
-    situation it is best not to try to overload SQL function names.  It
-    might work to load a C function that has the same C name as an internal
-    function or another dynamically-loaded function --- or it might not.
-    On some platforms the dynamic loader may botch the load in interesting
-    ways if there is a conflict of C function names.  So, even if it works
-    for you today, you might regret overloading names later when you try
-    to run the code somewhere else.
+    When overloading SQL functions with C-language functions, give
+    each C-language instance of the function a distinct name, and use
+    the alternative form of the <command>AS</command> clause in the
+    <command>CREATE FUNCTION</command> syntax to ensure that
+    overloaded SQL functions names are resolved to the correct
+    dynamically linked objects.
    </para>
 
+
    <para>
     A C function cannot return a set of values.
    </para>
@@ -227,7 +246,6 @@ SELECT one() AS answer;
    is correct. It is intended for use in a CHECK contraint.
   </para>
   <programlisting>
-   <userinput>
 CREATE FUNCTION ean_checkdigit(bpchar, bpchar) RETURNS bool
     AS '/usr1/proj/bray/sql/funcs.so' LANGUAGE 'c';
     
@@ -238,8 +256,41 @@ CREATE TABLE product (
     eancode   char(6) CHECK (eancode ~ '[0-9]{6}'),
     CONSTRAINT ean    CHECK (ean_checkdigit(eanprefix, eancode))
 );
-   </userinput>
   </programlisting>
+
+
+  <para>
+   This example creates a function that does type conversion between the
+   user defined type complex, and the internal type point.  The
+   function is implemented by a dynamically loaded object that was
+   compiled from C source. For <productname>Postgres</productname> to
+   find a type conversion function automatically, the sql function has
+   to have the same name as the return type, and overloading is
+   unavoidable.  The function name is overloaded by using the second
+   form of the <command>AS</command> clause in the SQL definition
+  </para>
+  <programlisting>
+CREATE FUNCTION point(complex) RETURNS point
+    AS '/home/bernie/pgsql/lib/complex.so', 'complex_to_point'
+    LANGUAGE 'c';
+  </programlisting>
+  <para>
+  The C decalaration of the function is:
+  </para>
+  <programlisting>
+Point * complex_to_point (Complex *z)
+{
+	Point *p;
+
+	p = (Point *) palloc(sizeof(Point));
+	p->x = z->x;
+	p->y = z->y;
+		
+	return p;
+}
+  </programlisting>
+
+    
  </refsect1>
  
  <refsect1 id="R1-SQL-CREATEFUNCTION-4">
@@ -283,8 +334,7 @@ CREATE TABLE product (
     SQL/PSM <command>CREATE FUNCTION</command> has the following syntax:
     <synopsis>
 CREATE FUNCTION <replaceable class="parameter">name</replaceable>
-    ( [ [ IN | OUT | INOUT ] <replaceable class="parameter">eter</replaceable>eable>eable> <replaceable
-      class="parameter">type</replaceable> [, ...] ] )
+    ( [ [ IN | OUT | INOUT ] <replaceable class="parameter">type</replaceable> [, ...] ] )
      RETURNS <replaceable class="parameter">rtype</replaceable>
      LANGUAGE '<replaceable class="parameter">langname</replaceable>'
      ESPECIFIC <replaceable class="parameter">routine</replaceable>
diff --git a/doc/src/sgml/xfunc.sgml b/doc/src/sgml/xfunc.sgml
index 036d029d818..879f6f66672 100644
--- a/doc/src/sgml/xfunc.sgml
+++ b/doc/src/sgml/xfunc.sgml
@@ -357,25 +357,43 @@ WARN::function declared to return type EMP does not retrieve (EMP.*)
    <title>Compiled (C) Language Functions</title>
 
    <para>
-    Functions written in C can be defined to Postgres, which will dynamically
-    load them into its address space.  The AS
-    clause gives the full path name of the object file that contains the
-    function.  This file is loaded either using
-    load(l)
-    or automatically the first time the function is necessary for
-    execution. Repeated execution of a function will cause negligible
-    additional overhead, as the function will remain in a main memory
-    cache.
+    Functions written in C can be compiled into dynamically loadable
+    objects, and used to implement user-defined SQL functions.  The
+    first time the user defined function is called inside the backend,
+    the dynamic loader loads the function's object code into memory,
+    and links the function with the running
+    <productname>Postgres</productname> executable.  The SQL syntax
+    for the <xref linkend="sql-createfunction-title"
+    endterm="sql-createfunction-title"> command links the SQL function
+    to the C source function in one of two ways. If the SQL function
+    has the same name as the C source function the first form of the
+    statement is used. The string argument in the AS clause is the
+    full pathname of the file that contains the dynamically loadable
+    compiled object.  If the name of C function is different from the
+    name of the SQL function, then the second form is used. In this
+    form the AS clause takes two string arguments, the first is the
+    full pathname of the dynamically loadable object file, and the
+    second is the link symbol that the dynamic loader should search
+    for. This link symbol is just the function name in the C source
+    code.
+
+	After it is used for the first time, a dynamically loaded, user
+	function is retained in memory, and future calls to the function
+	only incur the small overhead of a symbol table lookup.
    </para>
 
    <para>
-    The string which specifies the object file (the string in the AS clause)
-    should be the <emphasis>full path</emphasis>
-    of the object code file for the function, bracketed by quotation
-    marks.  (<productname>Postgres</productname> will not compile a
-    function automatically; it must
-    be compiled before it is used in a CREATE FUNCTION
-    command.  See below for additional information.)
+    The string which specifies the object file (the string in the AS
+    clause) should be the <emphasis>full path</emphasis> of the object
+    code file for the function, bracketed by quotation marks.  If a
+    link symbol is used in the AS clause, the link symbol should also be
+    bracketed by single quotation marks, and should be exactly the
+    same as the name of function in the C source code. On UNIX systems
+    the command <command>nm</command> will print all of the link
+    symbols in a dynamically loadable object.
+    (<productname>Postgres</productname> will not compile a function
+    automatically; it must be compiled before it is used in a CREATE
+    FUNCTION command.  See below for additional information.)
    </para>
 
    <sect2>
@@ -960,10 +978,13 @@ memmove(destination-&gt;data, buffer, 40);
     <title>Name Space Conflicts</title>
 
     <para>
-     As of <productname>Postgres</productname> v6.5,
-     <command>CREATE FUNCTION</command> can decouple a C language
-     function name from the name of the entry point. This is now the
-     preferred technique to accomplish function overloading.
+     As of <productname>Postgres</productname> v6.6, the alternative
+	 form of the AS clause for the SQL <command>CREATE
+	 FUNCTION</command> command described in <xref
+	 linkend="sql-createfunction-title" endterm="sql-createfunction-title">
+	 decouples the SQL function name from the function name in the C
+	 source code. This is now the preferred technique to accomplish
+	 function overloading.
     </para>
 
     <sect3>