maria-docs team mailing list archive

[Daniel Bartholomew <dbart@xxxxxxxxxxxx>]

Hello everyone,

Summarizing from my previous email: I'm working on the documentation for
the Segmented Key Cache, one of the new features in MariaDB 5.2. My
previous email was about the "About" section of the documentation. This
email is about the "Syntax" section.

For the syntax section, I see there is one new global variable defined
for this feature and a new KEY_CACHES table in the information_schema
database. Are there any other user-visible items which should be
mentioned?

Here is a first draft of the syntax section:

----------------------------------------------------------------------

== Segmented Key Cache Syntax ==

New global variable: key_cache_partitions, it sets the number of
segments in a key cache. Valid values for this variable are whole
numbers between 0 and 64. If the number of partitions is set to a number
greater than 64 the number of partitions will be truncated to 64 and a
warning will be issued.

A value of '0' means the key cache is a regular (i.e. non-segmented)
key cache. This is the default.

Other global variables used when working with regular key caches also
apply to segmented key caches: key_buffer_size,
key_cache_age_threshold, key_cache_block_size, and
key_cache_division_limit. See the MySQL manual for descriptions of
these variables.
http://dev.mysql.com/doc/refman/5.1/en/server-system-variables.html

Statistics about the key cache can be found by looking at the
KEY_CACHES table in the INFORMATION_SCHEMA database. Columns in this
table are:

* KEY_CACHE_NAME: The name of the key cache
* PARTITIONS: total number of segments
* PARTITION_NUMBER: segment number (set to NULL if a simple key cache)
* FULL_SIZE: memory for cache buffers/auxiliary structures
* BLOCK_SIZE: size of the blocks
* USED_BLOCKS: number of currently used blocks
* UNUSED_BLOCKS: number of currently unused blocks
* DIRTY_BLOCKS: number of currently dirty blocks
* READ_REQUESTS: number of read requests
* READS: number of actual reads from files into buffers
* WRITE_REQUESTS: number of write requests
* WRITES: number of actual writes from buffers into files

----------------------------------------------------------------------

If there are any factual errors with the above, let me know.
Improvements and suggestions are also welcome.

Question for the developers: A key_cache_partitions value of '0' means
the key cache will not be segmented, it will be a regular (or simple)
key cache. A value of '1' means the key cache will be a segmented key
cache with a single segment. Is there any benefit to having a
"single-segment segmented key cache" compared to a regular "simple key
cache" or are they practically the same thing?

The key_cache_partitions variable also needs to be documented on the
Server System Variables page
(http://askmonty.org/wiki/Manual:Server_System_Variables). The entry
will look something like this:

----------------------------------------------------------------------
* <code>key_cache_partitions</code>
** '''Description:''' The number of segments in a key cache.
** '''Commandline:''' <code>--key_cache_partitions=#</code>
** '''Scope:''' Global
** '''Dynamic:''' No
** '''Type:''' number
** '''Valid values:''' <code>0-64</code>
** '''Default value:''' <code>0</code> ''(non-segmented)''
* '''Introduced:''' MariaDB 5.2
----------------------------------------------------------------------

Let me know if there is anything wrong with the above.

My task now is to come up with some examples. I'll probably use the
test cases for inspiration unless someone has an awesome segmented key
cache example that they've been dying to share with me. :)

Thanks.

-- 
Daniel Bartholomew
Monty Program - http://askmonty.org