~drizzle-trunk/drizzle/development

/* -*- mode: c++; c-basic-offset: 2; indent-tabs-mode: nil; -*-

 *  vim:expandtab:shiftwidth=2:tabstop=2:smarttab:

 *

 *  Copyright (C) 2008 Sun Microsystems

 *

 *  This program is free software; you can redistribute it and/or modify

 *  it under the terms of the GNU General Public License as published by

 *  the Free Software Foundation; version 2 of the License.

 *

 *  This program is distributed in the hope that it will be useful,

 *  but WITHOUT ANY WARRANTY; without even the implied warranty of

 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the

 *  GNU General Public License for more details.

 *

 *  You should have received a copy of the GNU General Public License

 *  along with this program; if not, write to the Free Software

 *  Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA

 */

/**

  @addtogroup Replication

  @{

  @file

  @brief Binary log event definitions.  This includes generic code

  common to all types of log events, as well as specific code for each

  type of log event.

*/

#ifndef DRIZZLED_LOG_EVENT_H

#define DRIZZLED_LOG_EVENT_H

#include <mysys/my_bitmap.h>

#include <drizzled/replication/constants.h>

#include <drizzled/replication/record.h>

#include <drizzled/replication/reporting.h>

#include <drizzled/session.h>

#include <string>

#include <drizzled/sql_string.h>       /* append_query_string() needs String declaration */

/**

   Either assert or return an error.

   In debug build, the condition will be checked, but in non-debug

   builds, the error code given will be returned instead.

   @param COND   Condition to check

   @param ERRNO  Error number to return in non-debug builds

*/

#define ASSERT_OR_RETURN_ERROR(COND, ERRNO) \

  assert(COND)

#define LOG_READ_EOF    -1

#define LOG_READ_BOGUS  -2

#define LOG_READ_IO     -3

#define LOG_READ_MEM    -5

#define LOG_READ_TRUNC  -6

#define LOG_READ_TOO_LARGE -7

#define LOG_EVENT_OFFSET 4

/*

   3 is MySQL 4.x; 4 is MySQL 5.0.0.

   Compared to version 3, version 4 has:

   - a different Start_log_event, which includes info about the binary log

   (sizes of headers); this info is included for better compatibility if the

   master's MySQL version is different from the slave's.

   - all events have a unique ID (the triplet (server_id, timestamp at server

   start, other) to be sure an event is not executed more than once in a

   multimaster setup, example:

                M1

              /   \

             v     v

             M2    M3

             \     /

              v   v

                S

   if a query is run on M1, it will arrive twice on S, so we need that S

   remembers the last unique ID it has processed, to compare and know if the

   event should be skipped or not. Example of ID: we already have the server id

   (4 bytes), plus:

   timestamp_when_the_master_started (4 bytes), a counter (a sequence number

   which increments every time we write an event to the binlog) (3 bytes).

   Q: how do we handle when the counter is overflowed and restarts from 0 ?

   - Query and Load (Create or Execute) events may have a more precise

     timestamp (with microseconds), number of matched/affected/warnings rows

   and fields of session variables: SQL_MODE,

   FOREIGN_KEY_CHECKS, UNIQUE_CHECKS, SQL_AUTO_IS_NULL, the collations and

   charsets, the PASSWORD() version (old/new/...).

*/

#define BINLOG_VERSION    4

/*

 We could have used SERVER_VERSION_LENGTH, but this introduces an

 obscure dependency - if somebody decided to change SERVER_VERSION_LENGTH

 this would break the replication protocol

*/

#define ST_SERVER_VER_LEN 50

/*

  These are flags and structs to handle all the LOAD DATA INFILE options (LINES

  TERMINATED etc).

*/

/*

  These are flags and structs to handle all the LOAD DATA INFILE options (LINES

  TERMINATED etc).

  DUMPFILE_FLAG is probably useless (DUMPFILE is a clause of SELECT, not of LOAD

  DATA).

*/

#define DUMPFILE_FLAG		0x1

#define OPT_ENCLOSED_FLAG	0x2

#define REPLACE_FLAG		0x4

#define IGNORE_FLAG		0x8

#define FIELD_TERM_EMPTY	0x1

#define ENCLOSED_EMPTY		0x2

#define LINE_TERM_EMPTY		0x4

#define LINE_START_EMPTY	0x8

#define ESCAPED_EMPTY		0x10

#define NUM_LOAD_DELIM_STRS 5

/*****************************************************************************

  sql_ex_info struct

 ****************************************************************************/

struct sql_ex_info

{

  sql_ex_info() {}                            /* Remove gcc warning */

  const char* field_term;

  const char* enclosed;

  const char* line_term;

  const char* line_start;

  const char* escaped;

  int cached_new_format;

  uint8_t field_term_len,enclosed_len,line_term_len,line_start_len, escaped_len;

  char opt_flags;

  char empty_flags;

  /* store in new format even if old is possible */

  void force_new_format() { cached_new_format = 1;}

  int data_size()

  {

    return (new_format() ?

	    field_term_len + enclosed_len + line_term_len +

	    line_start_len + escaped_len + 6 : 7);

  }

  bool write_data(IO_CACHE* file);

  const char* init(const char* buf, const char* buf_end, bool use_new_format);

  bool new_format()

  {

    return ((cached_new_format != -1) ? cached_new_format :

	    (cached_new_format=(field_term_len > 1 ||

				enclosed_len > 1 ||

				line_term_len > 1 || line_start_len > 1 ||

				escaped_len > 1)));

  }

};

/*****************************************************************************

  MySQL Binary Log

  This log consists of events.  Each event has a fixed-length header,

  possibly followed by a variable length data body.

  The data body consists of an optional fixed length segment (post-header)

  and  an optional variable length segment.

  See the #defines below for the format specifics.

  The events which really update data are Query_log_event,

  Execute_load_query_log_event and old Load_log_event and

  Execute_load_log_event events (Execute_load_query is used together with

  Begin_load_query and Append_block events to replicate LOAD DATA INFILE.

  Create_file/Append_block/Execute_load (which includes Load_log_event)

  were used to replicate LOAD DATA before the 5.0.3).

 ****************************************************************************/

#define LOG_EVENT_HEADER_LEN 19     /* the fixed header length */

#define OLD_HEADER_LEN       13     /* the fixed header length in 3.23 */

/*

   Fixed header length, where 4.x and 5.0 agree. That is, 5.0 may have a longer

   header (it will for sure when we have the unique event's ID), but at least

   the first 19 bytes are the same in 4.x and 5.0. So when we have the unique

   event's ID, LOG_EVENT_HEADER_LEN will be something like 26, but

   LOG_EVENT_MINIMAL_HEADER_LEN will remain 19.

*/

#define LOG_EVENT_MINIMAL_HEADER_LEN (uint8_t)19

/* event-specific post-header sizes */

// where 3.23, 4.x and 5.0 agree

#define QUERY_HEADER_MINIMAL_LEN     (4 + 4 + 1 + 2)

// where 5.0 differs: 2 for len of N-bytes vars.

#define QUERY_HEADER_LEN     (QUERY_HEADER_MINIMAL_LEN + 2)

#define LOAD_HEADER_LEN      (4 + 4 + 4 + 1 +1 + 4)

#define START_V3_HEADER_LEN     (2 + ST_SERVER_VER_LEN + 4)

#define ROTATE_HEADER_LEN    8 // this is FROZEN (the Rotate post-header is frozen)

#define CREATE_FILE_HEADER_LEN 4

#define APPEND_BLOCK_HEADER_LEN 4

#define EXEC_LOAD_HEADER_LEN   4

#define DELETE_FILE_HEADER_LEN 4

#define FORMAT_DESCRIPTION_HEADER_LEN (START_V3_HEADER_LEN+1+LOG_EVENT_TYPES)

#define ROWS_HEADER_LEN        8

#define TABLE_MAP_HEADER_LEN   8

#define EXECUTE_LOAD_QUERY_EXTRA_HEADER_LEN (4 + 4 + 4 + 1)

#define EXECUTE_LOAD_QUERY_HEADER_LEN  (QUERY_HEADER_LEN + EXECUTE_LOAD_QUERY_EXTRA_HEADER_LEN)

#define INCIDENT_HEADER_LEN    2

#define HEARTBEAT_HEADER_LEN   0

/* 

  Max number of possible extra bytes in a replication event compared to a

  packet (i.e. a query) sent from client to master;

  First, an auxiliary log_event status vars estimation:

*/

#define MAX_SIZE_LOG_EVENT_STATUS (4 /* flags2 */   + \

                                   8 /* sql mode */ + \

                                   1 + 1 + 255 /* catalog */ + \

                                   4 /* autoinc */ + \

                                   6 /* charset */ + \

                                   MAX_TIME_ZONE_NAME_LENGTH)

#define MAX_LOG_EVENT_HEADER   ( /* in order of Query_log_event::write */ \

  LOG_EVENT_HEADER_LEN + /* write_header */ \

  QUERY_HEADER_LEN     + /* write_data */   \

  EXECUTE_LOAD_QUERY_EXTRA_HEADER_LEN + /*write_post_header_for_derived */ \

  MAX_SIZE_LOG_EVENT_STATUS + /* status */ \

  NAME_LEN + 1)

/* 

   Event header offsets; 

   these point to places inside the fixed header.

*/

#define EVENT_TYPE_OFFSET    4

#define SERVER_ID_OFFSET     5

#define EVENT_LEN_OFFSET     9

#define LOG_POS_OFFSET       13

#define FLAGS_OFFSET         17

/* start event post-header (for v3 and v4) */

#define ST_BINLOG_VER_OFFSET  0

#define ST_SERVER_VER_OFFSET  2

#define ST_CREATED_OFFSET     (ST_SERVER_VER_OFFSET + ST_SERVER_VER_LEN)

#define ST_COMMON_HEADER_LEN_OFFSET (ST_CREATED_OFFSET + 4)

/* slave event post-header (this event is never written) */

#define SL_MASTER_PORT_OFFSET   8

#define SL_MASTER_POS_OFFSET    0

#define SL_MASTER_HOST_OFFSET   10

/* query event post-header */

#define Q_THREAD_ID_OFFSET	0

#define Q_EXEC_TIME_OFFSET	4

#define Q_DB_LEN_OFFSET		8

#define Q_ERR_CODE_OFFSET	9

#define Q_STATUS_VARS_LEN_OFFSET 11

#define Q_DATA_OFFSET		QUERY_HEADER_LEN

/* these are codes, not offsets; not more than 256 values (1 byte). */

#define Q_FLAGS2_CODE           0

#define Q_LC_TIME_NAMES_CODE    7

#define Q_CHARSET_DATABASE_CODE 8

/* Intvar event post-header */

#define I_TYPE_OFFSET        0

#define I_VAL_OFFSET         1

/* Rand event post-header */

#define RAND_SEED1_OFFSET 0

#define RAND_SEED2_OFFSET 8

/* User_var event post-header */

#define UV_VAL_LEN_SIZE        4

#define UV_VAL_IS_NULL         1

#define UV_VAL_TYPE_SIZE       1

#define UV_NAME_LEN_SIZE       4

#define UV_CHARSET_NUMBER_SIZE 4

/* Load event post-header */

#define L_THREAD_ID_OFFSET   0

#define L_EXEC_TIME_OFFSET   4

#define L_SKIP_LINES_OFFSET  8

#define L_TBL_LEN_OFFSET     12

#define L_DB_LEN_OFFSET      13

#define L_NUM_FIELDS_OFFSET  14

#define L_SQL_EX_OFFSET      18

#define L_DATA_OFFSET        LOAD_HEADER_LEN

/* Rotate event post-header */

#define R_POS_OFFSET       0

#define R_IDENT_OFFSET     8

/* CF to DF handle LOAD DATA INFILE */

/* CF = "Create File" */

#define CF_FILE_ID_OFFSET  0

#define CF_DATA_OFFSET     CREATE_FILE_HEADER_LEN

/* AB = "Append Block" */

#define AB_FILE_ID_OFFSET  0

#define AB_DATA_OFFSET     APPEND_BLOCK_HEADER_LEN

/* EL = "Execute Load" */

#define EL_FILE_ID_OFFSET  0

/* DF = "Delete File" */

#define DF_FILE_ID_OFFSET  0

/* TM = "Table Map" */

#define TM_MAPID_OFFSET    0

#define TM_FLAGS_OFFSET    6

/* RW = "RoWs" */

#define RW_MAPID_OFFSET    0

#define RW_FLAGS_OFFSET    6

/* ELQ = "Execute Load Query" */

#define ELQ_FILE_ID_OFFSET QUERY_HEADER_LEN

#define ELQ_FN_POS_START_OFFSET ELQ_FILE_ID_OFFSET + 4

#define ELQ_FN_POS_END_OFFSET ELQ_FILE_ID_OFFSET + 8

#define ELQ_DUP_HANDLING_OFFSET ELQ_FILE_ID_OFFSET + 12

/* 4 bytes which all binlogs should begin with */

#define BINLOG_MAGIC        "\xfe\x62\x69\x6e"

/*

   This flag only makes sense for Format_description_log_event. It is set

   when the event is written, and *reset* when a binlog file is

   closed (yes, it's the only case when MySQL modifies already written

   part of binlog).  Thus it is a reliable indicator that binlog was

   closed correctly.  (Stop_log_event is not enough, there's always a

   small chance that mysqld crashes in the middle of insert and end of

   the binlog would look like a Stop_log_event).

   This flag is used to detect a restart after a crash, and to provide

   "unbreakable" binlog. The problem is that on a crash storage engines

   rollback automatically, while binlog does not.  To solve this we use this

   flag and automatically append ROLLBACK to every non-closed binlog (append

   virtually, on reading, file itself is not changed). If this flag is found,

   mysqlbinlog simply prints "ROLLBACK" Replication master does not abort on

   binlog corruption, but takes it as EOF, and replication slave forces a

   rollback in this case.

   Note, that old binlogs does not have this flag set, so we get a

   a backward-compatible behaviour.

*/

#define LOG_EVENT_BINLOG_IN_USE_F       0x1

/**

  @def LOG_EVENT_THREAD_SPECIFIC_F

  If the query depends on the thread (for example: TEMPORARY Table).

  Currently this is used by mysqlbinlog to know it must print

  SET @@PSEUDO_THREAD_ID=xx; before the query (it would not hurt to print it

  for every query but this would be slow).

*/

#define LOG_EVENT_THREAD_SPECIFIC_F 0x4

/**

  @def LOG_EVENT_SUPPRESS_USE_F

  Suppress the generation of 'USE' statements before the actual

  statement. This flag should be set for any events that does not need

  the current database set to function correctly. Most notable cases

  are 'CREATE DATABASE' and 'DROP DATABASE'.

  This flags should only be used in exceptional circumstances, since

  it introduce a significant change in behaviour regarding the

  replication logic together with the flags --binlog-do-db and

  --replicated-do-db.

 */

#define LOG_EVENT_SUPPRESS_USE_F    0x8

/*

  The table map version internal to the log should be increased after

  the event has been written to the binary log.

 */

#define LOG_EVENT_UPDATE_TABLE_MAP_VERSION_F 0x10

/**

  @def OPTIONS_WRITTEN_TO_BIN_LOG

  OPTIONS_WRITTEN_TO_BIN_LOG are the bits of session->options which must

  be written to the binlog. OPTIONS_WRITTEN_TO_BIN_LOG could be

  written into the Format_description_log_event, so that if later we

  don't want to replicate a variable we did replicate, or the

  contrary, it's doable. But it should not be too hard to decide once

  for all of what we replicate and what we don't, among the fixed 32

  bits of session->options.

  I (Guilhem) have read through every option's usage, and it looks

  like OPTION_AUTO_IS_NULL and OPTION_NO_FOREIGN_KEYS are the only

  ones which alter how the query modifies the table. It's good to

  replicate OPTION_RELAXED_UNIQUE_CHECKS too because otherwise, the

  slave may insert data slower than the master, in InnoDB.

  OPTION_BIG_SELECTS is not needed (the slave thread runs with

  max_join_size=HA_POS_ERROR) and OPTION_BIG_TABLES is not needed

  either, as the manual says (because a too big in-memory temp table

  is automatically written to disk).

*/

#define OPTIONS_WRITTEN_TO_BIN_LOG \

  (OPTION_AUTO_IS_NULL | OPTION_NO_FOREIGN_KEY_CHECKS |  \

   OPTION_RELAXED_UNIQUE_CHECKS | OPTION_NOT_AUTOCOMMIT)

/* Shouldn't be defined before */

#define EXPECTED_OPTIONS \

  ((1U << 14) | (1U << 26) | (1U << 27) | (1U << 19))

#if OPTIONS_WRITTEN_TO_BIN_LOG != EXPECTED_OPTIONS

#error OPTIONS_WRITTEN_TO_BIN_LOG must NOT change their values!

#endif

#undef EXPECTED_OPTIONS         /* You shouldn't use this one */

/**

  @enum Log_event_type

  Enumeration type for the different types of log events.

*/

enum Log_event_type

{

  /*

    Every time you update this enum (when you add a type), you have to

    fix Format_description_log_event::Format_description_log_event().

  */

  UNKNOWN_EVENT= 0,

  START_EVENT_V3= 1,

  QUERY_EVENT= 2,

  STOP_EVENT= 3,

  ROTATE_EVENT= 4,

  INTVAR_EVENT= 5,

  LOAD_EVENT= 6,

  SLAVE_EVENT= 7,

  CREATE_FILE_EVENT= 8,

  APPEND_BLOCK_EVENT= 9,

  EXEC_LOAD_EVENT= 10,

  DELETE_FILE_EVENT= 11,

  /*

    NEW_LOAD_EVENT is like LOAD_EVENT except that it has a longer

    sql_ex, allowing multibyte TERMINATED BY etc; both types share the

    same class (Load_log_event)

  */

  NEW_LOAD_EVENT= 12,

  RAND_EVENT= 13,

  USER_VAR_EVENT= 14,

  FORMAT_DESCRIPTION_EVENT= 15,

  XID_EVENT= 16,

  BEGIN_LOAD_QUERY_EVENT= 17,

  EXECUTE_LOAD_QUERY_EVENT= 18,

  TABLE_MAP_EVENT = 19,

  /*

    These event numbers are used from 5.1.16 and forward

   */

  WRITE_ROWS_EVENT = 23,

  UPDATE_ROWS_EVENT = 24,

  DELETE_ROWS_EVENT = 25,

  /*

    Something out of the ordinary happened on the master

   */

  INCIDENT_EVENT= 26,

  /*

    Heartbeat event to be send by master at its idle time 

    to ensure master's online status to slave 

  */

  HEARTBEAT_LOG_EVENT= 27,

  /*

    Add new events here - right above this comment!

    Existing events (except ENUM_END_EVENT) should never change their numbers

  */

  ENUM_END_EVENT /* end marker */

};

/*

   The number of types we handle in Format_description_log_event (UNKNOWN_EVENT

   is not to be handled, it does not exist in binlogs, it does not have a

   format).

*/

#define LOG_EVENT_TYPES (ENUM_END_EVENT-1)

enum Int_event_type

{

  INVALID_INT_EVENT = 0, LAST_INSERT_ID_EVENT = 1, INSERT_ID_EVENT = 2

};

class String;

class DRIZZLE_BIN_LOG;

class Session;

class Format_description_log_event;

class Relay_log_info;

/**

  the struct aggregates two paramenters that identify an event

  uniquely in scope of communication of a particular master and slave couple.

  I.e there can not be 2 events from the same staying connected master which

  have the same coordinates.

  @note

  Such identifier is not yet unique generally as the event originating master

  is resetable. Also the crashed master can be replaced with some other.

*/

struct event_coordinates

{

  char * file_name; // binlog file name (directories stripped)

  my_off_t  pos;       // event's position in the binlog file

};

/**

  @class Log_event

  This is the abstract base class for binary log events.

  @section Log_event_binary_format Binary Format

  Any @c Log_event saved on disk consists of the following three

  components.

  - Common-Header

  - Post-Header

  - Body

  The Common-Header, documented in the table @ref Table_common_header

  "below", always has the same form and length within one version of

  MySQL.  Each event type specifies a format and length of the

  Post-Header.  The length of the Common-Header is the same for all

  events of the same type.  The Body may be of different format and

  length even for different events of the same type.  The binary

  formats of Post-Header and Body are documented separately in each

  subclass.  The binary format of Common-Header is as follows.

  <table>

  <caption>Common-Header</caption>

  <tr>

    <th>Name</th>

    <th>Format</th>

    <th>Description</th>

  </tr>

  <tr>

    <td>timestamp</td>

    <td>4 byte unsigned integer</td>

    <td>The time when the query started, in seconds since 1970.

    </td>

  </tr>

  <tr>

    <td>type</td>

    <td>1 byte enumeration</td>

    <td>See enum #Log_event_type.</td>

  </tr>

  <tr>

    <td>server_id</td>

    <td>4 byte unsigned integer</td>

    <td>Server ID of the server that created the event.</td>

  </tr>

  <tr>

    <td>total_size</td>

    <td>4 byte unsigned integer</td>

    <td>The total size of this event, in bytes.  In other words, this

    is the sum of the sizes of Common-Header, Post-Header, and Body.

    </td>

  </tr>

  <tr>

    <td>master_position</td>

    <td>4 byte unsigned integer</td>

    <td>The position of the next event in the master binary log, in

    bytes from the beginning of the file.  In a binlog that is not a

    relay log, this is just the position of the next event, in bytes

    from the beginning of the file.  In a relay log, this is

    the position of the next event in the master's binlog.

    </td>

  </tr>

  <tr>

    <td>flags</td>

    <td>2 byte bitfield</td>

    <td>See Log_event::flags.</td>

  </tr>

  </table>

  Summing up the numbers above, we see that the total size of the

  common header is 19 bytes.

  @subsection Log_event_format_of_atomic_primitives Format of Atomic Primitives

  - All numbers, whether they are 16-, 24-, 32-, or 64-bit numbers,

  are stored in little endian, i.e., the least significant byte first,

  unless otherwise specified.

  @anchor packed_integer

  - Some events use a special format for efficient representation of

  unsigned integers, called Packed Integer.  A Packed Integer has the

  capacity of storing up to 8-byte integers, while small integers

  still can use 1, 3, or 4 bytes.  The value of the first byte

  determines how to read the number, according to the following table:

  <table>

  <caption>Format of Packed Integer</caption>

  <tr>

    <th>First byte</th>

    <th>Format</th>

  </tr>

  <tr>

    <td>0-250</td>

    <td>The first byte is the number (in the range 0-250), and no more

    bytes are used.</td>

  </tr>

  <tr>

    <td>252</td>

    <td>Two more bytes are used.  The number is in the range

    251-0xffff.</td>

  </tr>

  <tr>

    <td>253</td>

    <td>Three more bytes are used.  The number is in the range

    0xffff-0xffffff.</td>

  </tr>

  <tr>

    <td>254</td>

    <td>Eight more bytes are used.  The number is in the range

    0xffffff-0xffffffffffffffff.</td>

  </tr>

  </table>

  - Strings are stored in various formats.  The format of each string

  is documented separately.

*/

class Log_event

{

public:

  /**

     Enumeration of what kinds of skipping (and non-skipping) that can

     occur when the slave executes an event.

     @see shall_skip

     @see do_shall_skip

   */

  enum enum_skip_reason {

    /**

       Don't skip event.

    */

    EVENT_SKIP_NOT,

    /**

       Skip event by ignoring it.

       This means that the slave skip counter will not be changed.

    */

    EVENT_SKIP_IGNORE,

    /**

       Skip event and decrease skip counter.

    */

    EVENT_SKIP_COUNT

  };

  /*

    The following type definition is to be used whenever data is placed 

    and manipulated in a common buffer. Use this typedef for buffers

    that contain data containing binary and character data.

  */

  typedef unsigned char Byte;

  /*

    The offset in the log where this event originally appeared (it is

    preserved in relay logs, making SHOW SLAVE STATUS able to print

    coordinates of the event in the master's binlog). Note: when a

    transaction is written by the master to its binlog (wrapped in

    BEGIN/COMMIT) the log_pos of all the queries it contains is the

    one of the BEGIN (this way, when one does SHOW SLAVE STATUS it

    sees the offset of the BEGIN, which is logical as rollback may

    occur), except the COMMIT query which has its real offset.

  */

  off_t log_pos;

  /*

     A temp buffer for read_log_event; it is later analysed according to the

     event's type, and its content is distributed in the event-specific fields.

  */

  char *temp_buf;

  /*

    Timestamp on the master(for debugging and replication of

    NOW()/TIMESTAMP).  It is important for queries and LOAD DATA

    INFILE. This is set at the event's creation time, except for Query

    and Load (et al.) events where this is set at the query's

    execution time, which guarantees good replication (otherwise, we

    could have a query and its event with different timestamps).

  */

  time_t when;

  /* The number of seconds the query took to run on the master. */

  ulong exec_time;

  /* Number of bytes written by write() function */

  ulong data_written;

  /*

    The master's server id (is preserved in the relay log; used to

    prevent from infinite loops in circular replication).

  */

  uint32_t server_id;

  /**

    Some 16 flags. See the definitions above for LOG_EVENT_TIME_F,

    LOG_EVENT_FORCED_ROTATE_F, LOG_EVENT_THREAD_SPECIFIC_F, and

    LOG_EVENT_SUPPRESS_USE_F for notes.

  */

  uint16_t flags;

  bool cache_stmt;

  /**

    A storage to cache the global system variable's value.

    Handling of a separate event will be governed its member.

  */

  ulong slave_exec_mode;

  Session* session;

  Log_event();

  Log_event(Session* session_arg, uint16_t flags_arg, bool cache_stmt);

  /*

    read_log_event() functions read an event from a binlog or relay

    log; used by SHOW BINLOG EVENTS, the binlog_dump thread on the

    master (reads master's binlog), the slave IO thread (reads the

    event sent by binlog_dump), the slave SQL thread (reads the event

    from the relay log).  If mutex is 0, the read will proceed without

    mutex.  We need the description_event to be able to parse the

    event (to know the post-header's size); in fact in read_log_event

    we detect the event's type, then call the specific event's

    constructor and pass description_event as an argument.

  */

  static Log_event* read_log_event(IO_CACHE* file,

                                   pthread_mutex_t* log_lock,

                                   const Format_description_log_event

                                   *description_event);

  static int read_log_event(IO_CACHE* file, String* packet,

                            pthread_mutex_t* log_lock);

  /*

    init_show_field_list() prepares the column names and types for the

    output of SHOW BINLOG EVENTS; it is used only by SHOW BINLOG

    EVENTS.

  */

  static void init_show_field_list(List<Item>* field_list);

  int net_send(Protocol *protocol, const char* log_name, my_off_t pos);

  /*

    pack_info() is used by SHOW BINLOG EVENTS; as print() it prepares and sends

    a string to display to the user, so it resembles print().

  */

  virtual void pack_info(Protocol *protocol);

  virtual const char* get_db();

  static void *operator new(size_t size)

  {

    return (void*) my_malloc((uint)size, MYF(MY_WME|MY_FAE));

  }

  static void operator delete(void *ptr,

                              size_t)

  {

    free((unsigned char*) ptr);

  }

  /* Placement version of the above operators */

  static void *operator new(size_t, void* ptr) { return ptr; }

  static void operator delete(void*, void*) { }

  bool write_header(IO_CACHE* file, ulong data_length);

  virtual bool write(IO_CACHE* file)

  {

    return (write_header(file, get_data_size()) ||

            write_data_header(file) ||

            write_data_body(file));

  }

  virtual bool write_data_header(IO_CACHE*)

  { return 0; }

  virtual bool write_data_body(IO_CACHE*)

  { return 0; }

  time_t get_time();

  virtual Log_event_type get_type_code() = 0;

  virtual bool is_valid() const = 0;

  virtual bool is_artificial_event() { return 0; }

  inline bool get_cache_stmt() const { return cache_stmt; }

  Log_event(const char* buf, const Format_description_log_event

            *description_event);

  virtual ~Log_event() { free_temp_buf();}

  void register_temp_buf(char* buf) { temp_buf = buf; }

  void free_temp_buf()

  {

    if (temp_buf)

    {

      free(temp_buf);

      temp_buf = 0;

    }

  }

  /*

    Get event length for simple events. For complicated events the length

    is calculated during write()

  */

  virtual int get_data_size() { return 0;}

  static Log_event* read_log_event(const char* buf, uint32_t event_len,

				   const char **error,

                                   const Format_description_log_event

                                   *description_event);

  /**

    Returns the human readable name of the given event type.

  */

  static const char* get_type_str(Log_event_type type);

  /**

    Returns the human readable name of this event's type.

  */

  const char* get_type_str();

  /* Return start of query time or current time */

public:

  /**

     Apply the event to the database.

     This function represents the public interface for applying an

     event.

     @see do_apply_event

   */

  int apply_event(Relay_log_info const *rli)

  {

    return do_apply_event(rli);

  }

  /**

     Update the relay log position.

     This function represents the public interface for "stepping over"

     the event and will update the relay log information.

     @see do_update_pos

   */

  int update_pos(Relay_log_info *rli)

  {

    return do_update_pos(rli);

  }

  /**

     Decide if the event shall be skipped, and the reason for skipping

     it.

     @see do_shall_skip

   */

  enum_skip_reason shall_skip(Relay_log_info *rli)

  {

    return do_shall_skip(rli);

  }

protected:

  /**

     Helper function to ignore an event w.r.t. the slave skip counter.

     This function can be used inside do_shall_skip() for functions

     that cannot end a group. If the slave skip counter is 1 when

     seeing such an event, the event shall be ignored, the counter

     left intact, and processing continue with the next event.

     A typical usage is:

     @code

     enum_skip_reason do_shall_skip(Relay_log_info *rli) {

       return continue_group(rli);

     }

     @endcode

     @return Skip reason

   */

  enum_skip_reason continue_group(Relay_log_info *rli);

  /**

    Primitive to apply an event to the database.

    This is where the change to the database is made.

    @note The primitive is protected instead of private, since there

    is a hierarchy of actions to be performed in some cases.

    @see Format_description_log_event::do_apply_event()

    @param rli Pointer to relay log info structure

    @retval 0     Event applied successfully

    @retval errno Error code if event application failed

  */

  virtual int do_apply_event(Relay_log_info const *)

  {

    return 0;                /* Default implementation does nothing */

  }

  /**

     Advance relay log coordinates.

     This function is called to advance the relay log coordinates to

     just after the event.  It is essential that both the relay log

     coordinate and the group log position is updated correctly, since

     this function is used also for skipping events.

     Normally, each implementation of do_update_pos() shall:

     - Update the event position to refer to the position just after

       the event.

     - Update the group log position to refer to the position just

       after the event <em>if the event is last in a group</em>

     @param rli Pointer to relay log info structure

     @retval 0     Coordinates changed successfully

     @retval errno Error code if advancing failed (usually just

                   1). Observe that handler errors are returned by the

                   do_apply_event() function, and not by this one.

   */

  virtual int do_update_pos(Relay_log_info *rli);

  /**

     Decide if this event shall be skipped or not and the reason for

     skipping it.

     The default implementation decide that the event shall be skipped

     if either:

     - the server id of the event is the same as the server id of the

       server and <code>rli->replicate_same_server_id</code> is true,

       or

     - if <code>rli->slave_skip_counter</code> is greater than zero.

     @see do_apply_event

     @see do_update_pos

     @retval Log_event::EVENT_SKIP_NOT

     The event shall not be skipped and should be applied.

     @retval Log_event::EVENT_SKIP_IGNORE

     The event shall be skipped by just ignoring it, i.e., the slave

     skip counter shall not be changed. This happends if, for example,

     the originating server id of the event is the same as the server

     id of the slave.

     @retval Log_event::EVENT_SKIP_COUNT

     The event shall be skipped because the slave skip counter was

     non-zero. The caller shall decrease the counter by one.

   */

  virtual enum_skip_reason do_shall_skip(Relay_log_info *rli);

};

/*

   One class for each type of event.

   Two constructors for each class:

   - one to create the event for logging (when the server acts as a master),

   called after an update to the database is done,

   which accepts parameters like the query, the database, the options for LOAD

   DATA INFILE...

   - one to create the event from a packet (when the server acts as a slave),

   called before reproducing the update, which accepts parameters (like a

   buffer). Used to read from the master, from the relay log, and in

   mysqlbinlog. This constructor must be format-tolerant.

*/

/**

  @class Query_log_event

  A @c Query_log_event is created for each query that modifies the

  database, unless the query is logged row-based.

  @section Query_log_event_binary_format Binary format

  See @ref Log_event_binary_format "Binary format for log events" for

  a general discussion and introduction to the binary format of binlog

  events.

  The Post-Header has five components:

  <table>

  <caption>Post-Header for Query_log_event</caption>

  <tr>

    <th>Name</th>

    <th>Format</th>

    <th>Description</th>

  </tr>

  <tr>