Imported freely distributable documentation from upstream MySQL 5.1.34 source tarball.

1 files changed, 285 insertions, 0 deletions

diff --git a/man/ndbmtd.8 b/man/ndbmtd.8
new file mode 100644
index 00000000000..b1e977f7857
--- /dev/null
+++ b/man/ndbmtd.8
@@ -0,0 +1,285 @@
+.\"     Title: \fBndbmtd\fR
+.\"    Author: 
+.\" Generator: DocBook XSL Stylesheets v1.70.1 <http://docbook.sf.net/>
+.\"      Date: 03/31/2009
+.\"    Manual: MySQL Database System
+.\"    Source: MySQL 5.1
+.\"
+.TH "\fBNDBMTD\fR" "8" "03/31/2009" "MySQL 5.1" "MySQL Database System"
+.\" disable hyphenation
+.nh
+.\" disable justification (adjust text to left margin only)
+.ad l
+.SH "NAME"
+ndbmtd \- the MySQL Cluster storage engine node process (multi\-threaded version)
+.SH "SYNOPSIS"
+.HP 15
+\fBndbmtd \fR\fB\fIoptions\fR\fR
+.SH "DESCRIPTION"
+.PP
+\fBndbmtd\fR
+is a multi\-threaded version of
+\fBndbd\fR, the process that is used to handle all the data in tables using the
+NDBCLUSTER
+storage engine.
+\fBndbmtd\fR
+is intended for use on host computers having multiple CPU cores. Except where otherwise noted,
+\fBndbmtd\fR
+functions in the same way as
+\fBndbd\fR; therefore, in this section, we concentrate on the ways in which
+\fBndbmtd\fR
+differs from
+\fBndbd\fR, and you should consult
+\fBndbd\fR(8), for additional information about running MySQL Cluster data nodes that apply to both the single\-threaded and multi\-threaded versions of the data node process.
+.PP
+Command\-line options and configuration parameters used with
+\fBndbd\fR
+also apply to
+\fBndbmtd\fR. For more information about these options and parameters, see
+Section\ 17.6.2.1, \(lqCommand Options for \fBndbd\fR and \fBndbmtd\fR\(rq, and
+Section\ 17.3.4.6, \(lqDefining MySQL Cluster Data Nodes\(rq, respectively.
+.PP
+\fBndbmtd\fR
+is also file system\-compatible with
+\fBndbd\fR. In other words, a data node running
+\fBndbd\fR
+can be stopped, the binary replaced with
+\fBndbmtd\fR, and then restarted without any loss of data. (However, when doing this, you must make sure that
+MaxNoOfExecutionThreads
+is set to an apppriate value before restarting the node if you wish for
+\fBndbmtd\fR
+to run in multi\-threaded fashion.) Similarly, an
+\fBndbmtd\fR
+binary can be replaced with
+\fBndbd\fR
+simply by stopping the node and then starting
+\fBndbd\fR
+in place of the multi\-threaded binary. It is not necessary when switching between the two to start the data node binary using
+\fB\-\-initial\fR.
+.PP
+Using
+\fBndbmtd\fR
+differs from using
+\fBndbd\fR
+in two key respects:
+.TP 3n
+1.
+You must set an appropriate value for the
+MaxNoOfExecutionThreads
+configuration parameter in the
+\fIconfig.ini\fR
+file. If you do not do so,
+\fBndbmtd\fR
+runs in single\-threaded mode \(em that is, it behaves like
+\fBndbd\fR.
+.TP 3n
+2.
+Trace files are generated by critical errors in
+\fBndbmtd\fR
+processes in a somewhat different fashion from how these are generated by
+\fBndbd\fR
+failures.
+.sp
+.RE
+.PP
+These differences are discussed in more detail in the next few paragraphs.
+.PP
+\fBNumber of execution threads\fR. The
+MaxNoOfExecutionThreads
+configuration parameter is used to determine the number of local query handler (LQH) threads spawned by
+\fBndbmtd\fR. Although this parameter is set in
+[ndbd]
+or
+[ndbd default]
+sections of the
+\fIconfig.ini\fR
+file, it is exclusive to
+\fBndbmtd\fR
+and does not apply to
+\fBndbd\fR.
+.PP
+This parameter takes an integer value from 2 to 8 inclusive. Generally, you should set this to the number of CPU cores on the data node host, as shown in the following table:
+.TS
+allbox tab(:);
+lB lB.
+T{
+Number of Cores
+T}:T{
+Recommended MaxNoOfExecutionThreads Value
+T}
+.T&
+l l
+l l
+l l.
+T{
+2
+T}:T{
+2
+T}
+T{
+4
+T}:T{
+4
+T}
+T{
+8 or more
+T}:T{
+8
+T}
+.TE
+.sp
+.PP
+(It is possible to set this parameter to other values within the permitted range, but these are automatically rounded as shown in the
+\fBValue Used\fR
+column of the next table in this section.)
+.PP
+The multi\-threaded data node process always spawns at least 4 threads:
+.TP 3n
+\(bu
+1 local query handler (LQH) thread
+.TP 3n
+\(bu
+1 transaction coordinator (TC) thread
+.TP 3n
+\(bu
+1 transporter thread
+.TP 3n
+\(bu
+1 subscription manager (SUMA) thread
+.sp
+.RE
+.PP
+Setting this parameter to a value between 4 and 8 inclusive causes additional LQH threads to be used by
+\fBndbmtd\fR
+(up to a maximum of 4 LQH threads), as shown in the following table:
+.TS
+allbox tab(:);
+lB lB lB.
+T{
+\fIconfig.ini\fR Value
+T}:T{
+Value Used
+T}:T{
+Number of LQH Threads Used
+T}
+.T&
+l l l
+l l l
+l l l.
+T{
+3
+T}:T{
+2
+T}:T{
+1
+T}
+T{
+5 or 6
+T}:T{
+4
+T}:T{
+2
+T}
+T{
+7
+T}:T{
+8
+T}:T{
+4
+T}
+.TE
+.sp
+.PP
+Setting this parameter outside the permitted range of values causes the management server to abort on startup with the error
+Error line \fInumber\fR: Illegal value \fIvalue\fR for parameter MaxNoOfExecutionThreads.
+.sp
+.it 1 an-trap
+.nr an-no-space-flag 1
+.nr an-break-flag 1
+.br
+\fBNote\fR
+.PP
+In MySQL Cluster NDB 6.4.0, it is not possible to set
+MaxNoOfExecutionThreads
+to 2. You can safely use the value 3 instead (it is treated as 2 internally). This issue is resolved in MySQL Cluster NDB 6.4.1.
+.PP
+In MySQL Cluster NDB 6.4.0 through 6.4.3, the default value for this parameter was undefined, although the default behavior for
+\fBndbmtd\fR
+was to use 1 LQH thread, as though
+MaxNoOfExecutionThreads
+had been set to 2. Beginning with MySQL Cluster NDB 7.0.4, this parameter has an explcit default value of 2, thus guaranteeing this default behavior.
+.PP
+In MySQL Cluster NDB 7.0, it is not possible to cause
+\fBndbmtd\fR
+to use more than 1 TC thread, although we plan to introduce this capability in a future MySQL Cluster release series.
+.PP
+Like
+\fBndbd\fR,
+\fBndbmtd\fR
+generates a set of log files which are placed in the directory specified by
+DataDir
+in the
+\fIconfig.ini\fR
+configuration file. Except for trace files, these are generated in the same way and have the same names as those generated by
+\fBndbd\fR.
+.PP
+In the event of a critical error,
+\fBndbmtd\fR
+generates trace files describing what happened just prior to the error' occurrence. These files, which can be found in the data node's
+DataDir, are useful for analysis of problems by the MySQL Cluster Development and Support teams. One trace file is generated for each
+\fBndbmtd\fR
+thread. The names of these files follow the pattern
+\fIndb_\fR\fI\fInode_id\fR\fR\fI_trace.log.\fR\fI\fItrace_id\fR\fR\fI_t\fR\fI\fIthread_id\fR\fR, where
+\fInode_id\fR
+is the data node's unique node ID in the cluster,
+\fItrace_id\fR
+is a trace sequence number, and
+\fIthread_id\fR
+is the thread ID. For example, in the event of the failure of an
+\fBndbmtd\fR
+process running as a MySQL Cluster data node having the node ID 3 and with
+MaxNoOfExecutionThreads
+equal to 4, four trace files are generated in the data node's data directory; if the is the first time this node has failed, then these files are named
+\fIndb_3_trace.log.1_t1\fR,
+\fIndb_3_trace.log.1_t2\fR,
+\fIndb_3_trace.log.1_t3\fR, and
+\fIndb_3_trace.log.1_t4\fR. Internally, these trace files follow the same format as
+\fBndbd\fR
+trace files.
+.PP
+The
+\fBndbd\fR
+exit codes and messages that are generated when a data node process shuts down prematurely are also used by
+\fBndbmtd\fR. See
+[1]\&\fIndbd Error Messages\fR, for a listing of these.
+.sp
+.it 1 an-trap
+.nr an-no-space-flag 1
+.nr an-break-flag 1
+.br
+\fBNote\fR
+.PP
+It is possible to use
+\fBndbd\fR
+and
+\fBndbmtd\fR
+concurrently on different data nodes in the same MySQL Cluster. However, such configurations have not been tested extensively; thus, we cannot not recommend doing so in a production setting at this time.
+.SH "COPYRIGHT"
+.PP
+Copyright 2007\-2008 MySQL AB, 2009 Sun Microsystems, Inc.
+.PP
+This documentation is free software; you can redistribute it and/or modify it only under the terms of the GNU General Public License as published by the Free Software Foundation; version 2 of the License.
+.PP
+This documentation is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
+.PP
+You should have received a copy of the GNU General Public License along with the program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110\-1301 USA or see http://www.gnu.org/licenses/.
+.SH "REFERENCES"
+.TP 3
+1.\ ndbd Error Messages
+\%http://dev.mysql.com/doc/ndbapi/en/ndbd\-error\-messages.html
+.SH "SEE ALSO"
+For more information, please refer to the MySQL Reference Manual,
+which may already be installed locally and which is also available
+online at http://dev.mysql.com/doc/.
+.SH AUTHOR
+MySQL AB (http://www.mysql.com/).