path: root/man/ndbmtd.8

'\" t
.\"     Title: \fBndbmtd\fR
.\"    Author: [FIXME: author] [see http://docbook.sf.net/el/author]
.\" Generator: DocBook XSL Stylesheets v1.75.2 <http://docbook.sf.net/>
.\"      Date: 04/06/2010
.\"    Manual: MySQL Database System
.\"    Source: MySQL 5.1
.\"  Language: English
.\"
.TH "\FBNDBMTD\FR" "8" "04/06/2010" "MySQL 5\&.1" "MySQL Database System"
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.\" ndbmtd
.\" MySQL Cluster: ndbmtd
.\" MySQL Cluster: data nodes
.\" data nodes (MySQL Cluster)
.\" storage nodes - see data nodes, ndbd, ndbmtd
.SH "NAME"
ndbmtd \- the MySQL Cluster data node daemon (multi\-threaded version)
.SH "SYNOPSIS"
.HP \w'\fBndbmtd\ \fR\fB\fIoptions\fR\fR\ 'u
\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
\fBndbd\fR(8), and
Section\ \&17.3.2.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
Prior to MySQL Cluster NDB 7\&.0\&.6, there were known issues when using
\fBndbmtd\fR
with MySQL Cluster Disk Data tables\&. If you wish to use multi\-threaded data nodes with disk\-based
NDB
tables, you should ensure that you are running MySQL Cluster NDB 7\&.0\&.6 or later\&. (\m[blue]\fBBug#41915\fR\m[]\&\s-2\u[1]\d\s+2,
\m[blue]\fBBug#44915\fR\m[]\&\s-2\u[2]\d\s+2)
.PP
Using
\fBndbmtd\fR
differs from using
\fBndbd\fR
in two key respects:
.sp
.RS 4
.ie n \{\
\h'-04' 1.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  1." 4.2
.\}
You must set an appropriate value for the
MaxNoOfExecutionThreads
configuration parameter in the
config\&.ini
file\&. If you do not do so,
\fBndbmtd\fR
runs in single\-threaded mode \(em that is, it behaves like
\fBndbd\fR\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 2.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  2." 4.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\&.
.RE
.PP
These differences are discussed in more detail in the next few paragraphs\&.
.\" execution threads (MySQL Cluster)
.\" MySQL Cluster: execution threads
.\" ndbmtd: MaxNoOfExecutionThreads
.\" MaxNoOfExecutionThreads: ndbmtd
.\" ndbmtd: trace files
.\" trace files: ndbmtd
.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
config\&.ini
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 parameter equal 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 1
.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:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
1 local query handler (LQH) thread
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
1 transaction coordinator (TC) thread
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
1 transporter thread
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
1 subscription manager (SUMA) thread
.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{
config\&.ini 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 1
.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\&.
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBNote\fR
.ps -1
.br
.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\&.
.sp .5v
.RE
.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\&.
.\" MySQL Cluster: log files
.\" log files (MySQL Cluster): ndbmtd
.\" ndbmtd: trace files
.PP
Like
\fBndbd\fR,
\fBndbmtd\fR
generates a set of log files which are placed in the directory specified by
DataDir
in the
config\&.ini
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
ndb_\fInode_id\fR_trace\&.log\&.\fItrace_id\fR_t\fIthread_id\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
ndb_3_trace\&.log\&.1_t1,
ndb_3_trace\&.log\&.1_t2,
ndb_3_trace\&.log\&.1_t3, and
ndb_3_trace\&.log\&.1_t4\&. 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
\m[blue]\fBndbd Error Messages\fR\m[]\&\s-2\u[3]\d\s+2, for a listing of these\&.
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBNote\fR
.ps -1
.br
.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\&.
.sp .5v
.RE
.SH "COPYRIGHT"
.br
.PP
Copyright 2007-2008 MySQL AB, 2008-2010 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/.
.sp
.SH "NOTES"
.IP " 1." 4
Bug#41915
.RS 4
\%http://bugs.mysql.com/bug.php?id=41915
.RE
.IP " 2." 4
Bug#44915
.RS 4
\%http://bugs.mysql.com/bug.php?id=44915
.RE
.IP " 3." 4
ndbd Error Messages
.RS 4
\%http://dev.mysql.com/doc/ndbapi/en/ndbd-error-messages.html
.RE
.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
Sun Microsystems, Inc. (http://www.mysql.com/).