bk commit into 4.0 tree (1.1484)

Below is the list of changes that have just been committed into a local
4.0 repository of monty. When monty does a push these changes will
be propagated to the main repository and, within 24 hours after the
push, to the public repository.
For information on how to access the public repository
see http://www.mysql.com/doc/I/n/Installing_source_tree.html

ChangeSet
  1.1484 03/04/29 00:14:17 monty@xxxxxxxxxxxxxxx +2 -0
  Added missing dependency to VC++ project file

  VC++Files/mysql.dsw
    1.7 03/04/29 00:14:15 monty@xxxxxxxxxxxxxxx +3 -0
    Added missing dependency

  Docs/internals.texi
    1.31 03/04/29 00:14:15 monty@xxxxxxxxxxxxxxx +219 -187
    Moved code guidelines first
    Fixed texinfo nodes & menus

# This is a BitKeeper patch.  What follows are the unified diffs for the
# set of deltas contained in the patch.  The rest of the patch, the part
# that BitKeeper cares about, is below these diffs.
# User: monty
# Host: mashka.mysql.fi
# Root: /home/my/mysql-4.0

--- 1.30/Docs/internals.texi    Mon Apr 28 16:59:01 2003
+++ 1.31/Docs/internals.texi    Tue Apr 29 00:14:15 2003
@@ -43,18 +43,18 @@
 @page
 @end titlepage
 
-@node Top, caching, (dir), (dir)
+@node Top, coding guidelines, (dir), (dir)
 
 @ifinfo
 This is a manual about @strong{MySQL} internals.
 @end ifinfo
 
 @menu
+* coding guidelines::           Coding Guidelines
 * caching::                     How MySQL Handles Caching
-* join_buffer_size::
+* join_buffer_size::            
 * flush tables::                How MySQL Handles @code{FLUSH TABLES}
-* filesort::                    How MySQL Does Sorting (@code{filesort})
-* coding guidelines::           Coding Guidelines
+* Algorithms::                  
 * mysys functions::             Functions In The @code{mysys} Library
 * DBUG::                        DBUG Tags To Use
 * protocol::                    MySQL Client/Server Protocol
@@ -67,7 +67,167 @@
 @end menu
 
 
-@node caching, join_buffer_size, Top, Top
+@node coding guidelines, caching, Top, Top
+@chapter Coding Guidelines
+
+@itemize @bullet
+
+@item
+We use @uref{http://www.bitkeeper.com/, BitKeeper} for source management.
+
+@item
+You should use the @strong{MySQL} 4.0 source for all developments.
+
+@item
+If you have any questions about the @strong{MySQL} source, you can post these
+to @email{dev-public@@mysql.com} and we will answer them.  Please
+remember to not use this internal email list in public!
+
+@item
+Try to write code in a lot of black boxes that can be reused or use at
+least a clean, easy to change interface.
+
+@item
+Reuse code;  There is already a lot of algorithms in MySQL for list handling,
+queues, dynamic and hashed arrays, sorting, etc. that can be reused.
+
+@item
+Use the @code{my_*} functions like @code{my_read()}/@code{my_write()}/
+@code{my_malloc()} that you can find in the @code{mysys} library instead 
+of the direct system calls;  This will make your code easier to debug and 
+more portable.
+
+@item
+Try to always write optimized code, so that you don't have to
+go back and rewrite it a couple of months later.  It's better to
+spend 3 times as much time designing and writing an optimal function than
+having to do it all over again later on.
+
+@item
+Avoid CPU wasteful code, even where it does not matter, so that
+you will not develop sloppy coding habits.
+
+@item
+If you can write it in fewer lines, do it (as long as the code will not
+be slower or much harder to read).
+
+@item
+Don't use two commands on the same line.
+
+@item
+Do not check the same pointer for @code{NULL} more than once.
+
+@item
+Use long function and variable names in English.  This makes your code
+easier to read. 
+
+@item
+Use @code{my_var} as opposed to @code{myVar} or @code{MyVar} (@samp{_} 
+rather than dancing SHIFT to seperate words in identifiers).
+
+@item
+Think assembly - make it easier for the compiler to optimize your code.
+
+@item
+Comment your code when you do something that someone else may think
+is not ``trivial''.
+
+@item
+Use @code{libstring} functions (in the @file{strings} directory)
+instead of standard @code{libc} string functions whenever possible.
+
+@item
+Avoid using @code{malloc()} (its REAL slow);  For memory allocations 
+that only need to live for the lifetime of one thread, one should use
+@code{sql_alloc()} instead.
+
+@item
+Before making big design decisions, please first post a summary of
+what you want to do, why you want to do it, and how you plan to do
+it.  This way we can easily provide you with feedback and also
+easily discuss it thoroughly if some other developer thinks there is better
+way to do the same thing!
+
+@item
+Class names start with a capital letter.
+
+@item
+Structure types are @code{typedef}'ed to an all-caps identifier.
+
+@item
+Any @code{#define}'s are in all-caps.
+
+@item
+Matching @samp{@{} are in the same column.
+
+@item
+Put the @samp{@{} after a @code{switch} on the same line, as this gives 
+better overall indentation for the switch statement:
+
+@example
+switch (arg) @{
+@end example
+
+@item
+In all other cases, @samp{@{} and @samp{@}} should be on their own line, except
+if there is nothing inside @samp{@{} and @samp{@}}.
+
+@item
+Have a space after @code{if}
+
+@item
+Put a space after @samp{,} for function arguments
+
+@item
+Functions return @samp{0} on success, and non-zero on error, so you can do:
+
+@example
+if(a() || b() || c()) @{ error("something went wrong"); @}
+@end example
+
+@item
+Using @code{goto} is okay if not abused.
+
+@item
+Avoid default variable initalizations, use @code{LINT_INIT()} if the
+compiler complains after making sure that there is really no way
+the variable can be used uninitialized.
+
+@item
+Do not instantiate a class if you do not have to.
+
+@item
+Use pointers rather than array indexing when operating on strings.
+
+@end itemize
+
+Suggested mode in emacs:
+
+@example
+(load "cc-mode")
+(setq c-mode-common-hook '(lambda ()
+                           (turn-on-font-lock)
+                           (setq comment-column 48)))
+(setq c-style-alist
+      (cons
+       '("MY"
+        (c-basic-offset . 2)
+        (c-comment-only-line-offset . 0)
+        (c-offsets-alist . ((statement-block-intro . +)
+                            (knr-argdecl-intro . 0)
+                            (substatement-open . 0)
+                            (label . -)
+                            (statement-cont . +)
+                            (arglist-intro . 
c-lineup-arglist-intro-after-paren)
+                            (arglist-close . c-lineup-arglist)
+                            ))
+        )
+       c-style-alist))
+(c-set-style "MY")
+(setq c-default-style "MY")
+@end example
+
+@node caching, join_buffer_size, coding guidelines, Top
 @chapter How MySQL Handles Caching
 
 @strong{MySQL} has the following caches:
@@ -181,7 +341,7 @@
 the same row combination several times into different buffers)
 @end itemize
 
-@node flush tables, filesort, join_buffer_size, Top
+@node flush tables, Algorithms, join_buffer_size, Top
 @chapter How MySQL Handles @code{FLUSH TABLES}
 
 @itemize @bullet
@@ -226,8 +386,19 @@
 
 @end itemize
 
-@node filesort, coding guidelines, flush tables, Top
-@chapter How MySQL Does Sorting (@code{filesort})
+@node Algorithms, mysys functions, flush tables, Top
+@chapter Different algoritms used in MySQL
+
+MySQL uses a lot of different algorithms.  This chapter tries to describe
+some of these:
+
+@menu
+* filesort::                    
+* bulk-insert::                 
+@end menu
+
+@node filesort, bulk-insert, Algorithms, Algorithms
+@section How MySQL Does Sorting (@code{filesort})
 
 @itemize @bullet
 
@@ -266,169 +437,20 @@
 
 @end itemize
 
+@node bulk-insert,  , filesort, Algorithms
+@section Bulk insert
 
-@node coding guidelines, mysys functions, filesort, Top
-@chapter Coding Guidelines
-
-@itemize @bullet
-
-@item
-We use @uref{http://www.bitkeeper.com/, BitKeeper} for source management.
-
-@item
-You should use the @strong{MySQL} 4.0 source for all developments.
-
-@item
-If you have any questions about the @strong{MySQL} source, you can post these
-to @email{dev-public@@mysql.com} and we will answer them.  Please
-remember to not use this internal email list in public!
-
-@item
-Try to write code in a lot of black boxes that can be reused or use at
-least a clean, easy to change interface.
-
-@item
-Reuse code;  There is already a lot of algorithms in MySQL for list handling,
-queues, dynamic and hashed arrays, sorting, etc. that can be reused.
-
-@item
-Use the @code{my_*} functions like @code{my_read()}/@code{my_write()}/
-@code{my_malloc()} that you can find in the @code{mysys} library instead 
-of the direct system calls;  This will make your code easier to debug and 
-more portable.
-
-@item
-Try to always write optimized code, so that you don't have to
-go back and rewrite it a couple of months later.  It's better to
-spend 3 times as much time designing and writing an optimal function than
-having to do it all over again later on.
-
-@item
-Avoid CPU wasteful code, even where it does not matter, so that
-you will not develop sloppy coding habits.
-
-@item
-If you can write it in fewer lines, do it (as long as the code will not
-be slower or much harder to read).
-
-@item
-Don't use two commands on the same line.
-
-@item
-Do not check the same pointer for @code{NULL} more than once.
-
-@item
-Use long function and variable names in English.  This makes your code
-easier to read. 
-
-@item
-Use @code{my_var} as opposed to @code{myVar} or @code{MyVar} (@samp{_} 
-rather than dancing SHIFT to seperate words in identifiers).
-
-@item
-Think assembly - make it easier for the compiler to optimize your code.
-
-@item
-Comment your code when you do something that someone else may think
-is not ``trivial''.
-
-@item
-Use @code{libstring} functions (in the @file{strings} directory)
-instead of standard @code{libc} string functions whenever possible.
-
-@item
-Avoid using @code{malloc()} (its REAL slow);  For memory allocations 
-that only need to live for the lifetime of one thread, one should use
-@code{sql_alloc()} instead.
-
-@item
-Before making big design decisions, please first post a summary of
-what you want to do, why you want to do it, and how you plan to do
-it.  This way we can easily provide you with feedback and also
-easily discuss it thoroughly if some other developer thinks there is better
-way to do the same thing!
-
-@item
-Class names start with a capital letter.
-
-@item
-Structure types are @code{typedef}'ed to an all-caps identifier.
-
-@item
-Any @code{#define}'s are in all-caps.
-
-@item
-Matching @samp{@{} are in the same column.
-
-@item
-Put the @samp{@{} after a @code{switch} on the same line, as this gives 
-better overall indentation for the switch statement:
-
-@example
-switch (arg) @{
-@end example
-
-@item
-In all other cases, @samp{@{} and @samp{@}} should be on their own line, except
-if there is nothing inside @samp{@{} and @samp{@}}.
-
-@item
-Have a space after @code{if}
-
-@item
-Put a space after @samp{,} for function arguments
-
-@item
-Functions return @samp{0} on success, and non-zero on error, so you can do:
-
-@example
-if(a() || b() || c()) @{ error("something went wrong"); @}
-@end example
-
-@item
-Using @code{goto} is okay if not abused.
-
-@item
-Avoid default variable initalizations, use @code{LINT_INIT()} if the
-compiler complains after making sure that there is really no way
-the variable can be used uninitialized.
-
-@item
-Do not instantiate a class if you do not have to.
-
-@item
-Use pointers rather than array indexing when operating on strings.
-
-@end itemize
-
-Suggested mode in emacs:
-
-@example
-(load "cc-mode")
-(setq c-mode-common-hook '(lambda ()
-                           (turn-on-font-lock)
-                           (setq comment-column 48)))
-(setq c-style-alist
-      (cons
-       '("MY"
-        (c-basic-offset . 2)
-        (c-comment-only-line-offset . 0)
-        (c-offsets-alist . ((statement-block-intro . +)
-                            (knr-argdecl-intro . 0)
-                            (substatement-open . 0)
-                            (label . -)
-                            (statement-cont . +)
-                            (arglist-intro . 
c-lineup-arglist-intro-after-paren)
-                            (arglist-close . c-lineup-arglist)
-                            ))
-        )
-       c-style-alist))
-(c-set-style "MY")
-(setq c-default-style "MY")
-@end example
+Logic behind bulk insert optimisation is simple.
 
+Instead of writing each key value to b-tree (that is to keycache, but
+bulk insert code doesn't know about keycache) keys are stored in
+balanced binary (red-black) tree, in memory. When this tree reaches its
+memory limit it's writes all keys to disk (to keycache, that is).  But
+as key stream coming from the binary tree is already sorted inserting
+goes much faster, all the necessary pages are already in cache, disk
+access is minimized, etc.
 
-@node mysys functions, DBUG, coding guidelines, Top
+@node mysys functions, DBUG, Algorithms, Top
 @chapter Functions In The @code{mysys} Library
 
 Functions in @code{mysys}: (For flags see @file{my_sys.h})
@@ -624,6 +646,16 @@
 * fieldtype codes::             
 * protocol functions::          
 * protocol version 2::          
+* 4.1 protocol changes::        
+* 4.1 field packet::            
+* 4.1 field desc::              
+* 4.1 ok packet::               
+* 4.1 end packet::              
+* 4.1 error packet::            
+* 4.1 prep init::               
+* 4.1 long data::               
+* 4.1 execute::                 
+* 4.1 binary result::           
 @end menu
 
 @node raw packet without compression, raw packet with compression, protocol, 
protocol
@@ -690,7 +722,7 @@
 @end menu
 
 
-@node ok packet, error packet, basic packets, basic packets, basic packets
+@node ok packet, error packet, basic packets, basic packets
 @subsection OK Packet
 
 For details, see @file{sql/net_pkg.cc::send_ok()}.
@@ -720,7 +752,7 @@
 @end table
 
 
-@node error packet,  , ok packet, basic packets, basic packets
+@node error packet,  , ok packet, basic packets
 @subsection Error Packet       
 
 @example
@@ -835,7 +867,7 @@
                n data
 @end example
  
-@node fieldtype codes, protocol functions, communication
+@node fieldtype codes, protocol functions, communication, protocol
 @section Fieldtype Codes
 
 @example
@@ -859,7 +891,7 @@
 Date            03 0A 00 00     |01 0A                  |03 00 00 00
 @end example
 
-@node protocol functions, protocol version 2, fieldtype codes
+@node protocol functions, protocol version 2, fieldtype codes, protocol
 @section Functions used to implement the protocol
 
 @c This should be merged with the above one and changed to texi format
@@ -971,7 +1003,7 @@
 server then the password is accepted.
 @end example
 
-@node protocol version 2, 4.1 protocol changes, protocol functions
+@node protocol version 2, 4.1 protocol changes, protocol functions, protocol
 @section Another description of the protocol
 
 @c This should be merged with the above one and changed to texi format.
@@ -1664,7 +1696,7 @@
 @c @node 4.1 protocol,,,
 @c @chapter MySQL 4.1 protocol
 
-@node 4.1 protocol changes, 4.1 field packet, protocol version 2
+@node 4.1 protocol changes, 4.1 field packet, protocol version 2, protocol
 @section Changes to 4.0 protocol in 4.1
 
 All basic packet handling is identical to 4.0. When communication
@@ -1699,7 +1731,7 @@
 @end itemize
 
 
-@node 4.1 field packet, 4.1 field desc, 4.1 protocol changes
+@node 4.1 field packet, 4.1 field desc, 4.1 protocol changes, protocol
 @section 4.1 field description packet
 
 The field description packet is sent as a response to a query that
@@ -1719,7 +1751,7 @@
 This packet is always followed by a field description set.
 @xref{4.1 field desc}.
 
-@node 4.1 field desc, 4.1 ok packet, 4.1 field packet
+@node 4.1 field desc, 4.1 ok packet, 4.1 field packet, protocol
 @section 4.1 field description result set
 
 The field description result set contains the meta info for a result set.
@@ -1737,7 +1769,7 @@
 @end multitable
 
 
-@node 4.1 ok packet, 4.1 end packet, 4.1 field desc
+@node 4.1 ok packet, 4.1 end packet, 4.1 field desc, protocol
 @section 4.1 ok packet
 
 The ok packet is the first that is sent as an response for a query
@@ -1763,7 +1795,7 @@
 contains a string for how many rows was inserted / deleted.
 
 
-@node 4.1 end packet, 4.1 error packet, 4.1 ok packet
+@node 4.1 end packet, 4.1 error packet, 4.1 ok packet, protocol
 @section 4.1 end packet
 
 The end packet is sent as the last packet for
@@ -1792,7 +1824,7 @@
 packet).
 
 
-@node 4.1 error packet, 4.1 prep init, 4.1 end packet
+@node 4.1 error packet, 4.1 prep init, 4.1 end packet, protocol
 @section 4.1 error packet.
 
 The error packet is sent when something goes wrong.
@@ -1809,7 +1841,7 @@
 can only start with 255 if it's an error packet.
 
 
-@node 4.1 prep init, 4.1 long data, 4.1 error packet
+@node 4.1 prep init, 4.1 long data, 4.1 error packet, protocol
 @section 4.1 prepared statement init packet
 
 This is the return packet when one sends a query with the COM_PREPARE
@@ -1843,7 +1875,7 @@
 is followed by a field description result set. @xref{4.1 field desc}.
 
 
-@node 4.1 long data, 4.1 execute, 4.1 prep init
+@node 4.1 long data, 4.1 execute, 4.1 prep init, protocol
 @section 4.1 long data handling
 
 This is used by mysql_send_long_data() to set any parameter to a string
@@ -1870,7 +1902,7 @@
 responce for this.  If there is any errors (like to big string), one
 will get the error when calling execute.
 
-@node 4.1 execute, 4.1 binary result, 4.1 long data
+@node 4.1 execute, 4.1 binary result, 4.1 long data, protocol
 @section 4.1 execute
 
 On execute we send all parameters to the server in a COM_EXECUTE
@@ -1908,7 +1940,7 @@
 The result for this will be either an ok packet or a binary result
 set.
 
-@node 4.1 binary result, , 4.1 execute
+@node 4.1 binary result,  , 4.1 execute, protocol
 @section 4.1 binary result set
 
 A binary result are sent the following way.
@@ -2384,7 +2416,7 @@
 /myisam/mi_dynrec.c, and /myisam/mi_packrec.c.
 @*
 
-@node InnoDB Record Structure,InnoDB Page Structure,MyISAM Record Structure,Top
+@node InnoDB Record Structure, InnoDB Page Structure, MyISAM Record Structure, 
Top
 @chapter InnoDB Record Structure
 
 This page contains:
@@ -2690,7 +2722,7 @@
 The most relevant InnoDB source-code files are rem0rec.c, rem0rec.ic,
 and rem0rec.h in the rem ("Record Manager") directory.
 
-@node InnoDB Page Structure,Files in MySQL Sources,InnoDB Record Structure,Top
+@node InnoDB Page Structure, Files in MySQL Sources, InnoDB Record Structure, 
Top
 @chapter InnoDB Page Structure
 
 InnoDB stores all records inside a fixed-size unit which is commonly called a
@@ -3121,7 +3153,7 @@
 The most relevant InnoDB source-code files are page0page.c,
 page0page.ic, and page0page.h in \page directory.
 
-@node Files in MySQL Sources,Files in InnoDB Sources,InnoDB Page Structure,Top
+@node Files in MySQL Sources, Files in InnoDB Sources, InnoDB Page Structure, 
Top
 @chapter Annotated List Of Files in the MySQL Source Code Distribution
 
 This is a description of the files that you get when you download the
@@ -4942,7 +4974,7 @@
 for packet compression. The client sends messages to the server which
 are compressed by zlib. See also: \sql\net_serv.cc.
 
-@node Files in InnoDB Sources,,Files in MySQL Sources,Top
+@node Files in InnoDB Sources,  , Files in MySQL Sources, Top
 @chapter Annotated List Of Files in the InnoDB Source Code Distribution
 
 ERRATUM BY HEIKKI TUURI (START)

--- 1.6/VC++Files/mysql.dsw     Fri Feb 28 22:23:58 2003
+++ 1.7/VC++Files/mysql.dsw     Tue Apr 29 00:14:15 2003
@@ -605,6 +605,9 @@
 
 Package=<4>
 {{{
+    Begin Project Dependency
+    Project_Dep_Name strings
+    End Project Dependency
 }}}
 
 ###############################################################################

-- 
MySQL Internals Mailing List
For list archives: http://lists.mysql.com/internals
To unsubscribe:    
http://lists.mysql.com/internals?unsub=gcdmd-internals@xxxxxxxxxxx