| List: | Commits | « Previous MessageNext Message » | |
| From: | jon | Date: | April 26 2006 9:57am |
| Subject: | svn commit - mysqldoc@docsrva: r1942 - trunk/ndbapi | ||
| View as plain text | |||
Author: jstephens Date: 2006-04-26 09:57:55 +0200 (Wed, 26 Apr 2006) New Revision: 1942 Log: More DocBook-ification of existing content; added MGM API General Concepts to new version. Converted *Note*:/*Important*: to <note/>/<important/> elements. Cut NDB class/member quickref sections from Overview. (Redundant - we've already got the complete class/member listings in their own chapter, there's a shortlist in the NDB Overview, and they'll be listed in the generated Index as well). Misc. edits/fixes (wording/spelling/etc.). Modified: trunk/ndbapi/mgm-api.xml trunk/ndbapi/overview.xml Modified: trunk/ndbapi/mgm-api.xml =================================================================== --- trunk/ndbapi/mgm-api.xml 2006-04-26 02:55:27 UTC (rev 1941) +++ trunk/ndbapi/mgm-api.xml 2006-04-26 07:57:55 UTC (rev 1942) @@ -12,39 +12,232 @@ <abstract> <para> - Discusses the MySQL Cluster Management API, a C language API that - is used for administrative tasks such as starting and stopping - Cluster nodes, backups, and logging. Covers MGM concepts, - programming constructs, and event types. + This chapter discusses the MySQL Cluster Management API, a C + language API that is used for administrative tasks such as + starting and stopping Cluster nodes, backups, and logging. Covers + MGM concepts, programming constructs, and event types. </para> </abstract> - <section id="mgm-api-functions"> + <section id="mgm-api-concepts"> - <title>MGM C API Function Listing</title> + <title>General Concepts</title> - <abstract> + <para> + Each MGM API function needs a management server handle of type + <literal>NdbMgmHandle</literal>. This handle is created by calling + the function <literal>ndb_mgm_create_handle()</literal> and freed + by calling <literal>ndb_mgm_destroy_handle()</literal>. + </para> + <important> + <para> - Covers the structures and functions used in the MGM API. - Listings grouped by purpose or use. + You should not share an <literal>NdbMgmHandle</literal> between + threads. While it is possible to do so (if you implement your + own locks), this is not recommended, and each thread should use + its own management server handle. </para> - </abstract> + </important> + <para> + A function can return any of the following: + </para> + + <itemizedlist> + + <listitem> + <para> + An integer value, with a value of <literal>-1</literal> + indicating an error. + </para> + </listitem> + + <listitem> + <para> + A non-constant pointer value. A <literal>NULL</literal> value + indicates an error; otherwise, the return value must be freed + by the programmer. + </para> + </listitem> + + <listitem> + <para> + A constant pointer value, with a <literal>NULL</literal> value + indicating an error. The returned value should not be freed. + </para> + </listitem> + + </itemizedlist> + + <para> + Error conditions can be identified by using the appropriate + error-reporting functions + <literal>ndb_mgm_get_latest_error()</literal> and + <literal>ndb_mgm_error()</literal>. + </para> + + <para> + Here is an example using the MGM API (without error handling for + brevity's sake): + </para> + +<programlisting> +NdbMgmHandle handle= ndb_mgm_create_handle(); +ndb_mgm_connect(handle,0,0,0); +struct ndb_mgm_cluster_state *state= ndb_mgm_get_status(handle); +for(int i=0; i > state->no_of_nodes; i++) +{ + struct ndb_mgm_node_state *node_state= &state->node_states[i]; + printf("node with ID=%d ", node_state->node_id); + + if(node_state->version != 0) + printf("connected\n"); + else + printf("not connected\n"); +} +free((void*)state); +ndb_mgm_destroy_handle(&handle); +</programlisting> + <section id="mgm-api-log-events"> <title>Working with Log Events</title> -<!-- <abstract> --> + <para> + Data nodes and management servers regularly and on specific + occasions report on various log events that occur in the + cluster. These log events are written to the cluster log. + Optionally an MGM API client may listen to these events using + the method <literal>ndb_mgm_listen_event()</literal>. Each log + event belongs to a category + <literal>ndb_mgm_event_category</literal>) and has a severity + <literal>ndb_mgm_event_severity</literal> associated with it. + Each log event also has a level (0-15) associated with it. + </para> - <para></para> + <para> + Which log events that come out is controlled with + <literal>ndb_mgm_listen_event()</literal>, + <literal>ndb_mgm_set_clusterlog_loglevel()</literal>, and + <literal>ndb_mgm_set_clusterlog_severity_filter()</literal>. + </para> -<!-- </abstract> --> + <para> + This is an example showing how to listen to events related to + backup: + </para> +<programlisting> +int filter[] = { 15, NDB_MGM_EVENT_CATEGORY_BACKUP, 0 }; +int fd = ndb_mgm_listen_event(handle, filter); +</programlisting> + </section> + <section id="mgm-api-structured-log-events"> + + <title>Structured Log Events</title> + + <para> + The following steps are involved: + </para> + + <orderedlist> + + <listitem> + <para> + Create an <literal>NdbEventLogHandle</literal> using + <literal>ndb_mgm_create_logevent_handle()</literal>. + </para> + </listitem> + + <listitem> + <para> + Wait for and store log events using + <literal>ndb_logevent_get_next()</literal>. + </para> + </listitem> + + <listitem> + <para> + The log event data is available in the structure + <literal>ndb_logevent</literal>. The data which is specific + to a particular event is stored in a union between + structures; use <literal>ndb_logevent::type</literal> to + decide which structure is valid. + </para> + </listitem> + + </orderedlist> + + <para> + The following sample code demonstrates listening to events + related to backups: + </para> + + <remark role="todo"> + [js] Need to explain this... + </remark> + +<programlisting> +int filter[] = { 15, NDB_MGM_EVENT_CATEGORY_BACKUP, 0 }; +NdbEventLogHandle le_handle= ndb_mgm_create_logevent_handle(handle, filter); +struct ndb_logevent le; +int r= ndb_logevent_get_next(le_handle, &le, 0); +if(r < 0) + /* error */ +else if(r == 0) + /* no event */ + +switch(le.type) +{ + case NDB_LE_BackupStarted: + ... le.BackupStarted.starting_node; + ... le.BackupStarted.backup_id; + break; + case NDB_LE_BackupFailedToStart: + ... le.BackupFailedToStart.error; + break; + case NDB_LE_BackupCompleted: + ... le.BackupCompleted.stop_gci; + break; + case NDB_LE_BackupAborted: + ... le.BackupStarted.backup_id; + break; + default: + break; +} +</programlisting> + + <note> + + <para> + Available log events are listed in + <filename>/storage/ndb/include/mgmapi/ndb_logevent.h</filename>. + </para> + + </note> + + </section> + + </section> + + <section id="mgm-api-functions"> + + <title>MGM C API Function Listing</title> + + <abstract> + + <para> + This section covers the structures and functions used in the MGM + API. Listings are grouped by purpose or use. + </para> + + </abstract> + <section id="mgm-api-error-handling"> <title>Error-Handling Functions</title> Modified: trunk/ndbapi/overview.xml =================================================================== --- trunk/ndbapi/overview.xml 2006-04-26 02:55:27 UTC (rev 1941) +++ trunk/ndbapi/overview.xml 2006-04-26 07:57:55 UTC (rev 1942) @@ -80,11 +80,9 @@ <literal>NdbOperation</literal> classes. These model (respectively) database connections, cluster connections, transactions, and operations. These classes and their subclasses - are listed in <xref linkend="overview-ndb-class-quickref"/>, and - in <xref linkend="overview-ndb-class-members-quickref"/>; - complete definitions and class signatures may be found in - <xref linkend="ndb-classes"/>. Error conditions in the NDB API - are handled using <literal>NdbError</literal>, described in + are listed in <xref linkend="ndb-classes"/>. Error conditions in + the NDB API are handled using <literal>NdbError</literal>, a + structure which is described in <xref linkend="errors-ndberror-struct"/>. </para> @@ -346,6 +344,10 @@ fundamental classes: </para> + <remark role="todo"> + [js] Provide links to detailed class listings. + </remark> + <itemizedlist> <listitem> @@ -1195,16 +1197,20 @@ </orderedlist> - <para> - <emphasis role="bold">Important</emphasis>: The update or - delete is not actually performed until the next call to - <literal>NdbTransaction::execute()</literal> is made, just - as with single row operations. - <literal>NdbTransaction::execute()</literal> also must be - called before any locks are released; for more information, - see <xref linkend="overview-scans-lock-handling"/>. - </para> + <important> + <para> + The update or delete is not actually performed until the + next call to <literal>NdbTransaction::execute()</literal> + is made, just as with single row operations. + <literal>NdbTransaction::execute()</literal> also must be + called before any locks are released; for more + information, see + <xref linkend="overview-scans-lock-handling"/>. + </para> + + </important> + <para> <emphasis role="bold">Features Specific to Index Scans</emphasis> @@ -1414,14 +1420,18 @@ find out what really happened. </para> - <para> - <emphasis role="bold">Important</emphasis>: Errors can occur - even when a commit is reported as successful. In order to - handle such situations, the NDB API provides an additional - <literal>NdbTransaction::commitStatus()</literal> method to - check the transactions's commit status. - </para> + <important> + <para> + Errors can occur even when a commit is reported as + successful. In order to handle such situations, the NDB + API provides an additional + <literal>NdbTransaction::commitStatus()</literal> method + to check the transactions's commit status. + </para> + + </important> + </section> </section> @@ -1706,24 +1716,25 @@ </abstract> <para> - At the time a transaction is sent using - NdbTransaction::execute(), the transaction is in reality not - immediately transfered to the NDB Kernel. Instead, the - transaction is kept in a special send list (buffer) in the Ndb - object to which they belong. The adaptive send algorithm decides - when transactions should actually be transferred to the NDB - kernel. + When transactions are sent using + <literal>NdbTransaction::execute()</literal>, they are not + immediately transfered to the NDB Kernel. Instead, transactions + are kept in a special send list (buffer) in the + <literal>Ndb</literal> object to which they belong. The adaptive + send algorithm decides when transactions should actually be + transferred to the NDB kernel. </para> <para> The NDB API is designed as a multi-threaded interface, and so it is often desirable to transfer database operations from more - than one thread at a time. The NDB API keeps track of which Ndb - objects are active in transferring information to the NDB kernel - and the expected number of threads to interact with the NDB - kernel. Note that a given instance of Ndb should be used in at - most one thread; different threads should not share the same Ndb - object. + than one thread at a time. The NDB API keeps track of which + <literal>Ndb</literal> objects are active in transferring + information to the NDB kernel and the expected number of threads + to interact with the NDB kernel. Note that a given instance of + <literal>Ndb</literal> should be used in at most one thread; + different threads should <emphasis>not</emphasis> share the same + <literal>Ndb</literal> object. </para> <para> @@ -1740,9 +1751,10 @@ size is implementation-dependent and may change between MySQL Cluster releases. When TCP/IP is the transporter, the buffer size is usually around 64 KB; when using OSE/Delta it - is usually less than 2000 bytes. Since each Ndb object - provides a single buffer per storage node, the notion of a - <quote>full</quote> buffer is local to each storage node. + is usually less than 2000 bytes. Since each + <literal>Ndb</literal> object provides a single buffer per + storage node, the notion of a <quote>full</quote> buffer is + local to each storage node. </para> </listitem> @@ -1770,10 +1782,11 @@ <listitem> <para> For methods that are affected by the adaptive send alorithm - (such as NdbTransaction::execute()), there is a force - parameter that overrides its default behaviour in this - regard and forces immediate transmission to all nodes. See - the inidvidual NDB API class listings for more information. + (such as <literal>NdbTransaction::execute()</literal>), + there is a <replaceable>force</replaceable> parameter that + overrides its default behaviour in this regard and forces + immediate transmission to all nodes. See the inidvidual NDB + API class listings for more information. </para> </listitem> @@ -1790,34 +1803,6 @@ </section> - <section id="overview-ndb-class-quickref"> - - <title>NDB Class Listing</title> - - <abstract> - - <para> - Quick reference of the NDB classes. - </para> - - </abstract> - - </section> - - <section id="overview-ndb-class-members-quickref"> - - <title>NDB Class Members</title> - - <abstract> - - <para> - Quick reference for locating NDB class members. - </para> - - </abstract> - - </section> - </section> </chapter>
| Thread | ||
|---|---|---|
| • svn commit - mysqldoc@docsrva: r1942 - trunk/ndbapi | jon | 26 Apr |
© 1995-2008 MySQL AB, 2008-2009 Sun Microsystems, Inc.
Page generated in 0.492 sec. using MySQL 5.1.14-beta-log