API change: mysql_shutdown() now needs a 2nd parameter, the shutdown level.

Server will however still accept shutdown without specified level; so that old
mysqladmin can still shut server down.
I would like your comments on the names of shutdown level which I chose. You
are welcome to propose better names. Please however check WL#709 before.
Reason for the names I propose is to be accurate, thus leaving possibility
for other levels which we may imagine in the future; that's why I have rejected
names like "fast", "smart", "graceful" so far. My position is that WAIT_ALL_BUFFERS
or WAIT_CRITICAL_BUFFERS say what the shutdown does, whereas for "smart", "fast" you
need to remember what it does.
This should be pushed in 4.1.3 but only after your comments.


client/mysqladmin.c:
  2nd parameter for mysql_shutdown()
include/mysql.h:
  2nd paramater for mysql_shutdown()
include/mysql_com.h:
  4 types of shutdown
libmysql/libmysql.c:
  passing the requested shutdown level
sql/sql_parse.cc:
  check for the shutdown level in dispatch_command(). Though its value is ignored for now.
tools/mysqlmanager.c:
  2nd parameter to mysql_shutdown

client/mysqladmin.c

@@ -509,7 +509,7 @@ static int execute_commands(MYSQL *mysql,int argc, char **argv)
 	  !stat(pidfile, &pidfile_status))
 	last_modified= pidfile_status.st_mtime;
 
-      if (mysql_shutdown(mysql))
+      if (mysql_shutdown(mysql, SHUTDOWN_DEFAULT))
       {
 	my_printf_error(0,"shutdown failed; error: '%s'",MYF(ME_BELL),
 			mysql_error(mysql));

include/mysql.h

@@ -453,7 +453,9 @@ int             STDCALL mysql_add_slave(MYSQL* mysql, const char* host,
 					const char* user,
 					const char* passwd);
 
-int		STDCALL mysql_shutdown(MYSQL *mysql);
+int		STDCALL mysql_shutdown(MYSQL *mysql,
+                                       enum enum_shutdown_level
+                                       shutdown_level);
 int		STDCALL mysql_dump_debug_info(MYSQL *mysql);
 int		STDCALL mysql_refresh(MYSQL *mysql,
 				     unsigned int refresh_options);

include/mysql_com.h

@@ -223,6 +223,26 @@ enum enum_field_types { MYSQL_TYPE_DECIMAL, MYSQL_TYPE_TINY,
 #define FIELD_TYPE_INTERVAL    MYSQL_TYPE_ENUM
 #define FIELD_TYPE_GEOMETRY    MYSQL_TYPE_GEOMETRY
 
+enum enum_shutdown_level {
+  /*
+    We want levels to be in growing order of gracefulness. So we leave room
+    for future intermediate levels. For now, escalating one level is += 10;
+    later if we insert new levels in between we will need a function
+    next_shutdown_level(level). Note that DEFAULT does not respect the
+    growing property.
+  */
+  SHUTDOWN_DEFAULT= 255, /* mapped to WAIT_ALL_BUFFERS for now */
+  /*
+    Here is the list in growing order (the next does the previous plus
+    something). WAIT_ALL_BUFFERS is what we have now. Others are "this MySQL
+    server does not support this shutdown level yet".
+  */
+  SHUTDOWN_WAIT_CRITICAL_BUFFERS= 10, /* flush MyISAM buffs (no corruption) */
+  SHUTDOWN_WAIT_ALL_BUFFERS= 20, /* flush InnoDB buffers */
+  SHUTDOWN_WAIT_TRANSACTIONS= 30, /* wait for existing trans to finish */
+  SHUTDOWN_WAIT_CONNECTIONS= 40 /* wait for existing connections to finish */
+};
+
 /* options for mysql_set_option */
 enum enum_mysql_set_option
 {

libmysql/libmysql.c

@@ -1285,10 +1285,13 @@ mysql_drop_db(MYSQL *mysql, const char *db)
 
 
 int STDCALL
-mysql_shutdown(MYSQL *mysql)
+mysql_shutdown(MYSQL *mysql, enum enum_shutdown_level shutdown_level)
 {
+  uchar level[1];
+  level[0]= (uchar) shutdown_level;
   DBUG_ENTER("mysql_shutdown");
-  DBUG_RETURN(simple_command(mysql,COM_SHUTDOWN,0,0,0));
+  DBUG_RETURN(simple_command(mysql, COM_SHUTDOWN,
+                             &level, 1, 0));
 }
 
 

sql/sql_parse.cc

@@ -1308,6 +1308,7 @@ bool dispatch_command(enum enum_server_command command, THD *thd,
   if (command != COM_STATISTICS && command != COM_PING)
     query_id++;
   thread_running++;
+  /* TODO: set thd->lex->sql_command to SQLCOM_PARSE here */
   VOID(pthread_mutex_unlock(&LOCK_thread_count));
 
   thd->server_status&=
@@ -1478,6 +1479,7 @@ bool dispatch_command(enum enum_server_command command, THD *thd,
       thd->query_length= length;
       thd->query= packet;
       thd->query_id= query_id++;
+      /* TODO: set thd->lex->sql_command to SQLCOM_PARSE here */
       VOID(pthread_mutex_unlock(&LOCK_thread_count));
 #ifndef EMBEDDED_LIBRARY
       mysql_parse(thd, packet, length);
@@ -1631,10 +1633,25 @@ bool dispatch_command(enum enum_server_command command, THD *thd,
     }
 #ifndef EMBEDDED_LIBRARY
   case COM_SHUTDOWN:
+  {
     statistic_increment(com_other,&LOCK_status);
     if (check_global_access(thd,SHUTDOWN_ACL))
       break; /* purecov: inspected */
-    DBUG_PRINT("quit",("Got shutdown command"));
+    enum enum_shutdown_level level= (packet_length >= 2) ?
+      (enum enum_shutdown_level) (uchar) packet[0] : SHUTDOWN_DEFAULT;
+    DBUG_PRINT("quit",("Got shutdown command for level %u", level));
+    /*
+      Accept old mysql_shutdown (with no argument). For now we do nothing of
+      the argument.
+    */
+    if (level == SHUTDOWN_DEFAULT)
+      level= SHUTDOWN_WAIT_ALL_BUFFERS; // soon default will be configurable
+    else if (level != SHUTDOWN_WAIT_ALL_BUFFERS)
+    {
+      my_error(ER_NOT_SUPPORTED_YET, MYF(0), "this shutdown level");
+      send_error(thd);
+      break;
+    }
     mysql_log.write(thd,command,NullS);
     send_eof(thd);
 #ifdef __WIN__
@@ -1650,6 +1667,7 @@ bool dispatch_command(enum enum_server_command command, THD *thd,
     kill_mysql();
     error=TRUE;
     break;
+  }
 #endif
   case COM_STATISTICS:
   {

tools/mysqlmanager.c

@@ -687,7 +687,7 @@ HANDLE_DECL(handle_stop_exec)
     error="Process not running";
     goto err;
   }
-  if (mysql_shutdown(&e->mysql))
+  if (mysql_shutdown(&e->mysql, SHUTDOWN_DEFAULT))
   {
     /* e->th=0; */	/* th may be a struct */
     pthread_mutex_unlock(&e->lock);