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, Fifth Floor, 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 33 typedef struct st_mysql MYSQL; 34 35 #ifdef __cplusplus 36 extern "C" { 37 #endif 38 39 /** 40 Transaction observer flags. 41 */ 42 enum Trans_flags { 43 /** Transaction is a real transaction */ 44 TRANS_IS_REAL_TRANS = 1 45 }; 46 47 /** 48 Transaction observer parameter 49 */ 50 typedef 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 */ 68 typedef 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 */ 116 enum 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 */ 130 typedef struct Binlog_storage_param { 131 uint32 server_id; 132 } Binlog_storage_param; 133 134 /** 135 Observe binlog logging storage 136 */ 137 typedef 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 */ 185 typedef 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 */ 193 typedef 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 */ 289 enum 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 */ 298 typedef 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 */ 315 typedef 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 */ 404 int 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 */ 415 int 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 */ 426 int 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 */ 437 int 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 */ 448 int 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 */ 459 int 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 */ 470 int 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 */ 481 int 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 */ 503 MYSQL *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 */ 520 int 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 */ 538 int 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 */ 558 int 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