List:Commits« Previous MessageNext Message »
From:paul Date:December 17 2005 5:09pm
Subject:svn commit - mysqldoc@docsrva: r580 - in trunk: . refman-5.1
View as plain text  
Author: paul
Date: 2005-12-17 18:09:03 +0100 (Sat, 17 Dec 2005)
New Revision: 580

Log:
 r4863@frost:  paul | 2005-12-17 11:08:34 -0600
 Some updates to plugin API discussion.


Modified:
   trunk/
   trunk/refman-5.1/extending-mysql.xml


Property changes on: trunk
___________________________________________________________________
Name: svk:merge
   - b5ec3a16-e900-0410-9ad2-d183a3acac99:/mysqldoc-local/mysqldoc/trunk:4856
bf112a9c-6c03-0410-a055-ad865cd57414:/mysqldoc-local/mysqldoc/trunk:1694
   + b5ec3a16-e900-0410-9ad2-d183a3acac99:/mysqldoc-local/mysqldoc/trunk:4863
bf112a9c-6c03-0410-a055-ad865cd57414:/mysqldoc-local/mysqldoc/trunk:1694

Modified: trunk/refman-5.1/extending-mysql.xml
===================================================================
--- trunk/refman-5.1/extending-mysql.xml	2005-12-17 15:35:55 UTC (rev 579)
+++ trunk/refman-5.1/extending-mysql.xml	2005-12-17 17:09:03 UTC (rev 580)
@@ -901,10 +901,6 @@
         <filename>libmyplugin.dylib</filename>).
       </para>
 
-      <remark role="todo">
-        What is the library name on Windows? libmyplugin.dll?
-      </remark>
-
       <para>
         The shared library must be located in the plugin directory (that
         is, the directory named by the <literal>plugin_dir</literal>
@@ -971,6 +967,37 @@
 
       <remark role="help-description-end"/>
 
+      <para>
+        If you recompile a plugin library and need to reinstall it, you
+        can use either of the following procedures:
+      </para>
+
+      <itemizedlist>
+
+        <listitem>
+          <para>
+            Use <literal>UNINSTALL PLUGIN</literal> to uninstall all
+            plugins in the library, install the new plugin library file
+            in the plugin directory, and then use <literal>INSTALL
+            PLUGIN</literal> to install all plugins in the library. This
+            procedure has the advantage that it can be used without
+            stopping the server. However, if the plugin library contains
+            many plugins, you must issue many <literal>INSTALL
+            PLUGIN</literal> and <literal>UNINSTALL PLUGIN</literal>
+            statements.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            Alternatively, stop the server, install the new plugin
+            library file in the plugin directory, and then restart the
+            server.
+          </para>
+        </listitem>
+
+      </itemizedlist>
+
     </section>
 
     <section id="uninstall-plugin">
@@ -1187,8 +1214,8 @@
               the plugin is loaded, which happens for <literal>INSTALL
               PLUGIN</literal> or, for plugins listed in the
               <literal>plugin</literal> table, at server startup. The
-              function takes no arguments. It returns 0 for success and
-              1 for failure.
+              function takes no arguments. It returns zero for success
+              and non-zero for failure.
             </para>
           </listitem>
 
@@ -1202,8 +1229,8 @@
               when the plugin is unloaded, which happens for
               <literal>UNINSTALL PLUGIN</literal> or, for plugins listed
               in the <literal>plugin</literal> table, at server
-              shutdown. The function takes no arguments. It returns 0
-              for success and 1 for failure.
+              shutdown. The function takes no arguments. It returns zero
+              for success and non-zero for failure.
             </para>
           </listitem>
 
@@ -1296,10 +1323,46 @@
 
         </itemizedlist>
 
+        <remark role="todo">
+          Next para/bullet list are general, so when we have other
+          plugin types than full-text parsers, they should probably get
+          moved somewhere that discusses descriptors in a more general
+          manner.
+        </remark>
+
         <para>
+          Note that the plugin declaration in the plugin library
+          descriptor has initialization and deinitialization functions,
+          and so does the plugin descriptor to which it points. These
+          pairs of functions have different purposes and are invoked for
+          different reasons:
+        </para>
+
+        <itemizedlist>
+
+          <listitem>
+            <para>
+              For the plugin declaration in the plugin library
+              descriptor, the initialization and deinitialization
+              functions are invoked when the plugin is loaded and
+              unloaded.
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              For the plugin descriptor, the initialization and
+              deinitialization functions are invoked per SQL statement
+              for which the plugin is used.
+            </para>
+          </listitem>
+
+        </itemizedlist>
+
+        <para>
           Each interface function named in the plugin descriptor should
-          return 0 for success or 1 for failure, and each of them
-          receives an argument that points to a
+          return zero for success or non-zero for failure, and each of
+          them receives an argument that points to a
           <literal>MYSQL_FTPARSER_PARAM</literal> structure containing
           the parsing context. The structure has this definition:
         </para>
@@ -1640,10 +1703,6 @@
 
         <title>&title-plugin-creating;</title>
 
-        <remark role="todo">
-          Mention the header files.
-        </remark>
-
         <para>
           This section describes a step-by-step procedure for creating a
           plugin library that contains a full-text parsing plugin named
@@ -1712,6 +1771,22 @@
 
           <listitem>
             <para>
+              Include the header files that the plugin library needs.
+              The <filename>plugin.h</filename> file is required, and
+              the library might require other files as well. For
+              example:
+            </para>
+
+<programlisting>
+#include &lt;my_global.h&gt;
+#include &lt;m_string.h&gt;
+#include &lt;m_ctype.h&gt;
+#include &lt;plugin.h&gt;
+</programlisting>
+          </listitem>
+
+          <listitem>
+            <para>
               Set up the plugin library file descriptor.
             </para>
 
@@ -1833,6 +1908,15 @@
   ,{0,0,0,0,0,0,0}
 };
 </programlisting>
+
+            <para>
+              The preceding example declares a single plugin in the
+              library descriptor, but it is possible to declare multiple
+              plugins. List the declarations one after the other between
+              <literal>mysql_declare_plugin</literal> and
+              <literal>mysql_declare_plugin_end</literal>, separated by
+              commas.
+            </para>
           </listitem>
 
           <listitem>
@@ -1874,7 +1958,7 @@
               names the initialization and deinitialization functions
               that the server should invoke when it loads and unloads
               the plugin. For <literal>simple_parser</literal>, these
-              functions do nothing but return 0 to indicate that they
+              functions do nothing but return zero to indicate that they
               succeeded:
             </para>
 
@@ -1977,7 +2061,7 @@
   MYSQL_FTPARSER_BOOLEAN_INFO bool_info=
     { FT_TOKEN_WORD, 0, 0, 0, 0, ' ', 0 };
 
-  if (param-&gt;mode &amp; MYSQL_FTPARSER_FULL_BOOLEAN_INFO)
+  if (param-&gt;mode == MYSQL_FTPARSER_FULL_BOOLEAN_INFO)
     param-&gt;mysql_add_word(param-&gt;mysql_ftparam, word, len, &amp;bool_info);
   else
     param-&gt;mysql_add_word(param-&gt;mysql_ftparam, word, len, 0);

Thread
svn commit - mysqldoc@docsrva: r580 - in trunk: . refman-5.1paul17 Dec