| List: | Commits | « Previous MessageNext Message » | |
| From: | jon | Date: | March 10 2007 1:38pm |
| Subject: | svn commit - mysqldoc@docsrva: r5297 - trunk/ndbapi | ||
| View as plain text | |||
Author: jstephens Date: 2007-03-10 13:38:39 +0100 (Sat, 10 Mar 2007) New Revision: 5297 Log: First part of NDB Protocol draft (new file so it can be built separately). Some additional notes from Jonas. Added: trunk/ndbapi/ndb-internals-ndb-protocol.xml Modified: trunk/ndbapi/ndb-internals.xml Added: trunk/ndbapi/ndb-internals-ndb-protocol.xml =================================================================== --- trunk/ndbapi/ndb-internals-ndb-protocol.xml (rev 0) +++ trunk/ndbapi/ndb-internals-ndb-protocol.xml 2007-03-10 12:38:39 UTC (rev 5297) Changed blocks: 1, Lines Added: 336, Lines Deleted: 0; 9693 bytes @@ -0,0 +1,336 @@ +<?xml version="1.0" encoding="utf-8"?> +<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" +"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" +[ +<!ENTITY % fixedchars.entities SYSTEM "../common/fixedchars.ent"> +%fixedchars.entities; +]> +<section id="ndb-internals-ndb-protocol"> + + <title>The NDB Protocol</title> + + <para> + This document discusses the protocol used for communication between + data nodes and API nodes. + </para> + + <section id="ndb-internals-ndb-protocol-overview"> + + <title><literal>NDB</literal> Protocol Overview</title> + + <para> + MySQL Cluster data and API nodes communicate with one another by + passing messages to one another. The sending of a message from one + node and its reception by another node is referred to as a + <firstterm>signal</firstterm>; the <literal>NDB</literal> Protocol + is the set of rules governing the format of these messages and the + manner in which they are passed. + </para> + + <para> + An <literal>NDB</literal> message is typically either a + <firstterm>request</firstterm> or a + <firstterm>response</firstterm>. A request indicates that an API + node wants to perform an operation involving cluster data, such as + retrieval, insertion, updating, or deletion. A request is, when + necessary, accompanied by key or index information. The response + sent by a data node to this request indicates whether or not the + request succeeded and, where appropriate, is accompanied by one or + more data messages. + </para> + + <formalpara> + + <title>Request operation types</title> + + <para> + Data request operations are of three principal types: + + <itemizedlist> + + <listitem> + <formalpara> + + <title>Primary key lookup operations</title> + + <para> + These are performed through the exchange of + <literal>TCKEY</literal> messages. + </para> + + </formalpara> + </listitem> + + <listitem> + <formalpara> + + <title>Unique key lookup operations</title> + + <para> + These are performed through the exchange of + <literal>TCINDX</literal> messages. + </para> + + </formalpara> + </listitem> + + <listitem> + <formalpara> + + <title>Table or index scan operations</title> + + <para> + These are performed through the exchange of + <literal>SCANTAB</literal> messages. + </para> + + </formalpara> + </listitem> + + </itemizedlist> + </para> + + </formalpara> + + <formalpara> + + <title>Message types</title> + + <para> + There are three types of <literal>NDB</literal> messages: + + <itemizedlist> + + <listitem> + <formalpara> + + <title>Data operation request</title> + + <para> + This request is of one of the types described in the + previous paragraph, and is represented as a + <literal>REQ</literal> message. + </para> + + </formalpara> + </listitem> + + <listitem> + <formalpara> + + <title>Response indicating success</title> + + <para> + This type of response is represented as a + <literal>CONF</literal> (confirmation) message, and is + usually accompanied by data. + </para> + + </formalpara> + </listitem> + + <listitem> + <formalpara> + + <title>Response indicating failure</title> + + <para> + This type of response is represented as a + <literal>REF</literal> (refusal) message. + </para> + + </formalpara> + </listitem> + + </itemizedlist> + </para> + + </formalpara> + + <para> + These are discussed on more detail in the next section, + <xref linkend="ndb-internals-ndb-protocol-messages"/>. + </para> + + </section> + + <section id="ndb-internals-ndb-protocol-messages"> + + <title>Messages and Message Structure</title> + + <para> + This section describes the <literal>NDB</literal> Protocol message + types and their structures. + </para> + + <formalpara> + + <title>Naming Conventions</title> + + <para> + Message names are constructed according to a simple pattern + which should be readily apparent from the discussion of request + and response types in the previous section. These are shown in + the following table: + + <informaltable> + <tgroup cols="4"> + <colspec colwidth="25*"/> + <colspec colwidth="25*"/> + <colspec colwidth="25*"/> + <colspec colwidth="25*"/> + <tbody> + <row> + <entry><emphasis role="bold">Operation Type</emphasis></entry> + <entry><emphasis role="bold">Request (<literal>REQ</literal>)</emphasis></entry> + <entry><emphasis role="bold">Response/Success + (<literal>CONF</literal>)</emphasis></entry> + <entry><emphasis role="bold">Response/Failure + (<literal>REF</literal>)</emphasis></entry> + </row> + <row> + <entry><emphasis role="bold">Primary Key Lookup + (<literal>TCKEY</literal>)</emphasis></entry> + <entry><literal>TCKEYREQ</literal></entry> + <entry><literal>TCKEYCONF</literal></entry> + <entry><literal>TCKEYREF</literal></entry> + </row> + <row> + <entry><emphasis role="bold">Unique Key Lookup + (<literal>TCINDX</literal>)</emphasis></entry> + <entry><literal>TCINDXREQ</literal></entry> + <entry><literal>TCINDXCONF</literal></entry> + <entry><literal>TCINDXREF</literal></entry> + </row> + <row> + <entry><emphasis role="bold">Table or Index Scan (SCANTAB)</emphasis></entry> + <entry><literal>SCANTABREQ</literal></entry> + <entry><literal>SCANTABCONF</literal></entry> + <entry><literal>SCANTABREF</literal></entry> + </row> + </tbody> + </tgroup> + </informaltable> + </para> + + </formalpara> + + <para> + Three additional types of messages are sometimes used in internode + communication. These are: + + <itemizedlist> + + <listitem> + <para> + A <literal>KEYINFO</literal> message contains information + about the key used in a <literal>TCKEYREQ</literal> or + <literal>TCINDXREQ</literal> message. It is employed when + the key data does not fit within the request message. + <literal>KEYINFO</literal> messages are also sent for index + scan operations in which bounds are employed. + </para> + </listitem> + + <listitem> + <para> + An <literal>ATTRINFO</literal> message contains non-key + attribute values which does not fit within a + <literal>TCKEYREQ</literal>, <literal>TCINDXREQ</literal>, + or <literal>SCANTABREQ</literal> message. It is used for: + + <itemizedlist> + + <listitem> + <para> + Supplying attribute values for inserts and updates + </para> + </listitem> + + <listitem> + <para> + Specifying which attributes to read for read + operations + </para> + </listitem> + + <listitem> + <para> + Specifying optional values to read for delete + operations + </para> + </listitem> + + </itemizedlist> + </para> + </listitem> + + <listitem> + <para> + A <literal>TRANSID_AI</literal> message contains the data + returned from a red operation — in other words, it + functions as a result set. + </para> + </listitem> + + </itemizedlist> + </para> + + <formalpara> + + <title><literal>KEYINFO</literal> structure</title> + + <para> + <remark role="TODO"> + [js] Ask about this... + </remark> + </para> + + </formalpara> + + <formalpara> + + <title><literal>ATTRINFO</literal> structure</title> + + <para> + An <literal>ATTRINFO</literal> message made up of the following + components: + + <itemizedlist> + + <listitem> + <para> + <remark role="TODO"> + [js] Ask about these... + </remark> + </para> + </listitem> + + </itemizedlist> + </para> + + </formalpara> + + <formalpara> + + <title><literal>TRANSID_AI</literal> structure</title> + + <para> + <remark role="TODO"> + [js] Ask about this... + </remark> + </para> + + </formalpara> + + </section> + + <section id="ndb-internals-ndb-protocol-signals-transactions"> + + <title>Signals and Transactions</title> + + <para></para> + + </section> + +</section> Modified: trunk/ndbapi/ndb-internals.xml =================================================================== --- trunk/ndbapi/ndb-internals.xml 2007-03-10 07:41:29 UTC (rev 5296) +++ trunk/ndbapi/ndb-internals.xml 2007-03-10 12:38:39 UTC (rev 5297) Changed blocks: 2, Lines Added: 256, Lines Deleted: 0; 8402 bytes @@ -884,6 +884,11 @@ <title>The NDB Protocol</title> + <para> + This section discusses the protocol used for communication between + data nodes and API nodes. + </para> + <programlisting> * Primary key (or unique key) operation @@ -947,6 +952,257 @@ TCRELEASECONF </programlisting> +<programlisting> +ndb is based on message passing. +a message between two end points in ndb is called a signal. + +a protocol = rules that specifies how/what messages can be passed + +a typical protocol is request/reply, +for these protocol the naming convention is (almost everywhere) +XXX-REQ - A request for something...possibly with optional extra signal specifying the request +XXX-REF - A reply saying that request didn't succeed +XXX-CONF - A reply saying that request succeeded + +--- + +General notation + +X Y? Z+ U* - means X + followed by 0 or 1 Y + followed by 1 or several Z + followed by 0 or several U + +(each of X Y Z U is a message/signal) + +--- + +TCKEY REQ/REF/CONF - Primary key lookup +TCINDX REQ/REF/CONF - Unique index lookup +SCANTAB REQ/REF/CONF - Table (or index) scan + +KEYINFO is information about KEY used for TCKEYREQ, TCINDXREQ, SCANTABREQ +KEYINFO can also be "piggy backed" onto "real" request sometimes... + +ATTRINFO is information about ATTRIBUTES (data) fro TCKEYREQ... +ATTRINFO can also be "piggy backed" onto "real" request sometimes +ATTRINFO (somewhat simplified) contains *real* data when doing insert/update/write + and list of attributes to read for read/scan + +TRANSID_AI is resultset from read...and contains actual *data* +</programlisting> + + <section id="ndb-internals-ndb-protocol-overview"> + + <title><literal>NDB</literal> Protocol Overview</title> + + <para> + MySQL Cluster data and API nodes communicate with one another by + passing messages to one another. The sending of a message from + one node and its reception by another node is referred to as a + <firstterm>signal</firstterm>; the <literal>NDB</literal> + Protocol is the set of rules governing the format of these + messages and the manner in which they are passed. + </para> + + <para> + An <literal>NDB</literal> message is typically either a + <firstterm>request</firstterm> or a + <firstterm>response</firstterm>. A request indicates that an API + node wants to perform an operation involving cluster data, such + as retrieval, insertion, updating, or deletion. A request is, + when necessary, accompanied by key or index information. The + response sent by a data node indicates whether or not the + request succeeded and, where appropriate, is accompanied by one + or more data messages. + </para> + + <formalpara> + + <title>Request operation types</title> + + <para> + Data request operations are of three principal types: + + <itemizedlist> + + <listitem> + <formalpara> + + <title>Primary key lookup operations</title> + + <para> + These are performed through the exchange of + <literal>TCKEY</literal> messages. + </para> + + </formalpara> + </listitem> + + <listitem> + <formalpara> + + <title>Unique key lookup operations</title> + + <para> + These are performed through the exchange of + <literal>TCINDX</literal> messages. + </para> + + </formalpara> + </listitem> + + <listitem> + <formalpara> + + <title>Table or index scan operations</title> + + <para> + These are performed through the exchange of + <literal>SCANTAB</literal> messages. + </para> + + </formalpara> + </listitem> + + </itemizedlist> + </para> + + </formalpara> + + <formalpara> + + <title>Message types</title> + + <para> + There are three types of messages: + + <itemizedlist> + + <listitem> + <formalpara> + + <title>Data operation request</title> + + <para> + This request is of one of the types described in the + previous paragraph, and is represented as a + <literal>REQ</literal> message. + </para> + + </formalpara> + </listitem> + + <listitem> + <formalpara> + + <title>Response indicating success</title> + + <para> + This type of response is represented as a + <literal>CONF</literal> (confirmation) message, and is + usually accompanied by data. + </para> + + </formalpara> + </listitem> + + <listitem> + <formalpara> + + <title>Response indicating failure</title> + + <para> + This type of response is represented as a + <literal>REF</literal> (refusal) message. + </para> + + </formalpara> + </listitem> + + </itemizedlist> + </para> + + </formalpara> + + <para> + These are discussed on more detail in the next section, + <xref linkend="ndb-internals-ndb-protocol-messages"/>. + </para> + + </section> + + <section id="ndb-internals-ndb-protocol-messages"> + + <title>Messages and Message Structure</title> + + <para> + This section describes the <literal>NDB</literal> Protocol + message types and their structures. + </para> + + <formalpara> + + <title>Naming Conventions</title> + + <para> + Message names are constructed according to a simple pattern + which should be readily apparent from the discussion of + request and response types in the previous section. These are + shown in the following table: + + <informaltable> + <tgroup cols="4"> + <colspec colwidth="24*" colsep="4*"/> + <colspec colwidth="24*"/> + <colspec colwidth="24*"/> + <colspec colwidth="24*"/> + <tbody> + <row rowsep="4*"> + <entry><emphasis role="bold">Operation Type</emphasis></entry> + <entry><emphasis role="bold">Request (<literal>REQ</literal>)</emphasis></entry> + <entry><emphasis role="bold">Response/Success + (<literal>CONF</literal>)</emphasis></entry> + <entry><emphasis role="bold">Response/Failure + (<literal>REF</literal>)</emphasis></entry> + </row> + <row> + <entry><emphasis role="bold">Primary Key Lookup + (<literal>TCKEY</literal>)</emphasis></entry> + <entry><literal>TCKEYREQ</literal></entry> + <entry><literal>TCKEYCONF</literal></entry> + <entry><literal>TCKEYREF</literal></entry> + </row> + <row> + <entry><emphasis role="bold">Unique Key Lookup + (<literal>TCINDX</literal>)</emphasis></entry> + <entry><literal>TCINDXREQ</literal></entry> + <entry><literal>TCINDXCONF</literal></entry> + <entry><literal>TCINDXREF</literal></entry> + </row> + <row> + <entry><emphasis role="bold">Table or Index Scan (SCANTAB)</emphasis></entry> + <entry><literal>SCANTABREQ</literal></entry> + <entry><literal>SCANTABCONF</literal></entry> + <entry><literal>SCANTABREF</literal></entry> + </row> + </tbody> + </tgroup> + </informaltable> + </para> + + </formalpara> + + </section> + + <section id="ndb-internals-ndb-protocol-signals-transactions"> + + <title>Signals and Transactions</title> + + <para></para> + + </section> + </section> </chapter>
| Thread | ||
|---|---|---|
| • svn commit - mysqldoc@docsrva: r5297 - trunk/ndbapi | jon | 10 Mar |
© 1995-2008 MySQL AB. All rights reserved.
Page generated in 0.665 sec. using MySQL 5.1.14-beta-log