diff options
author | unknown <monty@mashka.mysql.fi> | 2003-04-29 00:14:17 +0300 |
---|---|---|
committer | unknown <monty@mashka.mysql.fi> | 2003-04-29 00:14:17 +0300 |
commit | 3d12a41d67481a04a218c38c1ac90a2abbe3828a (patch) | |
tree | 1432449356385662f41f8737add8bc8bbc733850 /Docs | |
parent | 749c0fe97f57aca710bf0a9033f7ed5c0afd80d9 (diff) | |
download | mariadb-git-3d12a41d67481a04a218c38c1ac90a2abbe3828a.tar.gz |
Added missing dependency to VC++ project file
Docs/internals.texi:
Moved code guidelines first
Fixed texinfo nodes & menus
VC++Files/mysql.dsw:
Added missing dependency
Diffstat (limited to 'Docs')
-rw-r--r-- | Docs/internals.texi | 406 |
1 files changed, 219 insertions, 187 deletions
diff --git a/Docs/internals.texi b/Docs/internals.texi index 66d04b006ff..270fe9e2249 100644 --- a/Docs/internals.texi +++ b/Docs/internals.texi @@ -43,18 +43,18 @@ END-INFO-DIR-ENTRY @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 @@ This is a manual about @strong{MySQL} internals. @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 @@ same algorithm described above to handle it. (In other words, we store 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 @@ After this it will give other threads a chance to open the same tables. @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 @@ and then we read the rows in the sorted order into a row buffer @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 @@ Print query. * 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 @@ is the header of the packet. @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 @@ For details, see @file{sql/net_pkg.cc::send_ok()}. @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 @@ For details, see @file{sql/net_pkg.cc::send_ok()}. 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 @@ Time 03 08 00 00 |01 0B |03 00 00 00 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 @@ client. If this is equal to the new message the client sends to the 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 @@ fe 00 . . @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 @@ results will sent as binary (low-byte-first). @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 @@ uses this to send the number of rows in the table) 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 @@ The field description result set contains the meta info for a result set. @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 @@ The message is optional. For example for multi line INSERT it 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 @@ by checking the packet length < 9 bytes (in which case it's and end 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 @@ The client/server protocol is designed in such a way that a packet 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 @@ prepared statement will contain a result set. In this case the packet 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 @@ The server will NOT send an @code{ok} or @code{error} packet in 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 parameters are stored the following ways: 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 @@ work for different record formats are: /myisam/mi_statrec.c, /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 @@ shorter because the NULLs take no space. 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 @@ header. 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 @@ The MySQL program that uses zlib is \mysys\my_compress.c. The use is 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) |