adding handlerton docs to mainline, going to redo the 3938 branch

git-svn-id: file:///svn/mysql/tokudb-engine/tokudb-engine@35722 c7de825b-a66e-492c-adef-691d508d4ae1

storage/tokudb/doc/handlerton-lock

@@ -0,0 +1,84 @@
+== Introduction ==
+
+MySQL interfaces with TokuDB through a set of plugins, which, at
+the time of this writing (October 2011) includes the tokudb storage
+engine plugin, the user data information schema plugin, and the 
+user data exact information schema plugin. Each plugin has its own
+initialize and de-initialize functions for mysql to call when
+clients install and uninstall them. 
+
+== Problem == 
+
+It was originally discovered that the two information schema plugins
+would crash mysqld if the tokudb storage engine failed to init
+properly. A quick fix for this problem was to have the storage engine
+plugin's init function set a global flag, call it tokudb_hton_initialized,
+which would be set if intialize succeeded. Other plugins could then check
+it before proceeding. The original problem is fixed, but the following
+still remain:
+
+    * a client connects, uninstalls tokudb storage engine, accesses 
+      the tokudb user data/exact table.
+
+    * uninstall the tokudb engine plugin, drop a table, select from
+      it to see that it does not exist, then install the tokudb engine
+      to see that it has reappeared.
+
+    * any situation where one client is using any plugin while another 
+      client modifies one.
+
+== Proposed solution ==
+
+Use a reader-writer lock in the handlerton to protect the existing
+tokudb_hton_initialized variable. All accesses to the handlerton (storage
+engine, information schema, or otherwise) grab a read lock before
+checking the initialized flag. Plugin initializers and de-initializers
+grab a write lock on the initialized flag before writing to it, ensuring
+no client is under the assumption that the handlerton is usable while
+it is being brought offline.
+
+== Implementation ==
+
+tokudb_hton_init_func 
+{
+    grab_hton_init_writelock();
+    ...
+    tokudb_hton_initialized = 1;
+error:
+    release_hton_init_writelock();
+}
+
+tokudb_hton_done_func
+{
+    grab_hton_init_writelock();
+    ...
+    tokudb_hton_initialized = 0;
+    release_hton_init_writelock();
+}
+
+tokudb_user_data_init_func
+{
+    grab_hton_init_readlock();
+    ...
+    release_hton_init_readlock();
+}
+
+tokudb_user_data_fill
+{
+    grab_hton_init_readlock();
+    if (!tokudb_hton_initialized) {
+        return error;
+    }
+    ...
+error:
+    release_hton_init_readlock();
+}
+
+tokudb_user_data_done_func
+{
+    grab_hton_init_readlock();
+    ...
+    release_hton_init_readlock();
+}
+
+