Document a gotcha that happens on Windows when using libpq's new event

procedure support: it's possible to get confused because exported procedures
have two different addresses.  Per Andrew Chernow.

diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml
index 99f6cf82e804c1af96c8f6b990569ecf2f204116..554471f5270a3f9779a8c1b4f3201c5651e29afc 100644 (file)
--- a/doc/src/sgml/libpq.sgml
+++ b/doc/src/sgml/libpq.sgml
@@ -5255,6 +5255,19 @@ int eventproc(PGEventId evtId, void *evtInfo, void *passThrough)
        <structname>PGconn</>.  This is because the address of the procedure
        is used as a lookup key to identify the associated instance data.
       </para>
+
+      <caution>
+       <para>
+        On Windows, functions can have two different addresses: one visible
+        from outside a DLL and another visible from inside the DLL.  One
+        should be careful that only one of these addresses is used with
+        <application>libpq</>'s event-procedure functions, else confusion will
+        result.  The simplest rule for writing code that will work is to
+        ensure that event procedures are declared <literal>static</>.  If the
+        procedure's address must be available outside its own source file,
+        expose a separate function to return the address.
+       </para>
+      </caution>
      </listitem>
     </varlistentry>
    </variablelist>