← Back to branch summary

~ubuntu-branches/ubuntu/precise/mysql-5.1/precise

« back to all changes in this revision

Viewing changes to storage/ndb/include/ndbapi/NdbEventOperation.hpp

  • Committer: Bazaar Package Importer
  • Author(s): Norbert Tretkowski
  • Date: 2010-03-17 14:56:02 UTC
  • Revision ID: james.westby@ubuntu.com-20100317145602-x7e30l1b2sb5s6w6
Tags: upstream-5.1.45
Import upstream version 5.1.45

Show diffs side-by-side

added added

removed removed

Lines of Context:
storage/ndb/include/ndbapi/NdbEventOperation.hpp
 
1
/* Copyright (C) 2003 MySQL AB
 
2
 
 
3
   This program is free software; you can redistribute it and/or modify
 
4
   it under the terms of the GNU General Public License as published by
 
5
   the Free Software Foundation; version 2 of the License.
 
6
 
 
7
   This program is distributed in the hope that it will be useful,
 
8
   but WITHOUT ANY WARRANTY; without even the implied warranty of
 
9
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 
10
   GNU General Public License for more details.
 
11
 
 
12
   You should have received a copy of the GNU General Public License
 
13
   along with this program; if not, write to the Free Software
 
14
   Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA */
 
15
 
 
16
#ifndef NdbEventOperation_H
 
17
#define NdbEventOperation_H
 
18
 
 
19
class NdbGlobalEventBuffer;
 
20
class NdbEventOperationImpl;
 
21
 
 
22
/**
 
23
 * @class NdbEventOperation
 
24
 * @brief Class of operations for getting change events from database.  
 
25
 *
 
26
 * Brief description on how to work with events:
 
27
 *
 
28
 * - An event, represented by an NdbDictionary::Event, i created in the 
 
29
 *   Database through
 
30
 *   NdbDictionary::Dictionary::createEvent() (note that this can be done 
 
31
 *   by any application or thread and not necessarily by the "listener")
 
32
 * - To listen to events, an NdbEventOperation object is instantiated by 
 
33
 *   Ndb::createEventOperation()
 
34
 * - execute() starts the event flow. Use Ndb::pollEvents() to wait
 
35
 *   for an event to occur.  Use Ndb::nextEvent() to iterate
 
36
 *   through the events that have occured.
 
37
 * - The instance is removed by Ndb::dropEventOperation()
 
38
 *
 
39
 * For more info see:
 
40
 * @ref ndbapi_event.cpp
 
41
 *
 
42
 * Known limitations:
 
43
 *
 
44
 * - Maximum number of active NdbEventOperations are now set at compile time.
 
45
 * Today 100.  This will become a configuration parameter later.
 
46
 * - Maximum number of NdbEventOperations tied to same event are maximum 16
 
47
 * per process.
 
48
 *
 
49
 * Known issues:
 
50
 *
 
51
 * - When several NdbEventOperation's are tied to the same event in the same
 
52
 * process they will share the circular buffer. The BufferLength will then
 
53
 * be the same for all and decided by the first NdbEventOperation 
 
54
 * instantiation. Just make sure to instantiate the "largest" one first.
 
55
 * - Today all events INSERT/DELETE/UPDATE and all changed attributes are
 
56
 * sent to the API, even if only specific attributes have been specified.
 
57
 * These are however hidden from the user and only relevant data is shown
 
58
 * after  Ndb::nextEvent().
 
59
 * - "False" exits from Ndb::pollEvents() may occur and thus
 
60
 * the subsequent Ndb::nextEvent() will return NULL,
 
61
 * since there was no available data. Just do Ndb::pollEvents() again.
 
62
 * - Event code does not check table schema version. Make sure to drop events
 
63
 * after table is dropped. Will be fixed in later
 
64
 * versions.
 
65
 * - If a node failure has occured not all events will be recieved
 
66
 * anymore. Drop NdbEventOperation and Create again after nodes are up
 
67
 * again. Will be fixed in later versions.
 
68
 *
 
69
 * Test status:
 
70
 *
 
71
 * - Tests have been run on 1-node and 2-node systems
 
72
 *
 
73
 * Useful API programs:
 
74
 *
 
75
 * - ndb_select_all -d sys 'NDB$EVENTS_0'
 
76
 * shows contents in the system table containing created events.
 
77
 *
 
78
 * @note this is an inteface to viewing events that is subject to change
 
79
 */
 
80
class NdbEventOperation {
 
81
public:
 
82
  /**
 
83
   * State of the NdbEventOperation object
 
84
   */
 
85
  enum State {
 
86
    EO_CREATED,   ///< Created but execute() not called
 
87
    EO_EXECUTING, ///< execute() called
 
88
    EO_DROPPED,   ///< Waiting to be deleted, Object unusable.
 
89
    EO_ERROR      ///< An error has occurred. Object unusable.
 
90
  };
 
91
  /**
 
92
   * Retrieve current state of the NdbEventOperation object
 
93
   */
 
94
  State getState();
 
95
  /**
 
96
   * See NdbDictionary::Event.  Default is false.
 
97
   */
 
98
  void mergeEvents(bool flag);
 
99
 
 
100
  /**
 
101
   * Activates the NdbEventOperation to start receiving events. The
 
102
   * changed attribute values may be retrieved after Ndb::nextEvent() 
 
103
   * has returned not NULL. The getValue() methods must be called
 
104
   * prior to execute().
 
105
   *
 
106
   * @return 0 if successful otherwise -1.
 
107
   */
 
108
  int execute();
 
109
 
 
110
  /**
 
111
   * Defines a retrieval operation of an attribute value.
 
112
   * The NDB API allocate memory for the NdbRecAttr object that
 
113
   * will hold the returned attribute value. 
 
114
   *
 
115
   * @note Note that it is the applications responsibility
 
116
   *       to allocate enough memory for aValue (if non-NULL).
 
117
   *       The buffer aValue supplied by the application must be
 
118
   *       aligned appropriately.  The buffer is used directly
 
119
   *       (avoiding a copy penalty) only if it is aligned on a
 
120
   *       4-byte boundary and the attribute size in bytes
 
121
   *       (i.e. NdbRecAttr::attrSize() times NdbRecAttr::arraySize() is
 
122
   *       a multiple of 4).
 
123
   *
 
124
   * @note There are two versions, getValue() and
 
125
   *       getPreValue() for retrieving the current and
 
126
   *       previous value repectively.
 
127
   *
 
128
   * @note This method does not fetch the attribute value from 
 
129
   *       the database!  The NdbRecAttr object returned by this method 
 
130
   *       is <em>not</em> readable/printable before the 
 
131
   *       execute() has been made and
 
132
   *       Ndb::nextEvent() has returned not NULL.
 
133
   *       If a specific attribute has not changed the corresponding 
 
134
   *       NdbRecAttr will be in state UNDEFINED.  This is checked by 
 
135
   *       NdbRecAttr::isNULL() which then returns -1.
 
136
   *
 
137
   * @param anAttrName  Attribute name 
 
138
   * @param aValue      If this is non-NULL, then the attribute value 
 
139
   *                    will be returned in this parameter.<br>
 
140
   *                    If NULL, then the attribute value will only 
 
141
   *                    be stored in the returned NdbRecAttr object.
 
142
   * @return            An NdbRecAttr object to hold the value of 
 
143
   *                    the attribute, or a NULL pointer 
 
144
   *                    (indicating error).
 
145
   */
 
146
  NdbRecAttr *getValue(const char *anAttrName, char *aValue = 0);
 
147
  /**
 
148
   * See getValue().
 
149
   */
 
150
  NdbRecAttr *getPreValue(const char *anAttrName, char *aValue = 0);
 
151
 
 
152
  /**
 
153
   * These methods replace getValue/getPreValue for blobs.  Each
 
154
   * method creates a blob handle NdbBlob.  The handle supports only
 
155
   * read operations.  See NdbBlob.
 
156
   */
 
157
  NdbBlob* getBlobHandle(const char *anAttrName);
 
158
  NdbBlob* getPreBlobHandle(const char *anAttrName);
 
159
 
 
160
  int isOverrun() const;
 
161
 
 
162
  /**
 
163
   * In the current implementation a nodefailiure may cause loss of events,
 
164
   * in which case isConsistent() will return false
 
165
   */
 
166
  bool isConsistent() const;
 
167
 
 
168
  /**
 
169
   * Query for occured event type.
 
170
   *
 
171
   * @note Only valid after Ndb::nextEvent() has been called and 
 
172
   * returned a not NULL value
 
173
   *
 
174
   * @return type of event
 
175
   */
 
176
  NdbDictionary::Event::TableEvent getEventType() const;
 
177
 
 
178
  /**
 
179
   * Check if table name has changed, for event TE_ALTER
 
180
   */
 
181
  bool tableNameChanged() const;
 
182
 
 
183
  /**
 
184
   * Check if table frm has changed, for event TE_ALTER
 
185
   */
 
186
  bool tableFrmChanged() const;
 
187
 
 
188
  /**
 
189
   * Check if table fragmentation has changed, for event TE_ALTER
 
190
   */
 
191
  bool tableFragmentationChanged() const;
 
192
 
 
193
  /**
 
194
   * Check if table range partition list name has changed, for event TE_ALTER
 
195
   */
 
196
  bool tableRangeListChanged() const;
 
197
 
 
198
  /**
 
199
   * Retrieve the GCI of the latest retrieved event
 
200
   *
 
201
   * @return GCI number
 
202
   */
 
203
  Uint64 getGCI() const;
 
204
 
 
205
  /**
 
206
   * Retrieve the AnyValue of the latest retrieved event
 
207
   *
 
208
   * @return AnyValue
 
209
   */
 
210
  Uint32 getAnyValue() const;
 
211
 
 
212
  /**
 
213
   * Retrieve the complete GCI in the cluster (not necessarily
 
214
   * associated with an event)
 
215
   *
 
216
   * @return GCI number
 
217
   */
 
218
  Uint64 getLatestGCI() const;
 
219
 
 
220
  /**
 
221
   * Get the latest error
 
222
   *
 
223
   * @return   Error object.
 
224
   */                        
 
225
  const struct NdbError & getNdbError() const;
 
226
 
 
227
#ifndef DOXYGEN_SHOULD_SKIP_INTERNAL
 
228
  /** these are subject to change at any time */
 
229
  const NdbDictionary::Table* getTable() const;
 
230
  const NdbDictionary::Event *getEvent() const;
 
231
  const NdbRecAttr *getFirstPkAttr() const;
 
232
  const NdbRecAttr *getFirstPkPreAttr() const;
 
233
  const NdbRecAttr *getFirstDataAttr() const;
 
234
  const NdbRecAttr *getFirstDataPreAttr() const;
 
235
 
 
236
//  bool validateTable(NdbDictionary::Table &table) const;
 
237
 
 
238
  void setCustomData(void * data);
 
239
  void * getCustomData() const;
 
240
 
 
241
  void clearError();
 
242
  int hasError() const;
 
243
 
 
244
  int getReqNodeId() const;
 
245
  int getNdbdNodeId() const;
 
246
#endif
 
247
 
 
248
#ifndef DOXYGEN_SHOULD_SKIP_INTERNAL
 
249
  /*
 
250
   *
 
251
   */
 
252
  void print();
 
253
#endif
 
254
 
 
255
private:
 
256
#ifndef DOXYGEN_SHOULD_SKIP_INTERNAL
 
257
  friend class NdbEventOperationImpl;
 
258
  friend class NdbEventBuffer;
 
259
#endif
 
260
  NdbEventOperation(Ndb *theNdb, const char* eventName);
 
261
  ~NdbEventOperation();
 
262
  class NdbEventOperationImpl &m_impl;
 
263
  NdbEventOperation(NdbEventOperationImpl& impl);
 
264
};
 
265
 
 
266
typedef void (* NdbEventCallback)(NdbEventOperation*, Ndb*, void*);
 
267
#endif