MySQL NDB Cluster API Developer Guide
This section describes concepts basic to the NDB Cluster MGM API.
Each MGM API function needs a management server handle of type
NdbMgmHandle
. This handle is created by
calling the function
ndb_mgm_create_handle()
and
freed by calling
ndb_mgm_destroy_handle()
.
See ndb_mgm_create_handle(), and ndb_mgm_destroy_handle(), for more information about these two functions.
You should not share an NdbMgmHandle
between threads. While it is possible to do so (if you
implement your own locks), this is not recommended; each
thread should use its own management server handle.
A function can return any of the following:
An integer value, with a value of -1
indicating an error.
A nonconstant pointer value. A NULL
value
indicates an error; otherwise, the return value must be
freed by the programmer.
A constant pointer value, with a NULL
value indicating an error. The returned value should not be
freed.
Error conditions can be identified by using the appropriate
error-reporting functions
ndb_mgm_get_latest_error()
and
ndb_mgm_error()
.
Here is an example using the MGM API (without error handling for brevity's sake):
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);
Data nodes and management servers both 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
ndb_mgm_listen_event()
. Each
log event belongs to a category
ndb_mgm_event_category
) and has
a severity
ndb_mgm_event_severity
associated with it. Each log event also has a level (0-15)
associated with it.
Which log events that come out is controlled with
ndb_mgm_listen_event()
,
ndb_mgm_set_clusterlog_loglevel()
,
and
ndb_mgm_set_clusterlog_severity_filter()
.
This is an example showing how to listen to events related to backup:
int filter[] = { 15, NDB_MGM_EVENT_CATEGORY_BACKUP, 0 }; int fd = ndb_mgm_listen_event(handle, filter);
Handling of structured log events in the MGM API involves the following steps:
Create an NdbLogEventHandle
using
ndb_mgm_create_logevent_handle()
.
Wait for and store log events using
ndb_logevent_get_next()
.
The log event data is available in the structure
ndb_logevent
. The data
which is specific to a particular event is stored in a union
between structures; use
ndb_logevent::type
to decide which
structure is valid.
The following sample code demonstrates listening to events related to backups:
int filter[] = { 15, NDB_MGM_EVENT_CATEGORY_BACKUP, 0 }; NdbLogEventHandle 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; }
For more information, see Section 3.2.1, “Log Event Functions”.
Available log event types are listed in
The Ndb_logevent_type Type, as well as in the file
/storage/ndb/include/mgmapi/ndb_logevent.h
in the NDB Cluster sources.