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 <my_global.h>
+#include <m_string.h>
+#include <m_ctype.h>
+#include <plugin.h>
+</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->mode & MYSQL_FTPARSER_FULL_BOOLEAN_INFO)
+ if (param->mode == MYSQL_FTPARSER_FULL_BOOLEAN_INFO)
param->mysql_add_word(param->mysql_ftparam, word, len, &bool_info);
else
param->mysql_add_word(param->mysql_ftparam, word, len, 0);
| Thread |
|---|
| • svn commit - mysqldoc@docsrva: r580 - in trunk: . refman-5.1 | paul | 17 Dec |
