1/* Copyright (c) 2008, 2010, Oracle and/or its affiliates. All rights reserved.
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 Foundation,
14 51 Franklin Street, Suite 500, Boston, MA 02110-1335 USA */
15
16#ifndef REPLICATION_H
17#define REPLICATION_H
18
19/***************************************************************************
20 NOTE: plugin locking.
21
22 The plugin is locked on Binlog_transmit_observer::transmit_start and is
23 unlocked after Binlog_transmit_observer::transmit_stop. All other
24 master observable events happen between these two and don't lock the
25 plugin at all.
26
27 Also a plugin is locked on Binlog_relay_IO_observer::thread_start
28 and unlocked after Binlog_relay_IO_observer::thread_stop.
29***************************************************************************/
30
31#include <mysql.h>
32
33typedef struct st_mysql MYSQL;
34
35#ifdef __cplusplus
36extern "C" {
37#endif
38
39/**
40 Transaction observer flags.
41*/
42enum Trans_flags {
43 /** Transaction is a real transaction */
44 TRANS_IS_REAL_TRANS = 1
45};
46
47/**
48 Transaction observer parameter
49*/
50typedef struct Trans_param {
51 uint32 server_id;
52 uint32 flags;
53
54 /*
55 The latest binary log file name and position written by current
56 transaction, if binary log is disabled or no log event has been
57 written into binary log file by current transaction (events
58 written into transaction log cache are not counted), these two
59 member will be zero.
60 */
61 const char *log_file;
62 my_off_t log_pos;
63} Trans_param;
64
65/**
66 Observes and extends transaction execution
67*/
68typedef struct Trans_observer {
69 uint32 len;
70
71 /**
72 This callback is called after transaction commit
73
74 This callback is called right after commit to storage engines for
75 transactional tables.
76
77 For non-transactional tables, this is called at the end of the
78 statement, before sending statement status, if the statement
79 succeeded.
80
81 @note The return value is currently ignored by the server.
82 @note This hook is called wo/ any global mutex held
83
84 @param param The parameter for transaction observers
85
86 @retval 0 Sucess
87 @retval 1 Failure
88 */
89 int (*after_commit)(Trans_param *param);
90
91 /**
92 This callback is called after transaction rollback
93
94 This callback is called right after rollback to storage engines
95 for transactional tables.
96
97 For non-transactional tables, this is called at the end of the
98 statement, before sending statement status, if the statement
99 failed.
100
101 @note The return value is currently ignored by the server.
102
103 @param param The parameter for transaction observers
104
105 @note This hook is called wo/ any global mutex held
106
107 @retval 0 Sucess
108 @retval 1 Failure
109 */
110 int (*after_rollback)(Trans_param *param);
111} Trans_observer;
112
113/**
114 Binlog storage flags
115*/
116enum Binlog_storage_flags {
117 /** Binary log was sync:ed */
118 BINLOG_STORAGE_IS_SYNCED = 1,
119
120 /** First(or alone) in a group commit */
121 BINLOG_GROUP_COMMIT_LEADER = 2,
122
123 /** Last(or alone) in a group commit */
124 BINLOG_GROUP_COMMIT_TRAILER = 4
125};
126
127/**
128 Binlog storage observer parameters
129 */
130typedef struct Binlog_storage_param {
131 uint32 server_id;
132} Binlog_storage_param;
133
134/**
135 Observe binlog logging storage
136*/
137typedef struct Binlog_storage_observer {
138 uint32 len;
139
140 /**
141 This callback is called after binlog has been flushed
142
143 This callback is called after cached events have been flushed to
144 binary log file. Whether the binary log file is synchronized to
145 disk is indicated by the bit BINLOG_STORAGE_IS_SYNCED in @a flags.
146
147 @note: this hook is called with LOCK_log mutex held
148
149 @param param Observer common parameter
150 @param log_file Binlog file name been updated
151 @param log_pos Binlog position after update
152 @param flags flags for binlog storage
153
154 @retval 0 Sucess
155 @retval 1 Failure
156 */
157 int (*after_flush)(Binlog_storage_param *param,
158 const char *log_file, my_off_t log_pos,
159 uint32 flags);
160
161 /**
162 This callback is called after binlog has been synced
163
164 This callback is called after events flushed to disk has been sync:ed
165 ("group committed").
166
167 @note: this hook is called with LOCK_after_binlog_sync mutex held
168
169 @param param Observer common parameter
170 @param log_file Binlog file name been updated
171 @param log_pos Binlog position after update
172 @param flags flags for binlog storage
173
174 @retval 0 Sucess
175 @retval 1 Failure
176 */
177 int (*after_sync)(Binlog_storage_param *param,
178 const char *log_file, my_off_t log_pos,
179 uint32 flags);
180} Binlog_storage_observer;
181
182/**
183 Replication binlog transmitter (binlog dump) observer parameter.
184*/
185typedef struct Binlog_transmit_param {
186 uint32 server_id;
187 uint32 flags;
188} Binlog_transmit_param;
189
190/**
191 Observe and extends the binlog dumping thread.
192*/
193typedef struct Binlog_transmit_observer {
194 uint32 len;
195
196 /**
197 This callback is called when binlog dumping starts
198
199
200 @param param Observer common parameter
201 @param log_file Binlog file name to transmit from
202 @param log_pos Binlog position to transmit from
203
204 @retval 0 Sucess
205 @retval 1 Failure
206 */
207 int (*transmit_start)(Binlog_transmit_param *param,
208 const char *log_file, my_off_t log_pos);
209
210 /**
211 This callback is called when binlog dumping stops
212
213 @param param Observer common parameter
214
215 @retval 0 Sucess
216 @retval 1 Failure
217 */
218 int (*transmit_stop)(Binlog_transmit_param *param);
219
220 /**
221 This callback is called to reserve bytes in packet header for event transmission
222
223 This callback is called when resetting transmit packet header to
224 reserve bytes for this observer in packet header.
225
226 The @a header buffer is allocated by the server code, and @a size
227 is the size of the header buffer. Each observer can only reserve
228 a maximum size of @a size in the header.
229
230 @param param Observer common parameter
231 @param header Pointer of the header buffer
232 @param size Size of the header buffer
233 @param len Header length reserved by this observer
234
235 @retval 0 Sucess
236 @retval 1 Failure
237 */
238 int (*reserve_header)(Binlog_transmit_param *param,
239 unsigned char *header,
240 unsigned long size,
241 unsigned long *len);
242
243 /**
244 This callback is called before sending an event packet to slave
245
246 @param param Observer common parameter
247 @param packet Binlog event packet to send
248 @param len Length of the event packet
249 @param log_file Binlog file name of the event packet to send
250 @param log_pos Binlog position of the event packet to send
251
252 @retval 0 Sucess
253 @retval 1 Failure
254 */
255 int (*before_send_event)(Binlog_transmit_param *param,
256 unsigned char *packet, unsigned long len,
257 const char *log_file, my_off_t log_pos );
258
259 /**
260 This callback is called after sending an event packet to slave
261
262 @param param Observer common parameter
263 @param event_buf Binlog event packet buffer sent
264 @param len length of the event packet buffer
265
266 @retval 0 Sucess
267 @retval 1 Failure
268 */
269 int (*after_send_event)(Binlog_transmit_param *param,
270 const char *event_buf, unsigned long len);
271
272 /**
273 This callback is called after resetting master status
274
275 This is called when executing the command RESET MASTER, and is
276 used to reset status variables added by observers.
277
278 @param param Observer common parameter
279
280 @retval 0 Sucess
281 @retval 1 Failure
282 */
283 int (*after_reset_master)(Binlog_transmit_param *param);
284} Binlog_transmit_observer;
285
286/**
287 Binlog relay IO flags
288*/
289enum Binlog_relay_IO_flags {
290 /** Binary relay log was sync:ed */
291 BINLOG_RELAY_IS_SYNCED = 1
292};
293
294
295/**
296 Replication binlog relay IO observer parameter
297*/
298typedef struct Binlog_relay_IO_param {
299 uint32 server_id;
300
301 /* Master host, user and port */
302 char *host;
303 char *user;
304 unsigned int port;
305
306 char *master_log_name;
307 my_off_t master_log_pos;
308
309 MYSQL *mysql; /* the connection to master */
310} Binlog_relay_IO_param;
311
312/**
313 Observes and extends the service of slave IO thread.
314*/
315typedef struct Binlog_relay_IO_observer {
316 uint32 len;
317
318 /**
319 This callback is called when slave IO thread starts
320
321 @param param Observer common parameter
322
323 @retval 0 Sucess
324 @retval 1 Failure
325 */
326 int (*thread_start)(Binlog_relay_IO_param *param);
327
328 /**
329 This callback is called when slave IO thread stops
330
331 @param param Observer common parameter
332
333 @retval 0 Sucess
334 @retval 1 Failure
335 */
336 int (*thread_stop)(Binlog_relay_IO_param *param);
337
338 /**
339 This callback is called before slave requesting binlog transmission from master
340
341 This is called before slave issuing BINLOG_DUMP command to master
342 to request binlog.
343
344 @param param Observer common parameter
345 @param flags binlog dump flags
346
347 @retval 0 Sucess
348 @retval 1 Failure
349 */
350 int (*before_request_transmit)(Binlog_relay_IO_param *param, uint32 flags);
351
352 /**
353 This callback is called after read an event packet from master
354
355 @param param Observer common parameter
356 @param packet The event packet read from master
357 @param len Length of the event packet read from master
358 @param event_buf The event packet return after process
359 @param event_len The length of event packet return after process
360
361 @retval 0 Sucess
362 @retval 1 Failure
363 */
364 int (*after_read_event)(Binlog_relay_IO_param *param,
365 const char *packet, unsigned long len,
366 const char **event_buf, unsigned long *event_len);
367
368 /**
369 This callback is called after written an event packet to relay log
370
371 @param param Observer common parameter
372 @param event_buf Event packet written to relay log
373 @param event_len Length of the event packet written to relay log
374 @param flags flags for relay log
375
376 @retval 0 Sucess
377 @retval 1 Failure
378 */
379 int (*after_queue_event)(Binlog_relay_IO_param *param,
380 const char *event_buf, unsigned long event_len,
381 uint32 flags);
382
383 /**
384 This callback is called after reset slave relay log IO status
385
386 @param param Observer common parameter
387
388 @retval 0 Sucess
389 @retval 1 Failure
390 */
391 int (*after_reset_slave)(Binlog_relay_IO_param *param);
392} Binlog_relay_IO_observer;
393
394
395/**
396 Register a transaction observer
397
398 @param observer The transaction observer to register
399 @param p pointer to the internal plugin structure
400
401 @retval 0 Sucess
402 @retval 1 Observer already exists
403*/
404int register_trans_observer(Trans_observer *observer, void *p);
405
406/**
407 Unregister a transaction observer
408
409 @param observer The transaction observer to unregister
410 @param p pointer to the internal plugin structure
411
412 @retval 0 Sucess
413 @retval 1 Observer not exists
414*/
415int unregister_trans_observer(Trans_observer *observer, void *p);
416
417/**
418 Register a binlog storage observer
419
420 @param observer The binlog storage observer to register
421 @param p pointer to the internal plugin structure
422
423 @retval 0 Sucess
424 @retval 1 Observer already exists
425*/
426int register_binlog_storage_observer(Binlog_storage_observer *observer, void *p);
427
428/**
429 Unregister a binlog storage observer
430
431 @param observer The binlog storage observer to unregister
432 @param p pointer to the internal plugin structure
433
434 @retval 0 Sucess
435 @retval 1 Observer not exists
436*/
437int unregister_binlog_storage_observer(Binlog_storage_observer *observer, void *p);
438
439/**
440 Register a binlog transmit observer
441
442 @param observer The binlog transmit observer to register
443 @param p pointer to the internal plugin structure
444
445 @retval 0 Sucess
446 @retval 1 Observer already exists
447*/
448int register_binlog_transmit_observer(Binlog_transmit_observer *observer, void *p);
449
450/**
451 Unregister a binlog transmit observer
452
453 @param observer The binlog transmit observer to unregister
454 @param p pointer to the internal plugin structure
455
456 @retval 0 Sucess
457 @retval 1 Observer not exists
458*/
459int unregister_binlog_transmit_observer(Binlog_transmit_observer *observer, void *p);
460
461/**
462 Register a binlog relay IO (slave IO thread) observer
463
464 @param observer The binlog relay IO observer to register
465 @param p pointer to the internal plugin structure
466
467 @retval 0 Sucess
468 @retval 1 Observer already exists
469*/
470int register_binlog_relay_io_observer(Binlog_relay_IO_observer *observer, void *p);
471
472/**
473 Unregister a binlog relay IO (slave IO thread) observer
474
475 @param observer The binlog relay IO observer to unregister
476 @param p pointer to the internal plugin structure
477
478 @retval 0 Sucess
479 @retval 1 Observer not exists
480*/
481int unregister_binlog_relay_io_observer(Binlog_relay_IO_observer *observer, void *p);
482
483/**
484 Connect to master
485
486 This function can only used in the slave I/O thread context, and
487 will use the same master information to do the connection.
488
489 @code
490 MYSQL *mysql = mysql_init(NULL);
491 if (rpl_connect_master(mysql))
492 {
493 // do stuff with the connection
494 }
495 mysql_close(mysql); // close the connection
496 @endcode
497
498 @param mysql address of MYSQL structure to use, pass NULL will
499 create a new one
500
501 @return address of MYSQL structure on success, NULL on failure
502*/
503MYSQL *rpl_connect_master(MYSQL *mysql);
504
505/**
506 Get the value of user variable as an integer.
507
508 This function will return the value of variable @a name as an
509 integer. If the original value of the variable is not an integer,
510 the value will be converted into an integer.
511
512 @param name user variable name
513 @param value pointer to return the value
514 @param null_value if not NULL, the function will set it to true if
515 the value of variable is null, set to false if not
516
517 @retval 0 Success
518 @retval 1 Variable not found
519*/
520int get_user_var_int(const char *name,
521 long long int *value, int *null_value);
522
523/**
524 Get the value of user variable as a double precision float number.
525
526 This function will return the value of variable @a name as real
527 number. If the original value of the variable is not a real number,
528 the value will be converted into a real number.
529
530 @param name user variable name
531 @param value pointer to return the value
532 @param null_value if not NULL, the function will set it to true if
533 the value of variable is null, set to false if not
534
535 @retval 0 Success
536 @retval 1 Variable not found
537*/
538int get_user_var_real(const char *name,
539 double *value, int *null_value);
540
541/**
542 Get the value of user variable as a string.
543
544 This function will return the value of variable @a name as
545 string. If the original value of the variable is not a string,
546 the value will be converted into a string.
547
548 @param name user variable name
549 @param value pointer to the value buffer
550 @param len length of the value buffer
551 @param precision precision of the value if it is a float number
552 @param null_value if not NULL, the function will set it to true if
553 the value of variable is null, set to false if not
554
555 @retval 0 Success
556 @retval 1 Variable not found
557*/
558int get_user_var_str(const char *name,
559 char *value, unsigned long len,
560 unsigned int precision, int *null_value);
561
562
563
564#ifdef __cplusplus
565}
566#endif
567#endif /* REPLICATION_H */
568