diff options
Diffstat (limited to 'src/docs')
54 files changed, 6301 insertions, 0 deletions
diff --git a/src/docs/Doxyfile b/src/docs/Doxyfile new file mode 100644 index 00000000000..47ebbab6e60 --- /dev/null +++ b/src/docs/Doxyfile @@ -0,0 +1,1782 @@ +# Doxyfile 1.7.4 + +# This file describes the settings to be used by the documentation system +# doxygen (www.doxygen.org) for a project +# +# All text after a hash (#) is considered a comment and will be ignored +# The format is: +# TAG = value [value, ...] +# For lists items can also be appended using: +# TAG += value [value, ...] +# Values that contain spaces should be placed between quotes (" ") + +#--------------------------------------------------------------------------- +# Project related configuration options +#--------------------------------------------------------------------------- + +# This tag specifies the encoding used for all characters in the config file +# that follow. The default is UTF-8 which is also the encoding used for all +# text before the first occurrence of this tag. Doxygen uses libiconv (or the +# iconv built into libc) for the transcoding. See +# http://www.gnu.org/software/libiconv for the list of possible encodings. + +DOXYFILE_ENCODING = UTF-8 + +# The PROJECT_NAME tag is a single word (or a sequence of words surrounded +# by quotes) that should identify the project. + +PROJECT_NAME = WiredTiger + +# The PROJECT_NUMBER tag can be used to enter a project or revision number. +# This could be handy for archiving the generated documentation or +# if some version control system is used. + +PROJECT_NUMBER = "Version 1.0" + +# Using the PROJECT_BRIEF tag one can provide an optional one line description +# for a project that appears at the top of each page and should give viewer +# a quick idea about the purpose of the project. Keep the description short. + +PROJECT_BRIEF = + +# With the PROJECT_LOGO tag one can specify an logo or icon that is +# included in the documentation. The maximum height of the logo should not +# exceed 55 pixels and the maximum width should not exceed 200 pixels. +# Doxygen will copy the logo to the output directory. + +PROJECT_LOGO = images/LogoFinal-header.png + +# The OUTPUT_DIRECTORY tag is used to specify the (relative or absolute) +# base path where the generated documentation will be put. +# If a relative path is entered, it will be relative to the location +# where doxygen was started. If left blank the current directory will be used. + +OUTPUT_DIRECTORY = ../../docs + +# If the CREATE_SUBDIRS tag is set to YES, then doxygen will create +# 4096 sub-directories (in 2 levels) under the output directory of each output +# format and will distribute the generated files over these directories. +# Enabling this option can be useful when feeding doxygen a huge amount of +# source files, where putting all generated files in the same directory would +# otherwise cause performance problems for the file system. + +CREATE_SUBDIRS = NO + +# The OUTPUT_LANGUAGE tag is used to specify the language in which all +# documentation generated by doxygen is written. Doxygen will use this +# information to generate all constant output in the proper language. +# The default language is English, other supported languages are: +# Afrikaans, Arabic, Brazilian, Catalan, Chinese, Chinese-Traditional, +# Croatian, Czech, Danish, Dutch, Esperanto, Farsi, Finnish, French, German, +# Greek, Hungarian, Italian, Japanese, Japanese-en (Japanese with English +# messages), Korean, Korean-en, Lithuanian, Norwegian, Macedonian, Persian, +# Polish, Portuguese, Romanian, Russian, Serbian, Serbian-Cyrillic, Slovak, +# Slovene, Spanish, Swedish, Ukrainian, and Vietnamese. + +OUTPUT_LANGUAGE = English + +# If the BRIEF_MEMBER_DESC tag is set to YES (the default) Doxygen will +# include brief member descriptions after the members that are listed in +# the file and class documentation (similar to JavaDoc). +# Set to NO to disable this. + +BRIEF_MEMBER_DESC = YES + +# If the REPEAT_BRIEF tag is set to YES (the default) Doxygen will prepend +# the brief description of a member or function before the detailed description. +# Note: if both HIDE_UNDOC_MEMBERS and BRIEF_MEMBER_DESC are set to NO, the +# brief descriptions will be completely suppressed. + +REPEAT_BRIEF = YES + +# This tag implements a quasi-intelligent brief description abbreviator +# that is used to form the text in various listings. Each string +# in this list, if found as the leading text of the brief description, will be +# stripped from the text and the result after processing the whole list, is +# used as the annotated text. Otherwise, the brief description is used as-is. +# If left blank, the following values are used ("$name" is automatically +# replaced with the name of the entity): "The $name class" "The $name widget" +# "The $name file" "is" "provides" "specifies" "contains" +# "represents" "a" "an" "the" + +ABBREVIATE_BRIEF = "The $name class" \ + "The $name widget" \ + "The $name file" \ + is \ + provides \ + specifies \ + contains \ + represents \ + a \ + an \ + the + +# If the ALWAYS_DETAILED_SEC and REPEAT_BRIEF tags are both set to YES then +# Doxygen will generate a detailed section even if there is only a brief +# description. + +ALWAYS_DETAILED_SEC = NO + +# If the INLINE_INHERITED_MEMB tag is set to YES, doxygen will show all +# inherited members of a class in the documentation of that class as if those +# members were ordinary class members. Constructors, destructors and assignment +# operators of the base classes will not be shown. + +INLINE_INHERITED_MEMB = NO + +# If the FULL_PATH_NAMES tag is set to YES then Doxygen will prepend the full +# path before files name in the file list and in the header files. If set +# to NO the shortest path that makes the file name unique will be used. + +FULL_PATH_NAMES = NO + +# If the FULL_PATH_NAMES tag is set to YES then the STRIP_FROM_PATH tag +# can be used to strip a user-defined part of the path. Stripping is +# only done if one of the specified strings matches the left-hand part of +# the path. The tag can be used to show relative paths in the file list. +# If left blank the directory from which doxygen is run is used as the +# path to strip. + +STRIP_FROM_PATH = + +# The STRIP_FROM_INC_PATH tag can be used to strip a user-defined part of +# the path mentioned in the documentation of a class, which tells +# the reader which header file to include in order to use a class. +# If left blank only the name of the header file containing the class +# definition is used. Otherwise one should specify the include paths that +# are normally passed to the compiler using the -I flag. + +STRIP_FROM_INC_PATH = ../include/ + +# If the SHORT_NAMES tag is set to YES, doxygen will generate much shorter +# (but less readable) file names. This can be useful if your file system +# doesn't support long names like on DOS, Mac, or CD-ROM. + +SHORT_NAMES = NO + +# If the JAVADOC_AUTOBRIEF tag is set to YES then Doxygen +# will interpret the first line (until the first dot) of a JavaDoc-style +# comment as the brief description. If set to NO, the JavaDoc +# comments will behave just like regular Qt-style comments +# (thus requiring an explicit @brief command for a brief description.) + +JAVADOC_AUTOBRIEF = YES + +# If the QT_AUTOBRIEF tag is set to YES then Doxygen will +# interpret the first line (until the first dot) of a Qt-style +# comment as the brief description. If set to NO, the comments +# will behave just like regular Qt-style comments (thus requiring +# an explicit \brief command for a brief description.) + +QT_AUTOBRIEF = YES + +# The MULTILINE_CPP_IS_BRIEF tag can be set to YES to make Doxygen +# treat a multi-line C++ special comment block (i.e. a block of //! or /// +# comments) as a brief description. This used to be the default behaviour. +# The new default is to treat a multi-line C++ comment block as a detailed +# description. Set this tag to YES if you prefer the old behaviour instead. + +MULTILINE_CPP_IS_BRIEF = NO + +# If the INHERIT_DOCS tag is set to YES (the default) then an undocumented +# member inherits the documentation from any documented member that it +# re-implements. + +INHERIT_DOCS = YES + +# If the SEPARATE_MEMBER_PAGES tag is set to YES, then doxygen will produce +# a new page for each member. If set to NO, the documentation of a member will +# be part of the file/class/namespace that contains it. + +SEPARATE_MEMBER_PAGES = NO + +# The TAB_SIZE tag can be used to set the number of spaces in a tab. +# Doxygen uses this value to replace tabs by spaces in code fragments. + +TAB_SIZE = 8 + +# This tag can be used to specify a number of aliases that acts +# as commands in the documentation. An alias has the form "name=value". +# For example adding "sideeffect=\par Side Effects:\n" will allow you to +# put the command \sideeffect (or @sideeffect) in the documentation, which +# will result in a user-defined paragraph with heading "Side Effects:". +# You can put \n's in the value part of an alias to insert newlines. + +ALIASES = "notyet{1}=<b>Not yet supported in WiredTiger.</b>\n@todo fix when \1 supported\n\n" \ + "errors=@returns zero on success and a non-zero error code on failure. See @ref error_returns \"Error Returns\" for details." \ + "ex_ref{1}=@ref \1 \"\1\"" \ + "hrow{1}=<tr><th>\1</th></tr>" \ + "hrow{2}=<tr><th>\1</th><th>\2</th></tr>" \ + "hrow{3}=<tr><th>\1</th><th>\2</th><th>\3</th></tr>" \ + "hrow{4}=<tr><th>\1</th><th>\2</th><th>\3</th><th>\4</th></tr>" \ + "hrow{5}=<tr><th>\1</th><th>\2</th><th>\3</th><th>\4</th><th>\5</th></tr>" \ + "row{1}=<tr><td>\1</td></tr>" \ + "row{2}=<tr><td>\1</td><td>\2</td></tr>" \ + "row{3}=<tr><td>\1</td><td>\2</td><td>\3</td></tr>" \ + "row{4}=<tr><td>\1</td><td>\2</td><td>\3</td><td>\4</td></tr>" \ + "row{5}=<tr><td>\1</td><td>\2</td><td>\3</td><td>\4</td><td>\5</td></tr>" \ + "configstart{2}=@param config\n Configuration string, see @ref config_strings. Permitted values:\n <table>@hrow{Name,Effect,Values}" \ + "config{3}= @row{<tt>\1</tt>,\2,\3}" \ + "configend= </table>" \ + "configempty{2}=@param config\n Configuration string, see @ref config_strings. No values currently permitted." + +# Set the OPTIMIZE_OUTPUT_FOR_C tag to YES if your project consists of C +# sources only. Doxygen will then generate output that is more tailored for C. +# For instance, some of the names that are used will be different. The list +# of all members will be omitted, etc. + +OPTIMIZE_OUTPUT_FOR_C = NO + +# Set the OPTIMIZE_OUTPUT_JAVA tag to YES if your project consists of Java +# sources only. Doxygen will then generate output that is more tailored for +# Java. For instance, namespaces will be presented as packages, qualified +# scopes will look different, etc. + +OPTIMIZE_OUTPUT_JAVA = YES + +# Set the OPTIMIZE_FOR_FORTRAN tag to YES if your project consists of Fortran +# sources only. Doxygen will then generate output that is more tailored for +# Fortran. + +OPTIMIZE_FOR_FORTRAN = NO + +# Set the OPTIMIZE_OUTPUT_VHDL tag to YES if your project consists of VHDL +# sources. Doxygen will then generate output that is tailored for +# VHDL. + +OPTIMIZE_OUTPUT_VHDL = NO + +# Doxygen selects the parser to use depending on the extension of the files it +# parses. With this tag you can assign which parser to use for a given extension. +# Doxygen has a built-in mapping, but you can override or extend it using this +# tag. The format is ext=language, where ext is a file extension, and language +# is one of the parsers supported by doxygen: IDL, Java, Javascript, CSharp, C, +# C++, D, PHP, Objective-C, Python, Fortran, VHDL, C, C++. For instance to make +# doxygen treat .inc files as Fortran files (default is PHP), and .f files as C +# (default is Fortran), use: inc=Fortran f=C. Note that for custom extensions +# you also need to set FILE_PATTERNS otherwise the files are not read by doxygen. + +EXTENSION_MAPPING = + +# If you use STL classes (i.e. std::string, std::vector, etc.) but do not want +# to include (a tag file for) the STL sources as input, then you should +# set this tag to YES in order to let doxygen match functions declarations and +# definitions whose arguments contain STL classes (e.g. func(std::string); v.s. +# func(std::string) {}). This also makes the inheritance and collaboration +# diagrams that involve STL classes more complete and accurate. + +BUILTIN_STL_SUPPORT = NO + +# If you use Microsoft's C++/CLI language, you should set this option to YES to +# enable parsing support. + +CPP_CLI_SUPPORT = NO + +# Set the SIP_SUPPORT tag to YES if your project consists of sip sources only. +# Doxygen will parse them like normal C++ but will assume all classes use public +# instead of private inheritance when no explicit protection keyword is present. + +SIP_SUPPORT = NO + +# For Microsoft's IDL there are propget and propput attributes to indicate getter +# and setter methods for a property. Setting this option to YES (the default) +# will make doxygen replace the get and set methods by a property in the +# documentation. This will only work if the methods are indeed getting or +# setting a simple type. If this is not the case, or you want to show the +# methods anyway, you should set this option to NO. + +IDL_PROPERTY_SUPPORT = YES + +# If member grouping is used in the documentation and the DISTRIBUTE_GROUP_DOC +# tag is set to YES, then doxygen will reuse the documentation of the first +# member in the group (if any) for the other members of the group. By default +# all members of a group must be documented explicitly. + +DISTRIBUTE_GROUP_DOC = NO + +# Set the SUBGROUPING tag to YES (the default) to allow class member groups of +# the same type (for instance a group of public functions) to be put as a +# subgroup of that type (e.g. under the Public Functions section). Set it to +# NO to prevent subgrouping. Alternatively, this can be done per class using +# the \nosubgrouping command. + +SUBGROUPING = YES + +# When the INLINE_GROUPED_CLASSES tag is set to YES, classes, structs and +# unions are shown inside the group in which they are included (e.g. using +# @ingroup) instead of on a separate page (for HTML and Man pages) or +# section (for LaTeX and RTF). + +INLINE_GROUPED_CLASSES = NO + +# When TYPEDEF_HIDES_STRUCT is enabled, a typedef of a struct, union, or enum +# is documented as struct, union, or enum with the name of the typedef. So +# typedef struct TypeS {} TypeT, will appear in the documentation as a struct +# with name TypeT. When disabled the typedef will appear as a member of a file, +# namespace, or class. And the struct will be named TypeS. This can typically +# be useful for C code in case the coding convention dictates that all compound +# types are typedef'ed and only the typedef is referenced, never the tag name. + +TYPEDEF_HIDES_STRUCT = YES + +# The SYMBOL_CACHE_SIZE determines the size of the internal cache use to +# determine which symbols to keep in memory and which to flush to disk. +# When the cache is full, less often used symbols will be written to disk. +# For small to medium size projects (<1000 input files) the default value is +# probably good enough. For larger projects a too small cache size can cause +# doxygen to be busy swapping symbols to and from disk most of the time +# causing a significant performance penalty. +# If the system has enough physical memory increasing the cache will improve the +# performance by keeping more symbols in memory. Note that the value works on +# a logarithmic scale so increasing the size by one will roughly double the +# memory usage. The cache size is given by this formula: +# 2^(16+SYMBOL_CACHE_SIZE). The valid range is 0..9, the default is 0, +# corresponding to a cache size of 2^16 = 65536 symbols + +SYMBOL_CACHE_SIZE = 0 + +#--------------------------------------------------------------------------- +# Build related configuration options +#--------------------------------------------------------------------------- + +# If the EXTRACT_ALL tag is set to YES doxygen will assume all entities in +# documentation are documented, even if no documentation was available. +# Private class members and static file members will be hidden unless +# the EXTRACT_PRIVATE and EXTRACT_STATIC tags are set to YES + +EXTRACT_ALL = NO + +# If the EXTRACT_PRIVATE tag is set to YES all private members of a class +# will be included in the documentation. + +EXTRACT_PRIVATE = NO + +# If the EXTRACT_STATIC tag is set to YES all static members of a file +# will be included in the documentation. + +EXTRACT_STATIC = NO + +# If the EXTRACT_LOCAL_CLASSES tag is set to YES classes (and structs) +# defined locally in source files will be included in the documentation. +# If set to NO only classes defined in header files are included. + +EXTRACT_LOCAL_CLASSES = YES + +# This flag is only useful for Objective-C code. When set to YES local +# methods, which are defined in the implementation section but not in +# the interface are included in the documentation. +# If set to NO (the default) only methods in the interface are included. + +EXTRACT_LOCAL_METHODS = NO + +# If this flag is set to YES, the members of anonymous namespaces will be +# extracted and appear in the documentation as a namespace called +# 'anonymous_namespace{file}', where file will be replaced with the base +# name of the file that contains the anonymous namespace. By default +# anonymous namespaces are hidden. + +EXTRACT_ANON_NSPACES = NO + +# If the HIDE_UNDOC_MEMBERS tag is set to YES, Doxygen will hide all +# undocumented members of documented classes, files or namespaces. +# If set to NO (the default) these members will be included in the +# various overviews, but no documentation section is generated. +# This option has no effect if EXTRACT_ALL is enabled. + +HIDE_UNDOC_MEMBERS = NO + +# If the HIDE_UNDOC_CLASSES tag is set to YES, Doxygen will hide all +# undocumented classes that are normally visible in the class hierarchy. +# If set to NO (the default) these classes will be included in the various +# overviews. This option has no effect if EXTRACT_ALL is enabled. + +HIDE_UNDOC_CLASSES = NO + +# If the HIDE_FRIEND_COMPOUNDS tag is set to YES, Doxygen will hide all +# friend (class|struct|union) declarations. +# If set to NO (the default) these declarations will be included in the +# documentation. + +HIDE_FRIEND_COMPOUNDS = NO + +# If the HIDE_IN_BODY_DOCS tag is set to YES, Doxygen will hide any +# documentation blocks found inside the body of a function. +# If set to NO (the default) these blocks will be appended to the +# function's detailed documentation block. + +HIDE_IN_BODY_DOCS = NO + +# The INTERNAL_DOCS tag determines if documentation +# that is typed after a \internal command is included. If the tag is set +# to NO (the default) then the documentation will be excluded. +# Set it to YES to include the internal documentation. + +INTERNAL_DOCS = NO + +# If the CASE_SENSE_NAMES tag is set to NO then Doxygen will only generate +# file names in lower-case letters. If set to YES upper-case letters are also +# allowed. This is useful if you have classes or files whose names only differ +# in case and if your file system supports case sensitive file names. Windows +# and Mac users are advised to set this option to NO. + +CASE_SENSE_NAMES = NO + +# If the HIDE_SCOPE_NAMES tag is set to NO (the default) then Doxygen +# will show members with their full class and namespace scopes in the +# documentation. If set to YES the scope will be hidden. + +HIDE_SCOPE_NAMES = NO + +# If the SHOW_INCLUDE_FILES tag is set to YES (the default) then Doxygen +# will put a list of the files that are included by a file in the documentation +# of that file. + +SHOW_INCLUDE_FILES = NO + +# If the FORCE_LOCAL_INCLUDES tag is set to YES then Doxygen +# will list include files with double quotes in the documentation +# rather than with sharp brackets. + +FORCE_LOCAL_INCLUDES = NO + +# If the INLINE_INFO tag is set to YES (the default) then a tag [inline] +# is inserted in the documentation for inline members. + +INLINE_INFO = YES + +# If the SORT_MEMBER_DOCS tag is set to YES (the default) then doxygen +# will sort the (detailed) documentation of file and class members +# alphabetically by member name. If set to NO the members will appear in +# declaration order. + +SORT_MEMBER_DOCS = YES + +# If the SORT_BRIEF_DOCS tag is set to YES then doxygen will sort the +# brief documentation of file, namespace and class members alphabetically +# by member name. If set to NO (the default) the members will appear in +# declaration order. + +SORT_BRIEF_DOCS = NO + +# If the SORT_MEMBERS_CTORS_1ST tag is set to YES then doxygen +# will sort the (brief and detailed) documentation of class members so that +# constructors and destructors are listed first. If set to NO (the default) +# the constructors will appear in the respective orders defined by +# SORT_MEMBER_DOCS and SORT_BRIEF_DOCS. +# This tag will be ignored for brief docs if SORT_BRIEF_DOCS is set to NO +# and ignored for detailed docs if SORT_MEMBER_DOCS is set to NO. + +SORT_MEMBERS_CTORS_1ST = NO + +# If the SORT_GROUP_NAMES tag is set to YES then doxygen will sort the +# hierarchy of group names into alphabetical order. If set to NO (the default) +# the group names will appear in their defined order. + +SORT_GROUP_NAMES = YES + +# If the SORT_BY_SCOPE_NAME tag is set to YES, the class list will be +# sorted by fully-qualified names, including namespaces. If set to +# NO (the default), the class list will be sorted only by class name, +# not including the namespace part. +# Note: This option is not very useful if HIDE_SCOPE_NAMES is set to YES. +# Note: This option applies only to the class list, not to the +# alphabetical list. + +SORT_BY_SCOPE_NAME = YES + +# If the STRICT_PROTO_MATCHING option is enabled and doxygen fails to +# do proper type resolution of all parameters of a function it will reject a +# match between the prototype and the implementation of a member function even +# if there is only one candidate or it is obvious which candidate to choose +# by doing a simple string match. By disabling STRICT_PROTO_MATCHING doxygen +# will still accept a match between prototype and implementation in such cases. + +STRICT_PROTO_MATCHING = NO + +# The GENERATE_TODOLIST tag can be used to enable (YES) or +# disable (NO) the todo list. This list is created by putting \todo +# commands in the documentation. + +GENERATE_TODOLIST = NO + +# The GENERATE_TESTLIST tag can be used to enable (YES) or +# disable (NO) the test list. This list is created by putting \test +# commands in the documentation. + +GENERATE_TESTLIST = YES + +# The GENERATE_BUGLIST tag can be used to enable (YES) or +# disable (NO) the bug list. This list is created by putting \bug +# commands in the documentation. + +GENERATE_BUGLIST = YES + +# The GENERATE_DEPRECATEDLIST tag can be used to enable (YES) or +# disable (NO) the deprecated list. This list is created by putting +# \deprecated commands in the documentation. + +GENERATE_DEPRECATEDLIST= YES + +# The ENABLED_SECTIONS tag can be used to enable conditional +# documentation sections, marked by \if sectionname ... \endif. + +ENABLED_SECTIONS = + +# The MAX_INITIALIZER_LINES tag determines the maximum number of lines +# the initial value of a variable or macro consists of for it to appear in +# the documentation. If the initializer consists of more lines than specified +# here it will be hidden. Use a value of 0 to hide initializers completely. +# The appearance of the initializer of individual variables and macros in the +# documentation can be controlled using \showinitializer or \hideinitializer +# command in the documentation regardless of this setting. + +MAX_INITIALIZER_LINES = 0 + +# Set the SHOW_USED_FILES tag to NO to disable the list of files generated +# at the bottom of the documentation of classes and structs. If set to YES the +# list will mention the files that were used to generate the documentation. + +SHOW_USED_FILES = NO + +# If the sources in your project are distributed over multiple directories +# then setting the SHOW_DIRECTORIES tag to YES will show the directory hierarchy +# in the documentation. The default is NO. + +SHOW_DIRECTORIES = NO + +# Set the SHOW_FILES tag to NO to disable the generation of the Files page. +# This will remove the Files entry from the Quick Index and from the +# Folder Tree View (if specified). The default is YES. + +SHOW_FILES = NO + +# Set the SHOW_NAMESPACES tag to NO to disable the generation of the +# Namespaces page. This will remove the Namespaces entry from the Quick Index +# and from the Folder Tree View (if specified). The default is YES. + +SHOW_NAMESPACES = NO + +# The FILE_VERSION_FILTER tag can be used to specify a program or script that +# doxygen should invoke to get the current version for each file (typically from +# the version control system). Doxygen will invoke the program by executing (via +# popen()) the command <command> <input-file>, where <command> is the value of +# the FILE_VERSION_FILTER tag, and <input-file> is the name of an input file +# provided by doxygen. Whatever the program writes to standard output +# is used as the file version. See the manual for examples. + +FILE_VERSION_FILTER = + +# The LAYOUT_FILE tag can be used to specify a layout file which will be parsed +# by doxygen. The layout file controls the global structure of the generated +# output files in an output format independent way. The create the layout file +# that represents doxygen's defaults, run doxygen with the -l option. +# You can optionally specify a file name after the option, if omitted +# DoxygenLayout.xml will be used as the name of the layout file. + +LAYOUT_FILE = style/DoxygenLayout.xml + +#--------------------------------------------------------------------------- +# configuration options related to warning and progress messages +#--------------------------------------------------------------------------- + +# The QUIET tag can be used to turn on/off the messages that are generated +# by doxygen. Possible values are YES and NO. If left blank NO is used. + +QUIET = NO + +# The WARNINGS tag can be used to turn on/off the warning messages that are +# generated by doxygen. Possible values are YES and NO. If left blank +# NO is used. + +WARNINGS = YES + +# If WARN_IF_UNDOCUMENTED is set to YES, then doxygen will generate warnings +# for undocumented members. If EXTRACT_ALL is set to YES then this flag will +# automatically be disabled. + +WARN_IF_UNDOCUMENTED = YES + +# If WARN_IF_DOC_ERROR is set to YES, doxygen will generate warnings for +# potential errors in the documentation, such as not documenting some +# parameters in a documented function, or documenting parameters that +# don't exist or using markup commands wrongly. + +WARN_IF_DOC_ERROR = YES + +# The WARN_NO_PARAMDOC option can be enabled to get warnings for +# functions that are documented, but have no documentation for their parameters +# or return value. If set to NO (the default) doxygen will only warn about +# wrong or incomplete parameter documentation, but not about the absence of +# documentation. + +WARN_NO_PARAMDOC = YES + +# The WARN_FORMAT tag determines the format of the warning messages that +# doxygen can produce. The string should contain the $file, $line, and $text +# tags, which will be replaced by the file and line number from which the +# warning originated and the warning text. Optionally the format may contain +# $version, which will be replaced by the version of the file (if it could +# be obtained via FILE_VERSION_FILTER) + +WARN_FORMAT = "$file:$line: $text" + +# The WARN_LOGFILE tag can be used to specify a file to which warning +# and error messages should be written. If left blank the output is written +# to stderr. + +WARN_LOGFILE = doxygen.log + +#--------------------------------------------------------------------------- +# configuration options related to the input files +#--------------------------------------------------------------------------- + +# The INPUT tag can be used to specify the files and/or directories that contain +# documented source files. You may enter file names like "myfile.cpp" or +# directories like "/usr/src/myproject". Separate the files or directories +# with spaces. + +INPUT = ../include/wiredtiger.in \ + ../include/wiredtiger_ext.h \ + . + +# This tag can be used to specify the character encoding of the source files +# that doxygen parses. Internally doxygen uses the UTF-8 encoding, which is +# also the default input encoding. Doxygen uses libiconv (or the iconv built +# into libc) for the transcoding. See http://www.gnu.org/software/libiconv for +# the list of possible encodings. + +INPUT_ENCODING = UTF-8 + +# If the value of the INPUT tag contains directories, you can use the +# FILE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp +# and *.h) to filter out the source-files in the directories. If left +# blank the following patterns are tested: +# *.c *.cc *.cxx *.cpp *.c++ *.d *.java *.ii *.ixx *.ipp *.i++ *.inl *.h *.hh +# *.hxx *.hpp *.h++ *.idl *.odl *.cs *.php *.php3 *.inc *.m *.mm *.dox *.py +# *.f90 *.f *.for *.vhd *.vhdl + +FILE_PATTERNS = *.c \ + *.cc \ + *.cxx \ + *.cpp \ + *.c++ \ + *.d \ + *.java \ + *.ii \ + *.ixx \ + *.ipp \ + *.i++ \ + *.inl \ + *.h \ + *.hh \ + *.hxx \ + *.hpp \ + *.h++ \ + *.idl \ + *.odl \ + *.cs \ + *.php \ + *.php3 \ + *.inc \ + *.m \ + *.mm \ + *.dox \ + *.py \ + *.f90 \ + *.f \ + *.vhd \ + *.vhdl + +# The RECURSIVE tag can be used to turn specify whether or not subdirectories +# should be searched for input files as well. Possible values are YES and NO. +# If left blank NO is used. + +RECURSIVE = YES + +# The EXCLUDE tag can be used to specify files and/or directories that should +# excluded from the INPUT source files. This way you can easily exclude a +# subdirectory from a directory tree whose root is specified with the INPUT tag. + +EXCLUDE = \ + bdb-map.dox \ + design.dox \ + processes.dox \ + sql-map.dox \ + tools \ + top + +# The EXCLUDE_SYMLINKS tag can be used select whether or not files or +# directories that are symbolic links (a Unix file system feature) are excluded +# from the input. + +EXCLUDE_SYMLINKS = NO + +# If the value of the INPUT tag contains directories, you can use the +# EXCLUDE_PATTERNS tag to specify one or more wildcard patterns to exclude +# certain files from those directories. Note that the wildcards are matched +# against the file with absolute path, so to exclude all test directories +# for example use the pattern */test/* + +EXCLUDE_PATTERNS = + +# The EXCLUDE_SYMBOLS tag can be used to specify one or more symbol names +# (namespaces, classes, functions, etc.) that should be excluded from the +# output. The symbol name can be a fully qualified name, a word, or if the +# wildcard * is used, a substring. Examples: ANamespace, AClass, +# AClass::ANamespace, ANamespace::*Test + +EXCLUDE_SYMBOLS = __F + +# The EXAMPLE_PATH tag can be used to specify one or more files or +# directories that contain example code fragments that are included (see +# the \include command). + +EXAMPLE_PATH = ../../examples/c + +# If the value of the EXAMPLE_PATH tag contains directories, you can use the +# EXAMPLE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp +# and *.h) to filter out the source-files in the directories. If left +# blank all files are included. + +EXAMPLE_PATTERNS = + +# If the EXAMPLE_RECURSIVE tag is set to YES then subdirectories will be +# searched for input files to be used with the \include or \dontinclude +# commands irrespective of the value of the RECURSIVE tag. +# Possible values are YES and NO. If left blank NO is used. + +EXAMPLE_RECURSIVE = NO + +# The IMAGE_PATH tag can be used to specify one or more files or +# directories that contain image that are included in the documentation (see +# the \image command). + +IMAGE_PATH = images + +# The INPUT_FILTER tag can be used to specify a program that doxygen should +# invoke to filter for each input file. Doxygen will invoke the filter program +# by executing (via popen()) the command <filter> <input-file>, where <filter> +# is the value of the INPUT_FILTER tag, and <input-file> is the name of an +# input file. Doxygen will then use the output that the filter program writes +# to standard output. If FILTER_PATTERNS is specified, this tag will be +# ignored. + +INPUT_FILTER = + +# The FILTER_PATTERNS tag can be used to specify filters on a per file pattern +# basis. Doxygen will compare the file name with each pattern and apply the +# filter if there is a match. The filters are a list of the form: +# pattern=filter (like *.cpp=my_cpp_filter). See INPUT_FILTER for further +# info on how filters are used. If FILTER_PATTERNS is empty or if +# non of the patterns match the file name, INPUT_FILTER is applied. + +FILTER_PATTERNS = *.py=tools/pyfilter + +# If the FILTER_SOURCE_FILES tag is set to YES, the input filter (if set using +# INPUT_FILTER) will be used to filter the input files when producing source +# files to browse (i.e. when SOURCE_BROWSER is set to YES). + +FILTER_SOURCE_FILES = NO + +# The FILTER_SOURCE_PATTERNS tag can be used to specify source filters per file +# pattern. A pattern will override the setting for FILTER_PATTERN (if any) +# and it is also possible to disable source filtering for a specific pattern +# using *.ext= (so without naming a filter). This option only has effect when +# FILTER_SOURCE_FILES is enabled. + +FILTER_SOURCE_PATTERNS = + +#--------------------------------------------------------------------------- +# configuration options related to source browsing +#--------------------------------------------------------------------------- + +# If the SOURCE_BROWSER tag is set to YES then a list of source files will +# be generated. Documented entities will be cross-referenced with these sources. +# Note: To get rid of all source code in the generated output, make sure also +# VERBATIM_HEADERS is set to NO. + +SOURCE_BROWSER = NO + +# Setting the INLINE_SOURCES tag to YES will include the body +# of functions and classes directly in the documentation. + +INLINE_SOURCES = NO + +# Setting the STRIP_CODE_COMMENTS tag to YES (the default) will instruct +# doxygen to hide any special comment blocks from generated source code +# fragments. Normal C and C++ comments will always remain visible. + +STRIP_CODE_COMMENTS = YES + +# If the REFERENCED_BY_RELATION tag is set to YES +# then for each documented function all documented +# functions referencing it will be listed. + +REFERENCED_BY_RELATION = NO + +# If the REFERENCES_RELATION tag is set to YES +# then for each documented function all documented entities +# called/used by that function will be listed. + +REFERENCES_RELATION = NO + +# If the REFERENCES_LINK_SOURCE tag is set to YES (the default) +# and SOURCE_BROWSER tag is set to YES, then the hyperlinks from +# functions in REFERENCES_RELATION and REFERENCED_BY_RELATION lists will +# link to the source code. Otherwise they will link to the documentation. + +REFERENCES_LINK_SOURCE = NO + +# If the USE_HTAGS tag is set to YES then the references to source code +# will point to the HTML generated by the htags(1) tool instead of doxygen +# built-in source browser. The htags tool is part of GNU's global source +# tagging system (see http://www.gnu.org/software/global/global.html). You +# will need version 4.8.6 or higher. + +USE_HTAGS = NO + +# If the VERBATIM_HEADERS tag is set to YES (the default) then Doxygen +# will generate a verbatim copy of the header file for each class for +# which an include is specified. Set to NO to disable this. + +VERBATIM_HEADERS = NO + +#--------------------------------------------------------------------------- +# configuration options related to the alphabetical class index +#--------------------------------------------------------------------------- + +# If the ALPHABETICAL_INDEX tag is set to YES, an alphabetical index +# of all compounds will be generated. Enable this if the project +# contains a lot of classes, structs, unions or interfaces. + +ALPHABETICAL_INDEX = NO + +# If the alphabetical index is enabled (see ALPHABETICAL_INDEX) then +# the COLS_IN_ALPHA_INDEX tag can be used to specify the number of columns +# in which this list will be split (can be a number in the range [1..20]) + +COLS_IN_ALPHA_INDEX = 5 + +# In case all classes in a project start with a common prefix, all +# classes will be put under the same header in the alphabetical index. +# The IGNORE_PREFIX tag can be used to specify one or more prefixes that +# should be ignored while generating the index headers. + +IGNORE_PREFIX = WT_ + +#--------------------------------------------------------------------------- +# configuration options related to the HTML output +#--------------------------------------------------------------------------- + +# If the GENERATE_HTML tag is set to YES (the default) Doxygen will +# generate HTML output. + +GENERATE_HTML = YES + +# The HTML_OUTPUT tag is used to specify where the HTML docs will be put. +# If a relative path is entered the value of OUTPUT_DIRECTORY will be +# put in front of it. If left blank `html' will be used as the default path. + +HTML_OUTPUT = . + +# The HTML_FILE_EXTENSION tag can be used to specify the file extension for +# each generated HTML page (for example: .htm,.php,.asp). If it is left blank +# doxygen will generate files with .html extension. + +HTML_FILE_EXTENSION = .html + +# The HTML_HEADER tag can be used to specify a personal HTML header for +# each generated HTML page. If it is left blank doxygen will generate a +# standard header. Note that when using a custom header you are responsible +# for the proper inclusion of any scripts and style sheets that doxygen +# needs, which is dependent on the configuration options used. +# It is adviced to generate a default header using "doxygen -w html +# header.html footer.html stylesheet.css YourConfigFile" and then modify +# that header. Note that the header is subject to change so you typically +# have to redo this when upgrading to a newer version of doxygen or when +# changing the value of configuration settings such as GENERATE_TREEVIEW! + +HTML_HEADER = style/header.html + +# The HTML_FOOTER tag can be used to specify a personal HTML footer for +# each generated HTML page. If it is left blank doxygen will generate a +# standard footer. + +HTML_FOOTER = style/footer.html + +# The HTML_STYLESHEET tag can be used to specify a user-defined cascading +# style sheet that is used by each HTML page. It can be used to +# fine-tune the look of the HTML output. If the tag is left blank doxygen +# will generate a default style sheet. Note that doxygen will try to copy +# the style sheet file to the HTML output directory, so don't put your own +# stylesheet in the HTML output directory as well, or it will be erased! + +HTML_STYLESHEET = style/wiredtiger.css + +# The HTML_EXTRA_FILES tag can be used to specify one or more extra images or +# other source files which should be copied to the HTML output directory. Note +# that these files will be copied to the base HTML output directory. Use the +# $relpath$ marker in the HTML_HEADER and/or HTML_FOOTER files to load these +# files. In the HTML_STYLESHEET file, use the file name only. Also note that +# the files will be copied as-is; there are no commands or markers available. + +HTML_EXTRA_FILES = + +# The HTML_COLORSTYLE_HUE tag controls the color of the HTML output. +# Doxygen will adjust the colors in the stylesheet and background images +# according to this color. Hue is specified as an angle on a colorwheel, +# see http://en.wikipedia.org/wiki/Hue for more information. +# For instance the value 0 represents red, 60 is yellow, 120 is green, +# 180 is cyan, 240 is blue, 300 purple, and 360 is red again. +# The allowed range is 0 to 359. + +HTML_COLORSTYLE_HUE = 34 + +# The HTML_COLORSTYLE_SAT tag controls the purity (or saturation) of +# the colors in the HTML output. For a value of 0 the output will use +# grayscales only. A value of 255 will produce the most vivid colors. + +HTML_COLORSTYLE_SAT = 81 + +# The HTML_COLORSTYLE_GAMMA tag controls the gamma correction applied to +# the luminance component of the colors in the HTML output. Values below +# 100 gradually make the output lighter, whereas values above 100 make +# the output darker. The value divided by 100 is the actual gamma applied, +# so 80 represents a gamma of 0.8, The value 220 represents a gamma of 2.2, +# and 100 does not change the gamma. + +HTML_COLORSTYLE_GAMMA = 96 + +# If the HTML_TIMESTAMP tag is set to YES then the footer of each generated HTML +# page will contain the date and time when the page was generated. Setting +# this to NO can help when comparing the output of multiple runs. + +HTML_TIMESTAMP = YES + +# If the HTML_ALIGN_MEMBERS tag is set to YES, the members of classes, +# files or namespaces will be aligned in HTML using tables. If set to +# NO a bullet list will be used. + +HTML_ALIGN_MEMBERS = YES + +# If the HTML_DYNAMIC_SECTIONS tag is set to YES then the generated HTML +# documentation will contain sections that can be hidden and shown after the +# page has loaded. For this to work a browser that supports +# JavaScript and DHTML is required (for instance Mozilla 1.0+, Firefox +# Netscape 6.0+, Internet explorer 5.0+, Konqueror, or Safari). + +HTML_DYNAMIC_SECTIONS = YES + +# If the GENERATE_DOCSET tag is set to YES, additional index files +# will be generated that can be used as input for Apple's Xcode 3 +# integrated development environment, introduced with OSX 10.5 (Leopard). +# To create a documentation set, doxygen will generate a Makefile in the +# HTML output directory. Running make will produce the docset in that +# directory and running "make install" will install the docset in +# ~/Library/Developer/Shared/Documentation/DocSets so that Xcode will find +# it at startup. +# See http://developer.apple.com/tools/creatingdocsetswithdoxygen.html +# for more information. + +GENERATE_DOCSET = NO + +# When GENERATE_DOCSET tag is set to YES, this tag determines the name of the +# feed. A documentation feed provides an umbrella under which multiple +# documentation sets from a single provider (such as a company or product suite) +# can be grouped. + +DOCSET_FEEDNAME = "Doxygen generated docs" + +# When GENERATE_DOCSET tag is set to YES, this tag specifies a string that +# should uniquely identify the documentation set bundle. This should be a +# reverse domain-name style string, e.g. com.mycompany.MyDocSet. Doxygen +# will append .docset to the name. + +DOCSET_BUNDLE_ID = org.doxygen.Project + +# When GENERATE_PUBLISHER_ID tag specifies a string that should uniquely identify +# the documentation publisher. This should be a reverse domain-name style +# string, e.g. com.mycompany.MyDocSet.documentation. + +DOCSET_PUBLISHER_ID = org.doxygen.Publisher + +# The GENERATE_PUBLISHER_NAME tag identifies the documentation publisher. + +DOCSET_PUBLISHER_NAME = Publisher + +# If the GENERATE_HTMLHELP tag is set to YES, additional index files +# will be generated that can be used as input for tools like the +# Microsoft HTML help workshop to generate a compiled HTML help file (.chm) +# of the generated HTML documentation. + +GENERATE_HTMLHELP = NO + +# If the GENERATE_HTMLHELP tag is set to YES, the CHM_FILE tag can +# be used to specify the file name of the resulting .chm file. You +# can add a path in front of the file if the result should not be +# written to the html output directory. + +CHM_FILE = + +# If the GENERATE_HTMLHELP tag is set to YES, the HHC_LOCATION tag can +# be used to specify the location (absolute path including file name) of +# the HTML help compiler (hhc.exe). If non-empty doxygen will try to run +# the HTML help compiler on the generated index.hhp. + +HHC_LOCATION = + +# If the GENERATE_HTMLHELP tag is set to YES, the GENERATE_CHI flag +# controls if a separate .chi index file is generated (YES) or that +# it should be included in the master .chm file (NO). + +GENERATE_CHI = NO + +# If the GENERATE_HTMLHELP tag is set to YES, the CHM_INDEX_ENCODING +# is used to encode HtmlHelp index (hhk), content (hhc) and project file +# content. + +CHM_INDEX_ENCODING = + +# If the GENERATE_HTMLHELP tag is set to YES, the BINARY_TOC flag +# controls whether a binary table of contents is generated (YES) or a +# normal table of contents (NO) in the .chm file. + +BINARY_TOC = NO + +# The TOC_EXPAND flag can be set to YES to add extra items for group members +# to the contents of the HTML help documentation and to the tree view. + +TOC_EXPAND = NO + +# If the GENERATE_QHP tag is set to YES and both QHP_NAMESPACE and +# QHP_VIRTUAL_FOLDER are set, an additional index file will be generated +# that can be used as input for Qt's qhelpgenerator to generate a +# Qt Compressed Help (.qch) of the generated HTML documentation. + +GENERATE_QHP = NO + +# If the QHG_LOCATION tag is specified, the QCH_FILE tag can +# be used to specify the file name of the resulting .qch file. +# The path specified is relative to the HTML output folder. + +QCH_FILE = + +# The QHP_NAMESPACE tag specifies the namespace to use when generating +# Qt Help Project output. For more information please see +# http://doc.trolltech.com/qthelpproject.html#namespace + +QHP_NAMESPACE = org.doxygen.Project + +# The QHP_VIRTUAL_FOLDER tag specifies the namespace to use when generating +# Qt Help Project output. For more information please see +# http://doc.trolltech.com/qthelpproject.html#virtual-folders + +QHP_VIRTUAL_FOLDER = doc + +# If QHP_CUST_FILTER_NAME is set, it specifies the name of a custom filter to +# add. For more information please see +# http://doc.trolltech.com/qthelpproject.html#custom-filters + +QHP_CUST_FILTER_NAME = + +# The QHP_CUST_FILT_ATTRS tag specifies the list of the attributes of the +# custom filter to add. For more information please see +# <a href="http://doc.trolltech.com/qthelpproject.html#custom-filters"> +# Qt Help Project / Custom Filters</a>. + +QHP_CUST_FILTER_ATTRS = + +# The QHP_SECT_FILTER_ATTRS tag specifies the list of the attributes this +# project's +# filter section matches. +# <a href="http://doc.trolltech.com/qthelpproject.html#filter-attributes"> +# Qt Help Project / Filter Attributes</a>. + +QHP_SECT_FILTER_ATTRS = + +# If the GENERATE_QHP tag is set to YES, the QHG_LOCATION tag can +# be used to specify the location of Qt's qhelpgenerator. +# If non-empty doxygen will try to run qhelpgenerator on the generated +# .qhp file. + +QHG_LOCATION = + +# If the GENERATE_ECLIPSEHELP tag is set to YES, additional index files +# will be generated, which together with the HTML files, form an Eclipse help +# plugin. To install this plugin and make it available under the help contents +# menu in Eclipse, the contents of the directory containing the HTML and XML +# files needs to be copied into the plugins directory of eclipse. The name of +# the directory within the plugins directory should be the same as +# the ECLIPSE_DOC_ID value. After copying Eclipse needs to be restarted before +# the help appears. + +GENERATE_ECLIPSEHELP = NO + +# A unique identifier for the eclipse help plugin. When installing the plugin +# the directory name containing the HTML and XML files should also have +# this name. + +ECLIPSE_DOC_ID = org.doxygen.Project + +# The DISABLE_INDEX tag can be used to turn on/off the condensed index at +# top of each HTML page. The value NO (the default) enables the index and +# the value YES disables it. + +DISABLE_INDEX = NO + +# The ENUM_VALUES_PER_LINE tag can be used to set the number of enum values +# (range [0,1..20]) that doxygen will group on one line in the generated HTML +# documentation. Note that a value of 0 will completely suppress the enum +# values from appearing in the overview section. + +ENUM_VALUES_PER_LINE = 4 + +# The GENERATE_TREEVIEW tag is used to specify whether a tree-like index +# structure should be generated to display hierarchical information. +# If the tag value is set to YES, a side panel will be generated +# containing a tree-like index structure (just like the one that +# is generated for HTML Help). For this to work a browser that supports +# JavaScript, DHTML, CSS and frames is required (i.e. any modern browser). +# Windows users are probably better off using the HTML help feature. + +GENERATE_TREEVIEW = YES + +# By enabling USE_INLINE_TREES, doxygen will generate the Groups, Directories, +# and Class Hierarchy pages using a tree view instead of an ordered list. + +USE_INLINE_TREES = YES + +# If the treeview is enabled (see GENERATE_TREEVIEW) then this tag can be +# used to set the initial width (in pixels) of the frame in which the tree +# is shown. + +TREEVIEW_WIDTH = 200 + +# When the EXT_LINKS_IN_WINDOW option is set to YES doxygen will open +# links to external symbols imported via tag files in a separate window. + +EXT_LINKS_IN_WINDOW = NO + +# Use this tag to change the font size of Latex formulas included +# as images in the HTML documentation. The default is 10. Note that +# when you change the font size after a successful doxygen run you need +# to manually remove any form_*.png images from the HTML output directory +# to force them to be regenerated. + +FORMULA_FONTSIZE = 10 + +# Use the FORMULA_TRANPARENT tag to determine whether or not the images +# generated for formulas are transparent PNGs. Transparent PNGs are +# not supported properly for IE 6.0, but are supported on all modern browsers. +# Note that when changing this option you need to delete any form_*.png files +# in the HTML output before the changes have effect. + +FORMULA_TRANSPARENT = YES + +# Enable the USE_MATHJAX option to render LaTeX formulas using MathJax +# (see http://www.mathjax.org) which uses client side Javascript for the +# rendering instead of using prerendered bitmaps. Use this if you do not +# have LaTeX installed or if you want to formulas look prettier in the HTML +# output. When enabled you also need to install MathJax separately and +# configure the path to it using the MATHJAX_RELPATH option. + +USE_MATHJAX = NO + +# When MathJax is enabled you need to specify the location relative to the +# HTML output directory using the MATHJAX_RELPATH option. The destination +# directory should contain the MathJax.js script. For instance, if the mathjax +# directory is located at the same level as the HTML output directory, then +# MATHJAX_RELPATH should be ../mathjax. The default value points to the +# mathjax.org site, so you can quickly see the result without installing +# MathJax, but it is strongly recommended to install a local copy of MathJax +# before deployment. + +MATHJAX_RELPATH = http://www.mathjax.org/mathjax + +# When the SEARCHENGINE tag is enabled doxygen will generate a search box +# for the HTML output. The underlying search engine uses javascript +# and DHTML and should work on any modern browser. Note that when using +# HTML help (GENERATE_HTMLHELP), Qt help (GENERATE_QHP), or docsets +# (GENERATE_DOCSET) there is already a search function so this one should +# typically be disabled. For large projects the javascript based search engine +# can be slow, then enabling SERVER_BASED_SEARCH may provide a better solution. + +SEARCHENGINE = NO + +# When the SERVER_BASED_SEARCH tag is enabled the search engine will be +# implemented using a PHP enabled web server instead of at the web client +# using Javascript. Doxygen will generate the search PHP script and index +# file to put on the web server. The advantage of the server +# based approach is that it scales better to large projects and allows +# full text search. The disadvantages are that it is more difficult to setup +# and does not have live searching capabilities. + +SERVER_BASED_SEARCH = NO + +#--------------------------------------------------------------------------- +# configuration options related to the LaTeX output +#--------------------------------------------------------------------------- + +# If the GENERATE_LATEX tag is set to YES (the default) Doxygen will +# generate Latex output. + +GENERATE_LATEX = NO + +# The LATEX_OUTPUT tag is used to specify where the LaTeX docs will be put. +# If a relative path is entered the value of OUTPUT_DIRECTORY will be +# put in front of it. If left blank `latex' will be used as the default path. + +LATEX_OUTPUT = latex + +# The LATEX_CMD_NAME tag can be used to specify the LaTeX command name to be +# invoked. If left blank `latex' will be used as the default command name. +# Note that when enabling USE_PDFLATEX this option is only used for +# generating bitmaps for formulas in the HTML output, but not in the +# Makefile that is written to the output directory. + +LATEX_CMD_NAME = latex + +# The MAKEINDEX_CMD_NAME tag can be used to specify the command name to +# generate index for LaTeX. If left blank `makeindex' will be used as the +# default command name. + +MAKEINDEX_CMD_NAME = makeindex + +# If the COMPACT_LATEX tag is set to YES Doxygen generates more compact +# LaTeX documents. This may be useful for small projects and may help to +# save some trees in general. + +COMPACT_LATEX = NO + +# The PAPER_TYPE tag can be used to set the paper type that is used +# by the printer. Possible values are: a4, letter, legal and +# executive. If left blank a4wide will be used. + +PAPER_TYPE = a4wide + +# The EXTRA_PACKAGES tag can be to specify one or more names of LaTeX +# packages that should be included in the LaTeX output. + +EXTRA_PACKAGES = + +# The LATEX_HEADER tag can be used to specify a personal LaTeX header for +# the generated latex document. The header should contain everything until +# the first chapter. If it is left blank doxygen will generate a +# standard header. Notice: only use this tag if you know what you are doing! + +LATEX_HEADER = + +# The LATEX_FOOTER tag can be used to specify a personal LaTeX footer for +# the generated latex document. The footer should contain everything after +# the last chapter. If it is left blank doxygen will generate a +# standard footer. Notice: only use this tag if you know what you are doing! + +LATEX_FOOTER = + +# If the PDF_HYPERLINKS tag is set to YES, the LaTeX that is generated +# is prepared for conversion to pdf (using ps2pdf). The pdf file will +# contain links (just like the HTML output) instead of page references +# This makes the output suitable for online browsing using a pdf viewer. + +PDF_HYPERLINKS = YES + +# If the USE_PDFLATEX tag is set to YES, pdflatex will be used instead of +# plain latex in the generated Makefile. Set this option to YES to get a +# higher quality PDF documentation. + +USE_PDFLATEX = YES + +# If the LATEX_BATCHMODE tag is set to YES, doxygen will add the \\batchmode. +# command to the generated LaTeX files. This will instruct LaTeX to keep +# running if errors occur, instead of asking the user for help. +# This option is also used when generating formulas in HTML. + +LATEX_BATCHMODE = NO + +# If LATEX_HIDE_INDICES is set to YES then doxygen will not +# include the index chapters (such as File Index, Compound Index, etc.) +# in the output. + +LATEX_HIDE_INDICES = YES + +# If LATEX_SOURCE_CODE is set to YES then doxygen will include +# source code with syntax highlighting in the LaTeX output. +# Note that which sources are shown also depends on other settings +# such as SOURCE_BROWSER. + +LATEX_SOURCE_CODE = YES + +#--------------------------------------------------------------------------- +# configuration options related to the RTF output +#--------------------------------------------------------------------------- + +# If the GENERATE_RTF tag is set to YES Doxygen will generate RTF output +# The RTF output is optimized for Word 97 and may not look very pretty with +# other RTF readers or editors. + +GENERATE_RTF = NO + +# The RTF_OUTPUT tag is used to specify where the RTF docs will be put. +# If a relative path is entered the value of OUTPUT_DIRECTORY will be +# put in front of it. If left blank `rtf' will be used as the default path. + +RTF_OUTPUT = rtf + +# If the COMPACT_RTF tag is set to YES Doxygen generates more compact +# RTF documents. This may be useful for small projects and may help to +# save some trees in general. + +COMPACT_RTF = NO + +# If the RTF_HYPERLINKS tag is set to YES, the RTF that is generated +# will contain hyperlink fields. The RTF file will +# contain links (just like the HTML output) instead of page references. +# This makes the output suitable for online browsing using WORD or other +# programs which support those fields. +# Note: wordpad (write) and others do not support links. + +RTF_HYPERLINKS = NO + +# Load stylesheet definitions from file. Syntax is similar to doxygen's +# config file, i.e. a series of assignments. You only have to provide +# replacements, missing definitions are set to their default value. + +RTF_STYLESHEET_FILE = + +# Set optional variables used in the generation of an rtf document. +# Syntax is similar to doxygen's config file. + +RTF_EXTENSIONS_FILE = + +#--------------------------------------------------------------------------- +# configuration options related to the man page output +#--------------------------------------------------------------------------- + +# If the GENERATE_MAN tag is set to YES (the default) Doxygen will +# generate man pages + +GENERATE_MAN = NO + +# The MAN_OUTPUT tag is used to specify where the man pages will be put. +# If a relative path is entered the value of OUTPUT_DIRECTORY will be +# put in front of it. If left blank `man' will be used as the default path. + +MAN_OUTPUT = man + +# The MAN_EXTENSION tag determines the extension that is added to +# the generated man pages (default is the subroutine's section .3) + +MAN_EXTENSION = .3 + +# If the MAN_LINKS tag is set to YES and Doxygen generates man output, +# then it will generate one additional man file for each entity +# documented in the real man page(s). These additional files +# only source the real man page, but without them the man command +# would be unable to find the correct page. The default is NO. + +MAN_LINKS = NO + +#--------------------------------------------------------------------------- +# configuration options related to the XML output +#--------------------------------------------------------------------------- + +# If the GENERATE_XML tag is set to YES Doxygen will +# generate an XML file that captures the structure of +# the code including all documentation. + +GENERATE_XML = NO + +# The XML_OUTPUT tag is used to specify where the XML pages will be put. +# If a relative path is entered the value of OUTPUT_DIRECTORY will be +# put in front of it. If left blank `xml' will be used as the default path. + +XML_OUTPUT = xml + +# The XML_SCHEMA tag can be used to specify an XML schema, +# which can be used by a validating XML parser to check the +# syntax of the XML files. + +XML_SCHEMA = + +# The XML_DTD tag can be used to specify an XML DTD, +# which can be used by a validating XML parser to check the +# syntax of the XML files. + +XML_DTD = + +# If the XML_PROGRAMLISTING tag is set to YES Doxygen will +# dump the program listings (including syntax highlighting +# and cross-referencing information) to the XML output. Note that +# enabling this will significantly increase the size of the XML output. + +XML_PROGRAMLISTING = YES + +#--------------------------------------------------------------------------- +# configuration options for the AutoGen Definitions output +#--------------------------------------------------------------------------- + +# If the GENERATE_AUTOGEN_DEF tag is set to YES Doxygen will +# generate an AutoGen Definitions (see autogen.sf.net) file +# that captures the structure of the code including all +# documentation. Note that this feature is still experimental +# and incomplete at the moment. + +GENERATE_AUTOGEN_DEF = NO + +#--------------------------------------------------------------------------- +# configuration options related to the Perl module output +#--------------------------------------------------------------------------- + +# If the GENERATE_PERLMOD tag is set to YES Doxygen will +# generate a Perl module file that captures the structure of +# the code including all documentation. Note that this +# feature is still experimental and incomplete at the +# moment. + +GENERATE_PERLMOD = NO + +# If the PERLMOD_LATEX tag is set to YES Doxygen will generate +# the necessary Makefile rules, Perl scripts and LaTeX code to be able +# to generate PDF and DVI output from the Perl module output. + +PERLMOD_LATEX = NO + +# If the PERLMOD_PRETTY tag is set to YES the Perl module output will be +# nicely formatted so it can be parsed by a human reader. This is useful +# if you want to understand what is going on. On the other hand, if this +# tag is set to NO the size of the Perl module output will be much smaller +# and Perl will parse it just the same. + +PERLMOD_PRETTY = YES + +# The names of the make variables in the generated doxyrules.make file +# are prefixed with the string contained in PERLMOD_MAKEVAR_PREFIX. +# This is useful so different doxyrules.make files included by the same +# Makefile don't overwrite each other's variables. + +PERLMOD_MAKEVAR_PREFIX = + +#--------------------------------------------------------------------------- +# Configuration options related to the preprocessor +#--------------------------------------------------------------------------- + +# If the ENABLE_PREPROCESSING tag is set to YES (the default) Doxygen will +# evaluate all C-preprocessor directives found in the sources and include +# files. + +ENABLE_PREPROCESSING = YES + +# If the MACRO_EXPANSION tag is set to YES Doxygen will expand all macro +# names in the source code. If set to NO (the default) only conditional +# compilation will be performed. Macro expansion can be done in a controlled +# way by setting EXPAND_ONLY_PREDEF to YES. + +MACRO_EXPANSION = YES + +# If the EXPAND_ONLY_PREDEF and MACRO_EXPANSION tags are both set to YES +# then the macro expansion is limited to the macros specified with the +# PREDEFINED and EXPAND_AS_DEFINED tags. + +EXPAND_ONLY_PREDEF = NO + +# If the SEARCH_INCLUDES tag is set to YES (the default) the includes files +# pointed to by INCLUDE_PATH will be searched when a #include is found. + +SEARCH_INCLUDES = YES + +# The INCLUDE_PATH tag can be used to specify one or more directories that +# contain include files that are not input files but should be processed by +# the preprocessor. + +INCLUDE_PATH = + +# You can use the INCLUDE_FILE_PATTERNS tag to specify one or more wildcard +# patterns (like *.h and *.hpp) to filter out the header-files in the +# directories. If left blank, the patterns specified with FILE_PATTERNS will +# be used. + +INCLUDE_FILE_PATTERNS = + +# The PREDEFINED tag can be used to specify one or more macro names that +# are defined before the preprocessor is started (similar to the -D option of +# gcc). The argument of the tag is a list of macros of the form: name +# or name=definition (no spaces). If the definition and the = are +# omitted =1 is assumed. To prevent a macro definition from being +# undefined via #undef or recursively expanded use the := operator +# instead of the = operator. + +PREDEFINED = DOXYGEN \ + __wt_collator:=WT_COLLATOR \ + __wt_compressor:=WT_COMPRESSOR \ + __wt_connection:=WT_CONNECTION \ + __wt_cursor:=WT_CURSOR \ + __wt_data_source:=WT_DATA_SOURCE \ + __wt_event_handler:=WT_EVENT_HANDLER \ + __wt_extension_api:=WT_EXTENSION_API \ + __wt_extractor:=WT_EXTRACTOR \ + __wt_item:=WT_ITEM \ + __wt_session:=WT_SESSION \ + +# If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then +# this tag can be used to specify a list of macro names that should be expanded. +# The macro definition that is found in the sources will be used. +# Use the PREDEFINED tag if you want to use a different macro definition that +# overrules the definition found in the source code. + +EXPAND_AS_DEFINED = + +# If the SKIP_FUNCTION_MACROS tag is set to YES (the default) then +# doxygen's preprocessor will remove all references to function-like macros +# that are alone on a line, have an all uppercase name, and do not end with a +# semicolon, because these will confuse the parser if not removed. + +SKIP_FUNCTION_MACROS = YES + +#--------------------------------------------------------------------------- +# Configuration::additions related to external references +#--------------------------------------------------------------------------- + +# The TAGFILES option can be used to specify one or more tagfiles. +# Optionally an initial location of the external documentation +# can be added for each tagfile. The format of a tag file without +# this location is as follows: +# TAGFILES = file1 file2 ... +# Adding location for the tag files is done as follows: +# TAGFILES = file1=loc1 "file2 = loc2" ... +# where "loc1" and "loc2" can be relative or absolute paths or +# URLs. If a location is present for each tag, the installdox tool +# does not have to be run to correct the links. +# Note that each tag file must have a unique name +# (where the name does NOT include the path) +# If a tag file is not located in the directory in which doxygen +# is run, you must also specify the path to the tagfile here. + +TAGFILES = + +# When a file name is specified after GENERATE_TAGFILE, doxygen will create +# a tag file that is based on the input files it reads. + +GENERATE_TAGFILE = + +# If the ALLEXTERNALS tag is set to YES all external classes will be listed +# in the class index. If set to NO only the inherited external classes +# will be listed. + +ALLEXTERNALS = NO + +# If the EXTERNAL_GROUPS tag is set to YES all external groups will be listed +# in the modules index. If set to NO, only the current project's groups will +# be listed. + +EXTERNAL_GROUPS = YES + +# The PERL_PATH should be the absolute path and name of the perl script +# interpreter (i.e. the result of `which perl'). + +PERL_PATH = /usr/bin/perl + +#--------------------------------------------------------------------------- +# Configuration options related to the dot tool +#--------------------------------------------------------------------------- + +# If the CLASS_DIAGRAMS tag is set to YES (the default) Doxygen will +# generate a inheritance diagram (in HTML, RTF and LaTeX) for classes with base +# or super classes. Setting the tag to NO turns the diagrams off. Note that +# this option also works with HAVE_DOT disabled, but it is recommended to +# install and use dot, since it yields more powerful graphs. + +CLASS_DIAGRAMS = YES + +# You can define message sequence charts within doxygen comments using the \msc +# command. Doxygen will then run the mscgen tool (see +# http://www.mcternan.me.uk/mscgen/) to produce the chart and insert it in the +# documentation. The MSCGEN_PATH tag allows you to specify the directory where +# the mscgen tool resides. If left empty the tool is assumed to be found in the +# default search path. + +MSCGEN_PATH = + +# If set to YES, the inheritance and collaboration graphs will hide +# inheritance and usage relations if the target is undocumented +# or is not a class. + +HIDE_UNDOC_RELATIONS = YES + +# If you set the HAVE_DOT tag to YES then doxygen will assume the dot tool is +# available from the path. This tool is part of Graphviz, a graph visualization +# toolkit from AT&T and Lucent Bell Labs. The other options in this section +# have no effect if this option is set to NO (the default) + +HAVE_DOT = NO + +# The DOT_NUM_THREADS specifies the number of dot invocations doxygen is +# allowed to run in parallel. When set to 0 (the default) doxygen will +# base this on the number of processors available in the system. You can set it +# explicitly to a value larger than 0 to get control over the balance +# between CPU load and processing speed. + +DOT_NUM_THREADS = 0 + +# By default doxygen will write a font called Helvetica to the output +# directory and reference it in all dot files that doxygen generates. +# When you want a differently looking font you can specify the font name +# using DOT_FONTNAME. You need to make sure dot is able to find the font, +# which can be done by putting it in a standard location or by setting the +# DOTFONTPATH environment variable or by setting DOT_FONTPATH to the directory +# containing the font. + +DOT_FONTNAME = FreeSans.ttf + +# The DOT_FONTSIZE tag can be used to set the size of the font of dot graphs. +# The default size is 10pt. + +DOT_FONTSIZE = 10 + +# By default doxygen will tell dot to use the output directory to look for the +# FreeSans.ttf font (which doxygen will put there itself). If you specify a +# different font using DOT_FONTNAME you can set the path where dot +# can find it using this tag. + +DOT_FONTPATH = + +# If the CLASS_GRAPH and HAVE_DOT tags are set to YES then doxygen +# will generate a graph for each documented class showing the direct and +# indirect inheritance relations. Setting this tag to YES will force the +# the CLASS_DIAGRAMS tag to NO. + +CLASS_GRAPH = YES + +# If the COLLABORATION_GRAPH and HAVE_DOT tags are set to YES then doxygen +# will generate a graph for each documented class showing the direct and +# indirect implementation dependencies (inheritance, containment, and +# class references variables) of the class with other documented classes. + +COLLABORATION_GRAPH = YES + +# If the GROUP_GRAPHS and HAVE_DOT tags are set to YES then doxygen +# will generate a graph for groups, showing the direct groups dependencies + +GROUP_GRAPHS = YES + +# If the UML_LOOK tag is set to YES doxygen will generate inheritance and +# collaboration diagrams in a style similar to the OMG's Unified Modeling +# Language. + +UML_LOOK = NO + +# If set to YES, the inheritance and collaboration graphs will show the +# relations between templates and their instances. + +TEMPLATE_RELATIONS = NO + +# If the ENABLE_PREPROCESSING, SEARCH_INCLUDES, INCLUDE_GRAPH, and HAVE_DOT +# tags are set to YES then doxygen will generate a graph for each documented +# file showing the direct and indirect include dependencies of the file with +# other documented files. + +INCLUDE_GRAPH = YES + +# If the ENABLE_PREPROCESSING, SEARCH_INCLUDES, INCLUDED_BY_GRAPH, and +# HAVE_DOT tags are set to YES then doxygen will generate a graph for each +# documented header file showing the documented files that directly or +# indirectly include this file. + +INCLUDED_BY_GRAPH = YES + +# If the CALL_GRAPH and HAVE_DOT options are set to YES then +# doxygen will generate a call dependency graph for every global function +# or class method. Note that enabling this option will significantly increase +# the time of a run. So in most cases it will be better to enable call graphs +# for selected functions only using the \callgraph command. + +CALL_GRAPH = NO + +# If the CALLER_GRAPH and HAVE_DOT tags are set to YES then +# doxygen will generate a caller dependency graph for every global function +# or class method. Note that enabling this option will significantly increase +# the time of a run. So in most cases it will be better to enable caller +# graphs for selected functions only using the \callergraph command. + +CALLER_GRAPH = NO + +# If the GRAPHICAL_HIERARCHY and HAVE_DOT tags are set to YES then doxygen +# will generate a graphical hierarchy of all classes instead of a textual one. + +GRAPHICAL_HIERARCHY = YES + +# If the DIRECTORY_GRAPH, SHOW_DIRECTORIES and HAVE_DOT tags are set to YES +# then doxygen will show the dependencies a directory has on other directories +# in a graphical way. The dependency relations are determined by the #include +# relations between the files in the directories. + +DIRECTORY_GRAPH = YES + +# The DOT_IMAGE_FORMAT tag can be used to set the image format of the images +# generated by dot. Possible values are svg, png, jpg, or gif. +# If left blank png will be used. + +DOT_IMAGE_FORMAT = png + +# The tag DOT_PATH can be used to specify the path where the dot tool can be +# found. If left blank, it is assumed the dot tool can be found in the path. + +DOT_PATH = + +# The DOTFILE_DIRS tag can be used to specify one or more directories that +# contain dot files that are included in the documentation (see the +# \dotfile command). + +DOTFILE_DIRS = + +# The MSCFILE_DIRS tag can be used to specify one or more directories that +# contain msc files that are included in the documentation (see the +# \mscfile command). + +MSCFILE_DIRS = + +# The DOT_GRAPH_MAX_NODES tag can be used to set the maximum number of +# nodes that will be shown in the graph. If the number of nodes in a graph +# becomes larger than this value, doxygen will truncate the graph, which is +# visualized by representing a node as a red box. Note that doxygen if the +# number of direct children of the root node in a graph is already larger than +# DOT_GRAPH_MAX_NODES then the graph will not be shown at all. Also note +# that the size of a graph can be further restricted by MAX_DOT_GRAPH_DEPTH. + +DOT_GRAPH_MAX_NODES = 50 + +# The MAX_DOT_GRAPH_DEPTH tag can be used to set the maximum depth of the +# graphs generated by dot. A depth value of 3 means that only nodes reachable +# from the root by following a path via at most 3 edges will be shown. Nodes +# that lay further from the root node will be omitted. Note that setting this +# option to 1 or 2 may greatly reduce the computation time needed for large +# code bases. Also note that the size of a graph can be further restricted by +# DOT_GRAPH_MAX_NODES. Using a depth of 0 means no depth restriction. + +MAX_DOT_GRAPH_DEPTH = 0 + +# Set the DOT_TRANSPARENT tag to YES to generate images with a transparent +# background. This is disabled by default, because dot on Windows does not +# seem to support this out of the box. Warning: Depending on the platform used, +# enabling this option may lead to badly anti-aliased labels on the edges of +# a graph (i.e. they become hard to read). + +DOT_TRANSPARENT = NO + +# Set the DOT_MULTI_TARGETS tag to YES allow dot to generate multiple output +# files in one run (i.e. multiple -o and -T options on the command line). This +# makes dot run faster, but since only newer versions of dot (>1.8.10) +# support this, this feature is disabled by default. + +DOT_MULTI_TARGETS = NO + +# If the GENERATE_LEGEND tag is set to YES (the default) Doxygen will +# generate a legend page explaining the meaning of the various boxes and +# arrows in the dot generated graphs. + +GENERATE_LEGEND = YES + +# If the DOT_CLEANUP tag is set to YES (the default) Doxygen will +# remove the intermediate dot files that are used to generate +# the various graphs. + +DOT_CLEANUP = YES diff --git a/src/docs/Makefile b/src/docs/Makefile new file mode 100644 index 00000000000..71173523a0a --- /dev/null +++ b/src/docs/Makefile @@ -0,0 +1,7 @@ +all: + @(cd ../../dist && sh s_docs -t) + +clean: + @(cd ../../dist && sh s_docs -a) + +.PHONY: all clean diff --git a/src/docs/admin.dox b/src/docs/admin.dox new file mode 100644 index 00000000000..3fe634c6749 --- /dev/null +++ b/src/docs/admin.dox @@ -0,0 +1,8 @@ +/*! @page admin Managing a WiredTiger Database + +- @subpage home +- @subpage security +- @subpage file_formats +- @subpage tuning + + */ diff --git a/src/docs/architecture.dox b/src/docs/architecture.dox new file mode 100644 index 00000000000..ef09656094d --- /dev/null +++ b/src/docs/architecture.dox @@ -0,0 +1,108 @@ +/*! @page architecture WiredTiger Architecture + +The WiredTiger data engine is a high performance, scalable, transactional, +production quality, open source, NoSQL data engine, created to maximize the +value of each computer you buy: + +- WiredTiger offers both low latency and high throughput (in-cache reads +require no latching, writes typically require a single latch), + +- WiredTiger handles data sets much larger than RAM without performance +or resource degradation, + +- WiredTiger has predictable behavior under heavy access and large +volumes of data, + +- WiredTiger offers transactional semantics without blocking, + +- WiredTiger stores are not corrupted by torn writes, reverting to the +last snapshot after system failure, + +- WiredTiger supports petabyte tables, records up to 4GB, and record +numbers up to 64-bits. + +WiredTiger's design is focused on a few core principles: + +@section multi_core Multi-core scaling + +WiredTiger scales on modern, multi-CPU architectures. Using a variety of +programming techniques such as hazard references, lock-free algorithms, fast +latching and message passing, WiredTiger performs more work per CPU core than +alternative engines. + +WiredTiger's transactions use optimistic concurrency control algorithms that +avoid the bottleneck of a centralized lock manager. Transactional operations +in one thread do not block operations in other threads, but strong isolation is +provided and update conflicts are detected to preserve data consistency. + +@section cache Hot caches + +WiredTiger supports both row-oriented storage (where all columns of a +row are stored together), and column-oriented storage (where groups of +columns are stored in separate files), resulting in more efficient +memory use. When reading and writing column-stores, only the columns +required for any particular query are maintained in memory. +Column-store keys are derived from the value's location in the table +rather than being physically stored in the table, further minimizing +memory requirements. Finally, row-and column-stores can be +mixed-and-matched at the table level: for example, a row-store index can +be created on a column-store table. + +WiredTiger supports different-sized Btree internal and leaf pages in the +same file. Applications can maximize the amount of data transferred in +each I/O by configuring large leaf pages, and still minimize CPU cache +misses when searching the tree. + +WiredTiger supports static encoding with a configurable Huffman engine, +which typically reduces the amount of information maintained in memory +by 20-50%. + +WiredTiger supports key prefix encoding, reducing the number of bytes +from each key maintained in memory. + +@section io Making I/O more valuable + +WiredTiger uses compact file formats to minimize on-disk overhead. +WiredTiger does not store data indexing information on disk, instead, +WiredTiger instantiates data indexing information either when pages are +read from disk or on demand. This simplifies the on-disk file format +and in the case of small key/value pairs, typically reduces the amount +of information written to disk by 20-50%. + +WiredTiger supports variable-length pages, meaning there is less wasted +space for large objects, and no need for compaction as pages grow and +shrink naturally when key/value pairs are inserted or deleted. + +WiredTiger supports stream compression on every page of a table. +Because WiredTiger supports variable-length pages, pages do not have to +shrink by a fixed amount in order to benefit from stream compression. +Stream compression is selectable on a per-table basis, allowing +applications to choose the compression algorithm most appropriate for +their data. Stream compression typically reduces the amount of +information written to disk by 30-80%. + +WiredTiger supports leaf pages of up to 512MB in size. Disk seeks are +less likely when reading large amounts of data from disk, significantly +improving table scan performance. + +Also, as noted in the @ref cache section, WiredTiger supports +column-store formats, prefix compression and static encoding. While +each of these features makes WiredTiger's use of memory more efficient, +they also maximize the amount of useful data transferred per disk I/O. + +@section quality Production quality + +WiredTiger is production quality, supported software, engineered for the +most demanding application environments. For example, as a no-overwrite +data engine, torn writes can never corrupt a WiredTiger data store. + +WiredTiger includes verification support so you can verify data sets, +and salvage support as a last-ditch protection: data can be retrieved +even if it somehow becomes corrupted. + +@section nosql NoSQL and Open Source + +WiredTiger is an Open Source, NoSQL data engine. See the @ref license +for details. + +*/ diff --git a/src/docs/basic-api.dox b/src/docs/basic-api.dox new file mode 100644 index 00000000000..d7098e9ab61 --- /dev/null +++ b/src/docs/basic-api.dox @@ -0,0 +1,115 @@ +/*! @page basic_api Getting Started with the API + +WiredTiger applications will generally use the following classes to access +and manage data: + + - a WT_CONNECTION represents a connection to a database. Most + applications will only open one connection to a database for each process. + All methods in WT_CONNECTION are thread safe. + + - a WT_SESSION represents a context in which database operations are + performed. Sessions are opened on a specified connection, and + applications must open a single session for each thread accessing the + database. + + - a WT_CURSOR represents a cursor over a collection of data. Cursors are + opened in the context of a session (which may have an associated + transaction), and can query and update records. In the common case, a + cursor is used to access records in a table. However, cursors can be used + on subsets of tables (such as a single column or a projection of multiple + columns), as an interface to statistics, configuration data or + application-specific data sources. + +Handles and operations are @ref config_strings "configured using strings", +which keeps the set of methods in the API relatively small and makes the +interface very similar regardless of the programming language used in the +application. WiredTiger supports the C, C++, Java and Python programming +languages (among others). + +By default, WiredTiger works as a traditional key/value store, where the +keys and values are raw byte arrays accessed using a WT_ITEM structure. +Keys and values may be up to (4GB - 512B) bytes in size, but depending +on how @ref WT_SESSION::create "maximum item sizes" are configured, +large key and value items will be stored on overflow pages. + +WiredTiger also supports a @ref schema "schema layer" so that keys and +values types can be chosen from a list, or composite keys or values made +up of columns with any combination of types. The size (4GB - 512B) byte +limit on keys and values still applies. + +All applications that use WiredTiger will be structured roughly as follows. +The code below is taken from the complete example program +@ex_ref{ex_access.c}. + +@section basic_connection Connecting to a database + +To access a database, first open a connection and create a session handle +for the single thread accessing the database: + +@snippet ex_access.c access example connection + +The configuration string @c "create" is passed to ::wiredtiger_open to +indicate the database should be created if it does not already exist. + +The code block above also shows simple error handling with +::wiredtiger_strerror (a function that returns a string describing an +error code passed as its argument). More complex error handling can be +configured by passing an implementation of WT_ERROR_HANDLER to +wiredtiger_open or WT_CONNECTION::open_session. + +@section basic_create_table Creating a table + +Create a table we can use to store data: + +@snippet ex_access.c access example table create + +This call creates a table called @c "access", configured to use strings +for its key and value columns. (See @ref schema for more information +on tables with other types of key and value columns.) + +@section basic_cursors Accessing data with cursors + +Now that we have a table, we open a cursor to perform some operations +on it: + +@snippet ex_access.c access example cursor open + +Here, the string @c "table:access" specifies that we are opening the +cursor on the table named @c "access". + +Then we insert a new row into the table. The WT_CURSOR::set_key and +WT_CURSOR::set_value calls put the application's data into the cursor. +The WT_CURSOR::insert call creates a record containing that data and +inserts it into the table. + +@snippet ex_access.c access example cursor insert + +Now we iterate through all of the records in the table, printing them out +as we go: + +@snippet ex_access.c access example cursor list + +Note that the key and value parts of the records are returned as C +strings because the table was created that way (even if it was created +by a previous run of the example). No data extraction or conversion is +required in the application. + +Because the cursor was positioned in the table after the WT_CURSOR::insert +call, we had to re-position it using the WT_CURSOR::first call; if we +weren't using the cursor for the call to WT_CURSOR::insert above, this loop +would simplify to: + +@code + while ((ret = cursor->next(cursor)) == 0) { + ... + } +@endcode + +@section basic_close Closing handles + +Lastly, we close the connection, which implicitly closes the cursor and +session handles: + +@snippet ex_access.c access example close + + */ diff --git a/src/docs/build-javadoc.sh b/src/docs/build-javadoc.sh new file mode 100755 index 00000000000..c413db28d33 --- /dev/null +++ b/src/docs/build-javadoc.sh @@ -0,0 +1,12 @@ +DOCS=`dirname $0` +TOP=$DOCS/.. +. $TOP/config.sh + +CLASSPATH=$THRIFT_HOME/libthrift.jar:$SLF4J_JAR javadoc -public -d $DOCS/java \ + -source 1.5 \ + -sourcepath $TOP/lang/java/src:$TOP/src/server/gen-java \ + -stylesheetfile $DOCS/style/javadoc.css \ + -use -link http://java.sun.com/j2se/1.5.0/docs/api/ \ + -header '<b>WiredTiger API</b><br><font size="-1"> version '$WT_VERSION'</font>' \ + -windowtitle 'WiredTiger Java API' -bottom '<font size=1>Copyright (c) 2008-2012 WiredTiger, Inc. All rights reserved.</font>' \ + com.wiredtiger com.wiredtiger.util diff --git a/src/docs/build-pydoc.sh b/src/docs/build-pydoc.sh new file mode 100755 index 00000000000..5e6e3635be5 --- /dev/null +++ b/src/docs/build-pydoc.sh @@ -0,0 +1,6 @@ +DOCS=`dirname $0` +TOP=$DOCS/.. +. $TOP/config.sh + +cd python +PYTHONPATH=../../lang/python/src:$THRIFT_HOME/lib/python2.6/site-packages pydoc -w wiredtiger diff --git a/src/docs/command-line.dox b/src/docs/command-line.dox new file mode 100644 index 00000000000..d2180440922 --- /dev/null +++ b/src/docs/command-line.dox @@ -0,0 +1,353 @@ +/*! @page command_line WiredTiger command line utility + +WiredTiger includes a command line utility, \c wt. + +@section Synopsis +<code>wt [-Vv] [-C config] [-h directory] command [command-specific arguments]</code> + +@section Description +The \c wt tool is a command-line utility that provides access to +various pieces of the WiredTiger functionality. + +@section Options +There are three global options: + +@par <code>-C config</code> +Specify configuration strings for the ::wiredtiger_open function. +@par <code>-h directory</code> +Specify a database home directory. +@par <code>-V</code> +Display WiredTiger version and exit. +@par <code>-v</code> +Set verbose output. + +Unless otherwise described by a \c wt command, the \c wt tool exits zero +on success and non-zero on error. + +The \c wt tool supports several commands. + +<hr> +@section utility_create wt create +Create a table or file. + +The \c create command creates the specified \c uri with the specified +configuration. It is equivalent to a call to WT_SESSION::create with +the specified string arguments. + +@subsection utility_create_synopsis Synopsis +<code>wt [-Vv] [-C config] [-h directory] create [-c config] uri</code> + +@subsection utility_create_options Options +The following are command-specific options for the \c create command: + +@par <code>-c</code> +Include a configuration string to be passed to WT_SESSION::create. + +<hr> +@section utility_drop wt drop +Drop a table or file. + +The \c drop command drops the specified \c uri. It is equivalent to a +call to WT_SESSION::drop with the "force" configuration argument. + +@subsection utility_drop_synopsis Synopsis +<code>wt [-Vv] [-C config] [-h directory] drop [-s snapshot] uri</code> + +@subsection utility_drop_options Options +The following are command-specific options for the \c drop command: + +@par <code>-s</code> +Specify one more more snapshots to drop; the argument must be either the +name of a single snapshot to drop (a string), or a list containing one +of the following keys: "all" to drop all snapshots, "from=<snapshot>" +to drop all snapshots after and including the named snapshots, or +"to=<snapshot>" to drop all snapshots before and including the named +snapshot. + +<hr> +@section utility_dump wt dump +Export data in a text format. + +The \c dump command outputs the specified table in a portable format +which can be re-loaded into a new table using the \c load command. + +See @subpage dump_formats for details of the dump file formats. + +@subsection utility_dump_synopsis Synopsis +<code>wt [-Vv] [-C config] [-h directory] dump [-rx] [-f output] [-s snapshot] uri</code> + +@subsection utility_dump_options Options +The following are command-specific options for the \c dump command: + +@par <code>-f</code> +By default, the \c dump command output is written to the standard output; +the \c -f option re-directs the output to the specified file. + +@par <code>-r</code> +Dump in reverse order, from largest to smallest. + +@par <code>-s</code> +By default, the \c dump command opens the most recent snapshot of the object; +the \c -s option changes the \c dump command to open the named snapshot. + +@par <code>-x</code> +Dump all characters in a hexadecimal encoding (the default is to leave +printable characters unencoded). + +<hr> +@section utility_dumpfile wt dumpfile +Dump a file in a debugging format. + +The \c dumpfile command dumps the specified physical file in a non-portable, +debugging format, exiting success if the file is correct, and failure if the +file is corrupted. + +@subsection utility_dumpfile_synopsis Synopsis +<code>wt [-Vv] [-C config] [-h directory] dumpfile [-f output] file</code> + +@subsection utility_dumpfile_options Options +The following are command-specific options for the \c dumpfile command: + +@par <code>-f</code> +By default, the \c dumpfile command output is written to the standard +output; the \c -f option re-directs the output to the specified +file. + +<hr> +@section utility_read wt list +List the tables and files in the database. + +By default, the \c list command prints out the tables and files stored +in the database. If an object name is specified as an argument, only +information about that object is printed. + +@subsection utility_list_synopsis Synopsis +<code>wt [-Vv] [-C config] [-h directory] list [-sv] [uri]</code> + +@subsection utility_list_options Options +The following are command-specific options for the \c list command: + +@par <code>-s</code> +If the \c -s option is specified, the object's snapshots are printed +in a human-readable format. + +@par <code>-v</code> +If the \c -v option is specified, the object's complete schema table +value is printed. + +<hr> +@section utility_rename wt rename +Rename a table or file. + +The \c rename command renames the specified table or file. + +@subsection utility_rename_synopsis Synopsis +<code>wt [-Vv] [-C config] [-h directory] rename uri name</code> + +@subsection utility_rename_options Options +The \c rename command has no command-specific options. + +<hr> +@section utility_load wt load +Load a table or file from dump output. + +The \c load command reads the standard input for data and loads it into +a table or file, creating the table or file if it does not yet exist. +The data should be the format produced by the \c dump command; see @ref +dump_formats for details. + +By default, if the table or file already exists, data in the file or +table cannot be overwritten by the new data (use the \c -o option to +overwrite existing data). + +@subsection utility_load_synopsis Synopsis +<code>wt [-Vv] [-C config] [-h directory] load [-ao] [-f input] [-r name] [uri configuration ...]</code> + +@subsection utility_load_options Options +The following are command-specific options for the \c load command: + +@par <code>-a</code> +If the \c -a option is specified, record number keys in the input are +ignored and the data is appended to the object and assigned new record +number keys. The \c -a option is only applicable when loading an object +where the primary key is a record number. + +@par <code>-f</code> +By default, the \c load command reads from the standard input; the \c +-f option reads the input from the specified file. + +@par <code>-r</code> +By default, the \c load command uses the table or file name taken from +the input; the \c -r option renames the object. + +@par <code>-o</code> +By default, input data will not overwrite existing data where the +key/value pair already exists in the object, and the attempt will fail; +the \c -o option causes the \c load command to overwrite already +existing data. + +Additionally, \c uri and \c configuration pairs may be specified to the +\c load command. Each of these pairs may be used to modify the +configuration of an object in the table or file. For each of the pairs, +the configuration string will be appended to the WT_SESSION::create call +for the object matching the uri. + +<hr> +@section utility_loadtext wt loadtext +Load text into a table or file. + +The \c loadtext command reads the standard input for text and loads it +into a table or file. The input data should be printable characters, +with newline delimiters for each key or value. + +The \c loadtext command does not create the file if it does not yet +exist. + +In the case of inserting values into a column-store table or file, each +value is appended to the table or file; in the case of inserting values +into a row-store table or file, lines are handled in pairs, where the +first line is the key and the second line is the value. If the +row-store table or file already exists, data in the table or file will +be overwritten by the new data. + +@subsection utility_loadtext_synopsis Synopsis +<code>wt [-Vv] [-C config] [-h directory] loadtext [-f input]</code> + +@subsection utility_loadtext_options Options +The following are command-specific options for the \c loadtext command: + +@par <code>-f</code> +By default, the \c loadtext command reads from the standard input; the +\c -f option reads the input from the specified file. + +<hr> +@section utility_printlog wt printlog +Display the database log. + +The \c printlog command outputs the database log. + +@subsection utility_printlog_synopsis Synopsis +<code>wt [-Vv] [-C config] [-h directory] printlog [-p] [-f output]</code> + +@subsection utility_printlog_options Options +The following are command-specific options for the \c printlog command: + +@par <code>-f</code> +By default, the \c printlog command output is written to the standard +output; the \c -f option re-directs the output to the specified file. + +@par <code>-p</code> +Display the log in a printable format. + +<hr> +@section utility_read wt read +Read records from a table or file. + +The \c read command prints out the records associated with the specified +keys from the specified object. + +The object must be configured with string or record number keys and +string values. + +The \c read command exits non-zero if a specified record is not found. + +@subsection utility_read_synopsis Synopsis +<code>wt [-Vv] [-C config] [-h directory] read uri key ...</code> + +@subsection utility_read_options Options +The \c read command has no command-specific options. + +<hr> +@section utility_salvage wt salvage +Recover data from a corrupted file. + +The \c salvage command salvages the specified object, discarding any +data that cannot be recovered. Underlying files are re-written in +place, overwriting the original file contents. + +@subsection utility_salvage_synopsis Synopsis +<code>wt [-Vv] [-C config] [-h directory] salvage [-F force] uri</code> + +@subsection utility_salvage_options Options +The following are command-specific options for the \c salvage command: + +@par <code>-F</code> +By default, salvage will refuse to salvage files that fail basic tests +(for example, files that don't appear to be in a WiredTiger format). +The \c -F option forces the salvage of the file, regardless. + +<hr> +@section utility_stat wt stat +Display database or object statistics. + +The \c stat command outputs run-time statistics for the WiredTiger +engine, or, if specified, for the command-line object. + +@subsection utility_stat_synopsis Synopsis +<code>wt [-Vv] [-C config] [-h directory] stat [uri]</code> + +@subsection utility_stat_options Options +The \c stat command has no command-specific options. + +<hr> +@section utility_upgrade wt upgrade +Upgrade a table or file. + +The \c upgrade command upgrades the specified table or file, exiting +success if the object up-to-date, and failure if the object cannot be +upgraded. + +@subsection utility_upgrade_synopsis Synopsis +<code>wt [-Vv] [-C config] [-h directory] upgrade uri</code> + +@subsection utility_upgrade_options Options +The \c upgrade command has no command-specific options. + +<hr> +@section utility_verify wt verify +Check the structural integrity of a table or file. + +The \c verify command verifies the specified table or file, exiting +success if the object is correct, and failure if the object is corrupted. + +@subsection utility_verify_synopsis Synopsis +<code>wt [-Vv] [-C config] [-h directory] verify uri</code> + +@subsection utility_verify_options Options +The \c verify command has no command-specific options. + +<hr> +@section utility_write wt write +Write records to a table or file. + +The \c write command stores records into the specified object. + +The object must be configured with string or record number keys and +string values. + +If the \c write command is called with the \c -a option, each +command-line argument is a single value to be appended to the specified +column-store object. If the \c write command is not called with the \c +-a option, the command-line arguments are key/value pairs. + +Attempting to overwrite an already existing record will fail. + +@subsection utility_write_synopsis Synopsis +<code> +wt [-Vv] [-C config] [-h directory] write -a uri value ... +<br> +wt [-Vv] [-C config] [-h directory] write [-o] uri key value ... +</code> + +@subsection utility_write_options Options +The following are command-specific options for the \c write command: + +@par <code>-a</code> +Append each value as a new record in the object. + +@par <code>-o</code> +By default, attempting to overwrite an already existing record will +fail. The \c -o option changes \c write to overwrite previously +existing records. + +*/ diff --git a/src/docs/compression.dox b/src/docs/compression.dox new file mode 100644 index 00000000000..c2223f0a404 --- /dev/null +++ b/src/docs/compression.dox @@ -0,0 +1,47 @@ +/*! @page compression Compressors + +This section explains how to use compression engines with WiredTiger, including the builtin support for bzip2 and snappy. + +@section bzip2 Using bzip2 compression + +To use the builtin <a href="http://www.bzip.org/">bzip2</a> compression, first verify that bzip2 is installed on your system. On most UNIX and Linux variants, there will be a <code>bzlib.h</code> header file in the include directory for the compiler, as well as a library file available, often named <code>libbz2.so</code>, in <code>/usr/lib</code>. If these are available, you can simply enable bzip2 by using the \c --enable-bzip2 option when running configure. + +If you have installed your own version of bzip2 in a non-standard location, you'll need to modify the \c CPPFLAGS and \c LDFLAGS to indicate these locations. For example, with bzip2 includes and libraries installed in <code>/usr/local/include</code> and <code>/usr/local/lib</code>, run configure as: + +@code +cd build_posix +../dist/configure --enable-bzip2 CPPFLAGS="-I/usr/local/include" LDFLAGS="-L/usr/local/include" +@endcode + +After building, check that this compressor is built and working by running the compression part of the test suite: + +@code +cd build_posix +python ../test/suite/run.py compress +@endcode + +Verify that the bzip2 part of the test passes and was not skipped. + +@section snappy Using snappy compression + +Google's <a href="http://code.google.com/p/snappy/">snappy</a> compressor is generally not installed by default on UNIX and Linux distributions, so you will need to download, build and install it first. To configure WiredTiger to include snappy, use the \c --enable-snappy option along with \c CPPFLAGS and \c LDFLAGS. For example, with snappy includes and libraries installed in <code>/usr/local/include</code> and <code>/usr/local/lib</code>, run configure as: + +@code +cd build_posix +../dist/configure --enable-snappy CPPFLAGS="-I/usr/local/include" LDFLAGS="-L/usr/local/include" +@endcode + +After building, check that this compressor is built and working by running the compression part of the test suite: + +@code +cd build_posix +python ../test/suite/run.py compress +@endcode + +Verify that the snappy part of the test passes and was not skipped. + +@section custom Custom compression engines + +WiredTiger may be extended by adding custom compression engines; see @ref WT_COMPRESSOR for more information. + + */ diff --git a/src/docs/config-file.dox b/src/docs/config-file.dox new file mode 100644 index 00000000000..59a92901c68 --- /dev/null +++ b/src/docs/config-file.dox @@ -0,0 +1,34 @@ +/*! @page config_file WiredTiger Configuration File + +If a file named \c WiredTiger.config appears in the WiredTiger home +directory, it is read as a configuration string. Configuration values +specified in the config argument to the wiredtiger_open function +override configuration values specified in the \c WiredTiger.config file. + +The file is minimally parsed in order to build configuration strings +for the WiredTiger configuration parser: +<ul> + +<li>A backslash (<b><tt>\\</tt></b>) followed by any character other +than a newline character leaves both characters untouched; otherwise, +if a backslash is followed by a newline character, both the backslash +and the newline character are discarded. + +<li>Any text between double-quote pairs (<b><tt>"</tt></b>) is left +untouched, including newline and white-space characters. Backslash +characters escape double-quote characters: a backslash escaped +double-quote character can neither start or end a quoted string. + +<li>Comments are discarded. If the first non-white-space character +following an unquoted and unescaped newline character is a hash mark +(<b><tt>#</tt></b>), all characters up to the next newline character are +discarded. The ending newline character cannot be escaped or quoted, +once a comment line is identified, all characters to the next newline +are simply discarded. + +<li>Otherwise, all lines are concatenated and the newline characters +replaced with commas. + +</ul> + +*/ diff --git a/src/docs/config-strings.dox b/src/docs/config-strings.dox new file mode 100644 index 00000000000..65f78c19946 --- /dev/null +++ b/src/docs/config-strings.dox @@ -0,0 +1,80 @@ +/*! @page config_strings Configuration Strings + +@section config_intro Introduction + +Many operations in WiredTiger accept a string to configure options. These +strings all have the same format: + +<pre> + [key['='value]][','[key['='value]]]* +</pre> + +That is, they are simple comma-separated lists of +<code>"<key>=<value>"</code> pairs. If the <code>"=<value>"</code> part is +omitted, the value of 1 is assumed. + +To handle more complex configuration, such as specifying a schema, values +may be nested lists using parentheses. For example: + +<pre> + schema=(keyfmt=S,valuefmt=S,columns=(name,notes)) +</pre> + +Empty configuration strings may be represented in C or C++ by passing +<code>NULL</code>. + +Superfluous commas and whitespace in the configuration string are ignored +(including at the beginning and end of the string), so it is always safe to +combine two configuration strings by concatenating them with a comma in +between. + +Keys are processed in order from left to right, with later settings +overriding earlier ones unless multiple settings for a key are permitted. + +@section config_json JSON compatibility + +The parser for configuration strings will accept additional formatting as +follows: + +- parentheses may be round or square brackets or curly braces: + <code>'()'</code>, <code>'[]'</code> or <code>'{}'</code> +- the whole configuration string may optionally be wrapped in parentheses +- the key/value separator can be a colon: <code>':'</code> +- keys and values may be in double quotes: <code>"key" = "value"</code> +- quoted strings are interpreted as UTF-8 values + +The result of this relaxed parsing is that applications may pass strings +representing valid <a href="http://json.org/">JSON objects</a> wherever +configuration strings are required. + +For example, in Python, code might look as follows: + +\code + import json + config = json.dumps({ + "key_format" : "r", + "value_format" : "5sHQ", + "columns" : ("id", "country", "year", "population"), + "colgroup.population" : ["population"], + "index.country_year" : ["country", "year"] + }) +\endcode + +@section config_examples Code samples + +@todo improve the example + +Open a connection to a database, creating it if it does not exist and set a +cache size of 10MB, then open a session in the database: + +@snippet ex_config.c configure cache size + +Create a table that uses C language strings for keys and values: + +@snippet ex_config.c create a table + +Walk a transactional cursor through the table: + +@snippet ex_config.c transaction + +*/ diff --git a/src/docs/cursor-ops.dox b/src/docs/cursor-ops.dox new file mode 100644 index 00000000000..ad5825f100b --- /dev/null +++ b/src/docs/cursor-ops.dox @@ -0,0 +1,97 @@ +/*! @page cursor_ops Cursor operations + +Common operations in WiredTiger are performed using WT_CURSOR handles. +A cursor includes: + +- a position within a data source +- getter/setters for key and value fields +- encoding of fields to store in the data source +- methods to navigate within and iterate through the data + +@section cursor_opening Opening a cursor + +Cursors are created using the WT_SESSION::open_cursor method. The +following are examples from the example program @ex_ref{ex_cursor.c}: + +@snippet ex_cursor.c open cursor #1 +@snippet ex_cursor.c open cursor #2 + +In addition to traditional data sources, cursors in WiredTiger are used +to access projections and even created data sources such as the run-time +statistics: + +@snippet ex_cursor.c open cursor #3 + +See @ref cursors for more information on available cursor types. + +@section cursor_position Positioning a cursor + +Cursors may be positioned at the beginning of the data source, the end of +the data source, at an exact key within the data source, and near a key +within the data source. + +To invalidate the position of a cursor so that subsequent iterations start +from the beginning or end of the data source, use the WT_CURSOR::reset method: + +@snippet ex_cursor.c cursor reset + +To move a cursor forward or backward in the data source, use the cursor +WT_CURSOR::next and WT_CURSOR::prev methods: + +@snippet ex_cursor.c cursor next +@snippet ex_cursor.c cursor prev + +If the WT_CURSOR::next and WT_CURSOR::prev methods are called on cursors +without a position in the data source, they are positioned at the beginning +or end of the data source, respectively. + +To position a cursor at a specific location in the data source, use the +WT_CURSOR::search method: + +@snippet ex_cursor.c cursor search + +To position a cursor at or near a location in the data source, use the +WT_CURSOR::search_near method: + +@snippet ex_cursor.c cursor search near + +@section cursor_writes Inserting and updating + +To insert new data, and optionally update existing data, using a cursor, +use the WT_CURSOR::insert method: + +@snippet ex_cursor.c cursor insert + +By default, when inserting into a row-store, the WT_CURSOR::insert method +returns an error if the key already exists in the store, otherwise it +inserts a new key/value pair. If the <code>overwrite</code> configuration +string is specified to the WT_SESSION::open_cursor method, any previously +existing key/value pair is updated to the new value rather than returning +an error. + +By default, when updating an underlying column-store, the WT_CURSOR::insert +method ignores the application's key value, instead, it allocates an unused +record number in the store and returns that record number in the +application's key. If the <code>overwrite</code> configuration string is +specified to the WT_SESSION::open_cursor method, the application's key +value will be used to specify the record number being inserted or updated. + +To update existing data using a cursor, use the WT_CURSOR::update method: + +@snippet ex_cursor.c cursor update + +In all cases, calling WT_CURSOR::update where the key does not already +exist in the store will return an error. + +To remove existing data using a cursor, use the WT_CURSOR::remove method: + +@snippet ex_cursor.c cursor remove + +@section cursor_error Cursor position after error + +After any cursor handle method failure, the cursor's position is +undetermined. Applications that cannot re-position the cursor after +failure must duplicate the cursor before calling a cursor method that will +attempt to re-position the cursor. @notyet{cursor duplication} + + */ diff --git a/src/docs/cursors.dox b/src/docs/cursors.dox new file mode 100644 index 00000000000..53b025a6845 --- /dev/null +++ b/src/docs/cursors.dox @@ -0,0 +1,61 @@ +/*! @page cursors Cursors + +Common operations in WiredTiger are performed using WT_CURSOR handles. +A cursor includes: + +- a position within a data source +- getter/setters for key and value fields +- encoding of fields to store in the data source +- methods to navigate within and iterate through the data + +See @subpage cursor_ops for a description of how to use cursors. + +@section cursor_types Cursor types + +The following are some of common builtin cursor types: + +<table> + @hrow{URI, Type} + @row{<tt>colgroup:\<tablename\>.\<columnset\></tt>, +column group cursor} + @row{<tt>table:\<tablename\></tt>, +table cursor (key=table key\, value=table value)} + @row{<tt>file:\<filename\></tt>, +file cursor (key=file key\, value=file value)} + @row{<tt>index:\<tablename\>.\<indexname\></tt>, +index cursor (key=index key\, value=table value)} + @row{<tt>statistics:[file</tt><tt>:\<filename\>]</tt>, + database or file statistics (key=(int)\, + value=(string)description\, (string)value\, (uint64_t)value)} +</table> + +See @subpage data_sources for the full list. + +@section cursor_projections Projections + +Cursors on tables, column groups and indices can return a subset of +columns. This is done by listing the column names in parenthesis in the +<code>uri</code> parameter to WT_SESSION::open_cursor. Only the fields +from the listed columns are returned by WT_CURSOR::get_value. + +This is particularly useful with index cursors, because if all columns in +the projection are available in the index (including primary key columns, +which are the values of the index), there is no need to access any column +groups. + +@section cursor_raw Raw mode + +Cursors can be configured for raw mode by specifying the \c "raw" config +keyword to WT_SESSION::open_cursor. In this mode, the methods +WT_CURSOR::get_key, WT_CURSOR::get_value, WT_CURSOR::set_key and +WT_CURSOR::set_value all take a single WT_ITEM in the variable-length +argument list instead of a separate argument for each column. + +For WT_CURSOR::get_key and WT_CURSOR::get_value in raw mode, the WT_ITEM +can be split into columns by calling ::wiredtiger_struct_unpack with the +cursor's \c key_format or \c value_format, respectively. For +WT_CURSOR::set_key and WT_CURSOR::set_value in raw mode, the WT_ITEM +should be equivalent to calling ::wiredtiger_struct_pack for the +cursor's \c key_format or \c value_format, respectively. + +*/ diff --git a/src/docs/data_sources.dox b/src/docs/data_sources.dox new file mode 100644 index 00000000000..2eaf2a99fe4 --- /dev/null +++ b/src/docs/data_sources.dox @@ -0,0 +1,87 @@ +/*! @page data_sources Data Sources + +WiredTiger provides access to data from a variety of sources. At the +lowest level, data may be stored in a file using a tree structure. A +relational schema supporting tables, indices and column groups is +layered on top of file. Additional sources include LSM trees and +statistics, and applications can further extend the supported types by +implementing the ::WT_DATA_SOURCE interface. + +Common operations on all data sources are performed using WT_CURSOR +handles. See @subpage cursor_ops for a description of how to use +cursors. + +@section data_builtin Builtin data sources + +The following are the builtin cursor types: + +<table> + @hrow{URI, Type} + @row{<tt>colgroup:\<tablename\>.\<columnset\></tt>, +column group cursor} + @row{<tt>config:[\<uri\>]</tt>, +object configuration cursor (key=config string\, +value=config value} + @row{<tt>table:\<tablename\></tt>, +table cursor (key=table key\, value=table value)} + @row{<tt>file:\<filename\></tt>, +file cursor (key=file key\, value=file value)} + @row{<tt>index:\<tablename\>.\<indexname\></tt>, +index cursor (key=index key\, value=table value)} + @row{<tt>join:\<cursor1\>\&\<cursor2\>[&\<cursor3\>...]</tt>, +join cursor @notyet{join cursors}} + @row{<tt>statistics:[file</tt><tt>:\<filename\>]</tt>, + database or file statistics (key=(int)\, + value=(string)description\, (string)value\, (uint64_t)value)} +</table> + +@subsection data_files Raw Files + +WiredTiger's schema layer can be bypassed by opening cursors with a \c +"file:" URI, using the name of the underlying file. This can be useful for +seeing the contents of a column group or index without reading all of the +columns from the table. + +For example, if an index becomes inconsistent with its primary, a file +cursor can read from the index without errors (even though some of the keys +that are returned may not exist in the primary). + +@subsection data_indices Table Index data + +When an index is created for a table, records are inserted into the index +whenever the table is updated. These records use a different key to the +primary table, as specified when the index is created with the +WT_SESSION::create method. + +A cursor opened on an index has the specified index columns as its key, +accessed by WT_CURSOR::set_key and WT_CURSOR::get_key. The value columns +default to returning the value columns from the table, but this can be +overridden by configuring a projection cursor (see @ref cursor_projections), +which can access the table key columns or a subset of the value columns. + +@subsection data_statistics Statistics Data + +Cursors can return run-time statistics about the WiredTiger engine as +well as statistics for the underlying row- and column-store files. Each +cursor iteration sets three separate values: a printable description of +the entry, a printable version of the entry's value, and the entry's +unsigned 64-bit integral value. + +The statistic key is an integer from the list of keys in @ref statistics_keys +"Statistics Keys". + +The following is an example of printing run-time statistics about the +WiredTiger engine: + +@snippet ex_stat.c statistics database function + +The following is an example of printing statistics about an underlying +file: + +@snippet ex_stat.c statistics file function + +Both examples can use a common display routine that iterates through the +statistics until the cursor returns the end of the list. + +@snippet ex_stat.c statistics display function +*/ diff --git a/src/docs/dump-formats.dox b/src/docs/dump-formats.dox new file mode 100644 index 00000000000..0c021e3a29b --- /dev/null +++ b/src/docs/dump-formats.dox @@ -0,0 +1,51 @@ +/*! @page dump_formats Dump Formats + +The @ref utility_dump command produces a text representation of a table +that can be loaded by @ref utility_load. This page describes the output +format of the @ref utility_dump command. + +Dump files have three parts, a prefix, a header and a body. + +The dump prefix includes basic information about the dump including the +WiredTiger version that created the dump and the dump format. The dump +format consists of a line beginning with \c "Format=", and contains the +following information: + +<table> +@hrow{String, Meaning} +@row{hex, the dumped data is in a hexadecimal dump format} +@row{print, the dumped data is in a printable format} +</table> + +The dump header follows a single \c "Header" line in the file and +consists of paired key and value lines, where the key is the URI passed +to WT_SESSION::create and the value is corresponding configuration +string. The table or file can be recreated by calling +WT_SESSION::create for each pair of lines in the header. + +The dump body follows a single \c "Data" line in the file and consists +of a text representation of the records in the table. Each record is a +represented by a pair of lines: the first line is the key and the second +line is the value. These lines are encoded in one of two formats: a +printable format and a hexadecimal format. + +The printable format consists of literal printable characters, and +hexadecimal encoded non-printable characters. Encoded characters are +written as three separate characters: a backslash character followed by +two hexadecimal characters (first the high nibble and then the low +nibble). For example, a newline character in the ASCII character set +would be encoded as \c "\0a" and an escape character would be encoded +as \c "\1b". Backslash characters which do not precede a hexadecimal +encoding are paired, that is, the characters \c "\\" should be +interpreted as a single backslash character. + +The hexadecimal format consists of encoded characters, where each +literal character is written as a pair of characters (first the +high-nibble and then the low-nibble). For example, "0a" would be an +ASCII newline character and "1b" would be an ASCII escape character. + +Because the definition of "printable" may depend on the application's +locale, dump files in the printable output format may be less portable +than dump files in the hexadecimal output format. + + */ diff --git a/src/docs/examples.dox b/src/docs/examples.dox new file mode 100644 index 00000000000..d0a249aecb6 --- /dev/null +++ b/src/docs/examples.dox @@ -0,0 +1,44 @@ +/*! +@example ex_hello.c +This is an example of how to create and open a database. + +@example ex_access.c +Create, insert and access a simple table. + +@example ex_all.c +Demonstrate how to call every method in the API. + +@example ex_config.c +Shows how to configure some properties of the database and tables. + +@example ex_cursor.c +Shows some common cursor types and operations. + +@example ex_pack.c +Shows basic packing and unpacking of fields. + +@cond sharing +@notyet{inter-process sharing} +@example ex_process.c +Shows how to connect to a database from multiple processes. +@endcond + +@example ex_stat.c +Shows how to access database and table statistics. + +@example ex_schema.c +Shows how to create column-oriented data and access individual columns. + +@example ex_thread.c +Shows how to access a database with multiple threads. + +@example ex_transaction.c +Shows how to use transactions. @notyet{transactions} + +@example ex_call_center.c +A more complex schema based on a call center example, showing how to map some +SQL constructs onto the WiredTiger API. + +@example ex_extending.c +Shows how to extend WiredTiger with application-specific collations, extractors and cursor types. + */ diff --git a/src/docs/file-formats.dox b/src/docs/file-formats.dox new file mode 100644 index 00000000000..538709673d4 --- /dev/null +++ b/src/docs/file-formats.dox @@ -0,0 +1,72 @@ +/*! @page file_formats WiredTiger files + +@section formats File formats + +WiredTiger supports two underlying file formats: row-store and +column-store. WiredTiger row- and column-stores are both key/value +stores. + +In a row-store, both keys and data are variable-length byte strings. In +a column-store, the key is a 64-bit record number, and the data item is +either a variable- or fixed-length byte string. + +Generally, row-stores are faster for queries where a set of columns are +required by every lookup (because there's only a single set of meta-data +pages to go through, or read into the cache). Column-stores are faster +for queries where only a few of the columns are required for any lookup +(because only the columns being returned are present in the cache). + +Row-stores support three types of compression: prefix compression (where +any identical portion of each key byte string is only stored once), +Huffman encoding of individual key/value items, (see @subpage huffman +for details), and stream compression of the blocks in the file (see @ref +compression for details). + +Unlike some row-stores, WiredTiger does not support duplicate data +items, that is, for any single key, there can be only a single value, +and applications are responsible for creating unique key/value pairs. + +Column-stores with variable-length byte string values support three +types of compression: run-length encoding (where duplicate values are +only stored a single time), Huffman encoding of individual value items, +(see @ref huffman for details), and stream compression of the blocks in +the file (see @ref compression for details). + +Column-stores with fixed-length byte values support a single type of +compression: stream compression of the blocks in the file (see @ref +compression for details). + +In row-stores, keys and values too large to fit on a normal page are +stored as overflow items in the file. In variable-length column-stores, +values too large to fit on a normal page are stored as overflow items +in the file. + +WiredTiger allocates space from the underlying files in block units. +The minimum file allocation unit WiredTiger supports is 512B and the +maximum file allocation unit is 512MB. File block offsets are 64-bit +(meaning the maximum file size is very, very large). + +Variable-length column-store values, and row-store keys and values, can +be up to (4GB - 512B) in length. + +Fixed-length values are limited to 8-bits (that is, only values between +0 and 255 may be stored in fixed-length column-store files). + +@section remote Remote file systems + +WiredTiger objects may be stored on remote file systems if the remote +file system conforms to ISO/IEC 9945-1:1996 (POSIX.1). In the case of +read-only objects, multiple systems may access the objects +simultaneously; objects which are written cannot be accessed by more +than a single system. Because remote file systems are often slower than +local file systems, using a remote file system for storage may degrade +performance. + +@section file File permissions + +WiredTiger creates file system objects readable and writable by the +process owner, group and user, as modified by the process' umask value. +The group ownership of created file system objects may vary depending +on the system, and is not controlled by WiredTiger. + +*/ diff --git a/src/docs/home.dox b/src/docs/home.dox new file mode 100644 index 00000000000..222e0400f75 --- /dev/null +++ b/src/docs/home.dox @@ -0,0 +1,57 @@ +/*! @page home WiredTiger Home Directory + +WiredTiger file naming is based on the \c home argument specified to the +::wiredtiger_open function and the \c WIREDTIGER_HOME environment +variable. + +If a \c home argument is specified to the ::wiredtiger_open function, +its value is used as the database directory and the \c WIREDTIGER_HOME +environment variable is always ignored. + +If no \c home argument is specified to the ::wiredtiger_open function +and the WIREDTIGER_HOME environment variable is not set, the database +directory is the process' current working directory. No current working +directory path is maintained by the WiredTiger software and changing the +working directory after opening the WiredTiger database may cause +failure. + +If no \c home argument is specified to the ::wiredtiger_open function, +the WIREDTIGER_HOME environment variable is set, and the +::wiredtiger_open function was configured with the \c home_environment +string, the WIREDTIGER_HOME environment variable value is used as the +database directory. + +If no \c home argument is specified to the ::wiredtiger_open function, +the WIREDTIGER_HOME environment variable is set, the ::wiredtiger_open +function was configured with the \c home_environment_priv string, and +the user has appropriate privileges, the WIREDTIGER_HOME environment +value is used as the database directory. (The \c home_environment_priv +string is intended for applications that have or acquire special +privileges and wish to ensure an environment-specified home directory +is ignored unless the program is executed by a user with appropriate +permissions: if such an application does not configure the +::wiredtiger_open function with the \c home_environment_priv string, +setting an environment value will cause the open to fail unless the user +has appropriate permissions. On ISO/IEC 9945-1:1990 (POSIX.1) systems, +"appropriate permissions" is defined as a real user ID of 0.) + +If no \c home argument is specified to the ::wiredtiger_open function, +the WIREDTIGER_HOME environment variable is set, and the +::wiredtiger_open function was not configured with either the \c +home_environment or \c home_environment_priv strings, the open will +fail. + +Finally, consider security when configuring WiredTiger to use the +WIREDTIGER_HOME environment variable, especially in applications which +run with permissions other than the user's. Such applications are +potentially vulnerable to allowing users access to databases they could +not otherwise access. + +@section home_config Home directory configuration strings + +The WiredTiger home directory optionally includes a file named \c +WiredTiger.config. If this file exists when ::wiredtiger_open is +called, it is read for configuration strings. See @subpage config_file +for details. + +*/ diff --git a/src/docs/huffman.dox b/src/docs/huffman.dox new file mode 100644 index 00000000000..e4693873d66 --- /dev/null +++ b/src/docs/huffman.dox @@ -0,0 +1,64 @@ +/*! @page huffman Huffman Encoding + +Keys in row-stores and variable-length values in either row- or +column-stores can be compressed with Huffman encoding. + +Huffman compression is maintained in memory as well as on disk, and can +increase the amount of usable data the cache can hold as well as +decrease the size of the data on disk. + +To configure Huffman encoding for the key in a row-store, specify \c +"huffman_key=english", \c "huffman_key=utf8<file>" or \c +"huffman_key=utf16<file>" in the configuration passed to \c +WT_SESSION::create. + +To configure Huffman encoding for a variable-length value in either a +row-store or a column-store, specify "huffman_value=english", \c +"huffman_value=utf8<file>" or \c "huffman_value=utf16<file>" in the +configuration passed to \c WT_SESSION::create. + +Setting Huffman encoding to \c "english" configures WiredTiger to use a +built-in English language frequency table. + +Setting Huffman encoding to \c "utf8<file>" or \c "utf16<file>" +configures WiredTiger to use a frequency table read from a file. The +frequency table file format is lines containing pairs of unsigned +integers separated by whitespace. The first integer is the symbol +value, the second integer is the frequency value. Symbol values may be +specified as hexadecimal numbers (with a leading \c "0x" prefix), or as +integers. For example, an English-language frequency table for the +characters '0' through '9' might look like this: + +@code +0x30 546233 +0x31 460946 +0x32 333499 +0x33 187606 +0x34 192528 +0x35 374413 +0x36 153865 +0x37 120094 +0x38 182627 +0x39 282364 +@endcode + +Frequency table symbol values must be unique. In the case of \c utf8 +files, symbol values must be in the range of 0 to 255. In the case of +\c utf16 files, symbol values must be in the range of 0 to 65,535. +Frequency values do not need to be unique, but must be in the range of +0 to the maximum 32-bit unsigned integer value (4,294,967,295), where +the lower a frequency value, the less likely the byte value is to occur. + +Any symbol values not listed in the frequency table are assumed to have +frequencies of 0. Input containing symbol values that did not appear +in the frequency table (or appeared in the frequency table, but with +frequency values of 0), are accepted, but will not compress as well as +if they are listed in the frequency table, with frequency values other +than 0. + +The English language frequency table is based on \c "Case-sensitive +letter and bigram frequency counts from large-scale English corpora", +by Michael N. Jones and D.J.K. Mewhort, modified to support space and +tab characters. + +*/ diff --git a/src/docs/images/LogoFace-watermark.png b/src/docs/images/LogoFace-watermark.png Binary files differnew file mode 100644 index 00000000000..7af37f88a7c --- /dev/null +++ b/src/docs/images/LogoFace-watermark.png diff --git a/src/docs/images/LogoFinal-header.png b/src/docs/images/LogoFinal-header.png Binary files differnew file mode 100644 index 00000000000..fcbdb27ae81 --- /dev/null +++ b/src/docs/images/LogoFinal-header.png diff --git a/src/docs/images/architecture.pdf b/src/docs/images/architecture.pdf Binary files differnew file mode 100644 index 00000000000..ff97ddff2b4 --- /dev/null +++ b/src/docs/images/architecture.pdf diff --git a/src/docs/images/architecture.png b/src/docs/images/architecture.png Binary files differnew file mode 100644 index 00000000000..c5b72bc05e0 --- /dev/null +++ b/src/docs/images/architecture.png diff --git a/src/docs/install.dox b/src/docs/install.dox new file mode 100644 index 00000000000..dbf4712ba1d --- /dev/null +++ b/src/docs/install.dox @@ -0,0 +1,193 @@ +/*! @page install How to build and install WiredTiger + +This section explains how to build and install the WiredTiger software. + +@section github Building using Git and GitHub + +Skip this step if you are building from a WiredTiger release package, +and proceed with @ref building. + +To build from the WiredTiger GitHub repository requires +<a href="http://git-scm.com/">git</a>, +<a href="http://www.gnu.org/software/autoconf/autoconf.html">autoconf</a>, +<a href="http://www.gnu.org/software/autoconf/automake.html">automake</a>, +<a href="http://www.gnu.org/software/libtool/libtool.html">libtool</a> and +related tools. The standard options for those tools can be specified +when configuring and building WiredTiger. + +First, clone the repository: + +@code +git clone git://github.com/wiredtiger/wiredtiger.git +@endcode + +Second, run the \c build_posix/reconf script: + +@code +cd wiredtiger +sh build_posix/reconf +@endcode + +This creates the \c configure script, and you can now proceed with @ref +building. + +@section building Building WiredTiger + +To build the WiredTiger software on a POSIX-like system, change directory to +the top-level directory, then configure and build the software: + +@code +cd wiredtiger +./configure && make +@endcode + +To rebuild from scratch, discard any previous configuration by cleaning +out the build area: + +@code +make realclean +@endcode + +To see additional configuration options, run: + +@code +./configure --help +@endcode + +WiredTiger uses +<a href="http://www.gnu.org/software/autoconf/autoconf.html">autoconf</a> +<a href="http://www.gnu.org/software/autoconf/automake.html">automake</a>, +and <a href="http://www.gnu.org/software/libtool/libtool.html">libtool</a> +to create the configure script and Makefiles. The standard options for those +tools can be specified when configuring and building WiredTiger. + +@section installing Installing WiredTiger + +The WiredTiger software consists of a library and a single standalone +utility. + +WiredTiger's distribution follows the GNU Coding Standards installation +guidelines, and by default WiredTiger builds and installs four versions +of the library in <code>/usr/local/lib</code>. For example: + +@code +file /usr/local/lib/libwiredtiger* +/usr/local/lib/libwiredtiger-1.0.0.so: ELF 64-bit LSB shared object, x86-64, version 1 (FreeBSD), dynamically linked, not stripped +/usr/local/lib/libwiredtiger.a: current ar archive +/usr/local/lib/libwiredtiger.la: libtool library file +/usr/local/lib/libwiredtiger.so: symbolic link to `libwiredtiger-1.0.0.so' +@endcode + +WiredTiger uses +<a href="http://www.gnu.org/software/libtool/libtool.html">libtool</a> to +build the libraries. By default, both shared and static libraries are built. +To build only static libraries, configure WiredTiger using the +\c --disable-shared argument. To build only shared libraries, configure using +WiredTiger using the \c --disable-static argument. + +In addition, WiredTiger installs a standalone utility program named +<code>wt</code>. By default, this utility is installed in +<code>/usr/local/bin/wt</code>. + +To install WiredTiger: + +@code +make install +@endcode + +To uninstall WiredTiger: + +@code +make uninstall +@endcode + +To install WiredTiger's libraries or binaries into alternate locations, +use the configuration or installation options described in the +<a href="http://www.gnu.org/prep/standards/">GNU coding standards</a> +documentation. For example, to install the libraries and binaries into +a different location: + +@code +./configure --prefix=/c/wiredtiger +@endcode + +@section configure Configuring WiredTiger + +The WiredTiger software supports some additional configuration options: + +@par \c --enable-attach +Configure WiredTiger to sleep and wait for a debugger to attach on failure. +<b>DO NOT</b> configure this option in production environments. + +@par \c --enable-bzip2 +Configure WiredTiger for <a href="http://www.bzip.org/">bzip2</a> +compression; see @ref compression for more information. + +@par \c --enable-debug +Configure WiredTiger for debugging, including building with the +compiler's \c -g flag. +<b>DO NOT</b> configure this option in production environments. + +@par \c --enable-diagnostic +Configure WiredTiger to perform various run-time diagnostic tests. +<b>DO NOT</b> configure this option in production environments. + +@par \c --enable-python +Build the WiredTiger <a href="http://www.python.org">Python</a> API. + +@par \c --enable-snappy +Configure WiredTiger for <a href="http://code.google.com/p/snappy/">snappy</a> +compression; see @ref compression for more information. + +@par \c --enable-verbose +Configure WiredTiger to support the \c verbose configuration string to +::wiredtiger_open. + +@par <code>--with-spinlock</code> +Configure WiredTiger to use a specific mutex type, options are \c +pthread_mutex (the default, which configures WiredTiger to use POSIX 1003.1c +pthread mutexes for serialization) or \c gcc (which configures WiredTiger to +use gcc-based spinlocks for serialization). + +@section compiler Changing compiler or loader options + +To change the compiler or loader behavior during the build, use the +<code>CC</code>, <code>CFLAGS</code>, <code>LDFLAGS</code>, or +<code>LIBS</code> environment variables: + +@par \c CC +The compiler. +@par \c CFLAGS +Compiler flags. +@par \c LDFLAGS +Loader flags. +@par \c LIBS +Additional libraries. + +For example, to specify a different compiler: + +@code +env CC=mygcc ./configure +@endcode + +By default, WiredTiger builds with the \c -O3 compiler optimization flag +unless the \c --enable-debug configuration option is specified, in which +case the \c -g compiler flag is used instead. For example, to specify +a different level of optimization: + +@code +env CFLAGS=-Os ./configure +@endcode + +To specify a different set of include files: + +@code +env CFLAGS=-I/usr/local/include ./configure +@endcode + +To specify an additional library: + +@code +env LIBS="-lrtf -lmin" LDFLAGS=-L/usr/local/lib ./configure +@endcode + */ diff --git a/src/docs/introduction.dox b/src/docs/introduction.dox new file mode 100644 index 00000000000..84ddd0865c2 --- /dev/null +++ b/src/docs/introduction.dox @@ -0,0 +1,50 @@ +-/*! @mainpage Reference Guide + +WiredTiger is an high performance, scalable, production quality, NoSQL, +Open Source extensible platform for data management. + +WiredTiger supports both traditional row-oriented storage, where all +columns of a row are stored together, and column-oriented storage, where +one or more columns can be stored individually, allowing more efficient +access and storage. + +For more information on the WiredTiger architecture and why it might be +right for your project, see: + +- @subpage architecture. + +This documentation describes the programming interface to WiredTiger +used by developers to construct applications. We follow SQL +terminology: a database is set of tables managed together. Tables +consist of rows, where each row is a key and its associated value. +Tables may optionally have an associated schema, splitting the value +into a set of columns. Tables may also have associated indices, each +of which is ordered by one or more columns. + +WiredTiger distributions are tested on Linux, FreeBSD and Mac OS X. +WiredTiger should be portable to any system that supports the ANSI C99, +POSIX 1003.1 and POSIX 1003.1c (threads extension) standards. + +For more information about using WiredTiger, see: + +- @subpage install\n + +- @subpage programming\n + +- @ref wt "WiredTiger API reference manual" + +- @subpage command_line\n + +- @subpage admin\n + +- @subpage license\n + +To browse or download the WiredTiger source code, visit our + +- <a href="https://github.com/wiredtiger/wiredtiger"><b>Project page</b></a> + +To ask questions or discuss issues related to using WiredTiger, visit our + +- <a href="http://groups.google.com/group/wiredtiger-users"><b>User Group</b></a> + +*/ diff --git a/src/docs/keyvalue.dox b/src/docs/keyvalue.dox new file mode 100644 index 00000000000..f375886b030 --- /dev/null +++ b/src/docs/keyvalue.dox @@ -0,0 +1,19 @@ +/*! @page keyvalue Key/Value pairs + +Underlying WiredTiger files are key/value stores, that is, entries in +the file are paired keys and values. These keys and values can be +accessed directly, and a file cursor will only return the data from the +single file, without reference to any other related files or data. For +example, if an index were lost or to become inconsistent with its +primary, a file cursor could read from the index without problems (even +though some of the returned keys might not exist in the primary). + +In the case of a row-store file, keys and values are both +variable-length byte strings, up to (4GB - 512B) in length. + +In the case of a column-store file, keys are 64-bit record numbers, +where the first record in the file is record number 1. Values are +either variable-length byte strings, up to (4GB - 512B) in length, or +bit fields, where a bit field is 1 to 8 bits. + + */ diff --git a/src/docs/license.dox b/src/docs/license.dox new file mode 100644 index 00000000000..409bedea512 --- /dev/null +++ b/src/docs/license.dox @@ -0,0 +1,54 @@ +/*! @page license WiredTiger license + +The WiredTiger software is Open Source software: you may redistribute +it and modify it under the terms of version 3 of the +<a href="http://www.gnu.org/licenses/gpl-3.0-standalone.html"> +<b>GNU General Public License</b></a> +as published by the Free Software Foundation. The WiredTiger library +binary also includes software copyrighted under the terms of the +<a href="http://www.opensource.org/licenses/BSD-3-Clause"> +<b>University of California, Berkeley (BSD) 3-Clause License</b></a>. +Any redistribution should comply with both copyrights. + +This program is distributed in the hope that it will be useful, but +WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +<a href="http://www.gnu.org/licenses/gpl-3.0-standalone.html"> +<b>GNU General Public License</b></a> for details. + +For a license to use the WiredTiger software under conditions other than +those described above, or for technical support for this software, please +contact WiredTiger, Inc. at +<a mailto="info@wiredtiger.com">info@wiredtiger.com</a>. + +@section library 3rd party software included in the WiredTiger library binary + +The WiredTiger library binary includes the following 3rd party software, +distributed under the following licenses: + +<table> +@hrow{Distribution File, License} +@row{src/include/bitstring.i, University of California\, Berkeley (BSD) 3-Clause License} +@row{src/include/queue.h, University of California\, Berkeley (BSD) 3-Clause License} +@row{src/utilities/util_getopt.c, University of California\, Berkeley (BSD) 3-Clause License} +</table> + +@section distribution 3rd party software included in the WiredTiger distribution + +The WiredTiger distribution includes additional 3rd party software +licensed under a variety of licenses. This software is not included +in the WiredTiger library binary as built by the distribution, it is +only used to build and test the WiredTiger documentation and software. +If you extract portions of the WiredTiger distribution for inclusion in +other packages, or redistribute selected portions of the WiredTiger +sources, please review the copyright notices and LICENSE files included +in the WiredTiger distribution for the terms and conditions of such +redistribution. + +@section pd Public domain software + +Portions of this program are public domain software. Public domain +files have copyright notices releasing the software into the public +domain and may be freely used. + +*/ diff --git a/src/docs/namespace.dox b/src/docs/namespace.dox new file mode 100644 index 00000000000..1b2402dd4f2 --- /dev/null +++ b/src/docs/namespace.dox @@ -0,0 +1,22 @@ +/*! @page name_space WiredTiger name spaces + +@section c C language name space + +WiredTiger's public function names begin with the string "wiredtiger". + +WiredTiger's public \c \#define and structure \c typedef declarations +begin with the string "WT_". + +WiredTiger's private function names begin with the string "__wt__". + +@section filename File system name space + +WiredTiger's files begin with the string "WiredTiger"; applications +should not create files in the WiredTiger file system name space. + +@section error Error return name space + +WiredTiger reserves all values from -31,800 to -31,999 as possible error +return values. + +*/ diff --git a/src/docs/packing.dox b/src/docs/packing.dox new file mode 100644 index 00000000000..7723e21bc79 --- /dev/null +++ b/src/docs/packing.dox @@ -0,0 +1,35 @@ +/*! @page packing Packing and Unpacking Data + +WiredTiger's data packing uses format strings similar to those specified in the +Python struct module: + http://docs.python.org/library/struct + +The first character of the format string can be used to indicate the byte +order, size and alignment of the packed data, according to the following +table: + +<table> +@hrow{Character, Byte order, Size, Alignment} +@row{<tt>.</tt>, big-endian, packed, none} +@row{<tt>></tt>, big-endian, standard, none} +@row{<tt><</tt>, little-endian, standard, none} +@row{<tt>\@</tt>, native, native, native} +</table> + +If the first character is not one of these, '.' (big-endian, packed) is +assumed: it naturally sorts in lexicographic order, and the packed format +uses variable-sized encoding of values to reduce the data size. + +@notyet{format types} <b>Only the default big-endian, packed format is currently supported.</b> + +The remaining characters in the format string specify the type of each field to be packed into or unpacked from a byte array. See @ref schema_types for the list of supported types. + +@todo Describe the variable-length integer packing in sufficient detail that it can be re-implemented in other programming languages or in network clients. + +@section config_examples Code samples + +The code below is taken from the complete example program @ex_ref{ex_pack.c}. It demonstrates how to pack three integer values into a buffer and then unpack them again. + +@snippet ex_pack.c packing + + */ diff --git a/src/docs/processes.dox b/src/docs/processes.dox new file mode 100644 index 00000000000..87f715792f9 --- /dev/null +++ b/src/docs/processes.dox @@ -0,0 +1,28 @@ +/*! @page processes Sharing Between Processes + +@notyet{inter-process sharing} + +WiredTiger includes a server that provides remote access to databases. The primary process to open a database can optionally start a server that handles requests from other processes. + +The remote interface is the way languages other than C/C++ are supported, and the interface for client processes in multiprocess C/C++ applications. + +The server can be embedded in an application or run from the command line. To embed the RPC server in your application, pass <code>"multiprocess"</code> in the configuration string to ::wiredtiger_open. Note that in this case, when your application exits, all client connections are forcibly closed. + +For details on running a standalone RPC server, see @ref utility. + +@section processes_sharing Opening connections from multiple processes + +When ::wiredtiger_open is called for a database, one of the following occurs: + +# no process has the database open, it was closed cleanly. In this case, the opening process becomes the primary process and the database is opened without recovery. +# no process has the database open, but it was not closed cleanly. In this case, the process becomes the primary and recovery is run before the database is opened. See @ref transaction_recovery for details. +# another process has the database open and is running the RPC server, in which case the opening process becomes a client. +# another process has the database open but is not running the RPC server, in which case the open fails. + +@section processes_example Code samples + +The code below is taken from the complete example program @ex_ref{ex_process.c}. + +@snippet ex_process.c processes + + */ diff --git a/src/docs/programming.dox b/src/docs/programming.dox new file mode 100644 index 00000000000..f4041679dbb --- /dev/null +++ b/src/docs/programming.dox @@ -0,0 +1,16 @@ +/*! @page programming Writing WiredTiger applications + +This section explains how to write applications that use WiredTiger: + +- @subpage basic_api +- @subpage config_strings +- @subpage schema +- @subpage cursors +- @subpage threads +- @subpage snapshots +- @subpage transactions +- @subpage compression +- @subpage name_space +- @subpage signals + + */ diff --git a/src/docs/schema.dox b/src/docs/schema.dox new file mode 100644 index 00000000000..01b9572c0ff --- /dev/null +++ b/src/docs/schema.dox @@ -0,0 +1,206 @@ +/*! @page schema Schemas + +While many tables have simple key/value pairs for records, WiredTiger +also supports more complex data patterns. + +@section schema_intro Tables, rows and columns + +A table is a logical representation of data consisting of cells in rows and +columns. For example, a database might have this table. + +<table> +<tr><th>EmpId</th><th>Lastname</th><th>Firstname</th><th>Salary</th></tr> +<tr><td>1</td><td>Smith</td><td>Joe</td><td>40000</td></tr> +<tr><td>2</td><td>Jones</td><td>Mary</td><td>50000</td></tr> +<tr><td>3</td><td>Johnson</td><td>Cathy</td><td>44000</td></tr> +</table> + +This simple table includes an employee identifier, last name and first +name, and a salary. + +A row-oriented database would store all of the values in a row together, +then the values in the next row, and so on: + +<pre> + 1,Smith,Joe,40000; + 2,Jones,Mary,50000; + 3,Johnson,Cathy,44000; +</pre> + +A column-oriented database stores all of the values of a column together, +then the values of the next column, and so on: + +<pre> + 1,2,3; + Smith,Jones,Johnson; + Joe,Mary,Cathy; + 40000,50000,44000; +</pre> + +WiredTiger supports both storage formats, and can mix and match the storage +of columns within a logical table. + +Applications describe the format of their data by supplying a schema to +WT_SESSION::create. This specifies how the application's data can be split +into fields and mapped onto rows and columns. + +@section schema_types Column types + +By default, WiredTiger works as a traditional key/value store, where the +keys and values are raw byte arrays accessed using a WT_ITEM structure. +Keys and values may be up to (4GB - 512B) bytes in size, but depending +on how @ref WT_SESSION::create "maximum item sizes" are configured, +large key and value items will be stored on overflow pages. + +See @subpage keyvalue for more details on raw key / value items. + +The schema layer allows key and value types to be chosen from a list, +or composite keys or values made up of columns with any combination of +types. The size (4GB - 512B) byte limit on keys and values still +applies. + +WiredTiger's uses format strings similar to those specified in the Python +struct module to describe the types of columns in a table: + http://docs.python.org/library/struct + +@section schema_format_types Format types + +<table> +@hrow{Format, C Type, Java type, Python type, Standard size} +@row{x, pad byte, N/A, N/A, 1} +@row{b, signed char, byte, integer, 1} +@row{B, unsigned char, byte, integer, 1} +@row{h, short, short, integer, 2} +@row{H, unsigned short, short, integer, 2} +@row{i, int, int, integer, 4} +@row{I, unsigned int, int, integer, 4} +@row{l, long, int, integer, 4} +@row{L, unsigned long, int, integer, 4} +@row{q, long long, long, integer, 8} +@row{Q, unsigned long long, long, integer, 8} +@row{r, uint64_t, long, integer, 8} +@row{s, char[], String, string, fixed length} +@row{S, char[], String, string, variable} +@row{t, unsigned char, byte, integer, fixed bit length} +@row{u, WT_ITEM *, byte[], string, variable} +</table> + +The <code>'r'</code> type is used for record number keys in column stores. + +The <code>'S'</code> type is encoded as a C language string terminated by a +NUL character. + +The <code>'t'</code> type is used for fixed-length bit field values. If +it is preceded by a size, that indicates the number of bits to store, +between 1 and 8. That number of low-order bits will be stored in the +table. The default is a size of 1 bit: that is, a boolean. The +application must always use an <code>unsigned char</code> type (or +equivalently, <code>uint8_t</code>) for calls to WT_CURSOR::set_value, +and a pointer to the same for calls to WT_CURSOR::get_value. If a bit +field value is combined with other types in a packing format, it is +equivalent to <code>'B'</code>, and a full byte is used to store it. + +When referenced by a record number (that is, a key format of \c 'r'), +the <code>'t'</code> type will be stored in a fixed-length column-store, +and will not have a out-of-band value to indicate the record does not +exist. In this case, a 0 byte value is used to indicate the record does +not exist. This means removing a record with WT_CURSOR::remove is +equivalent to storing a value of 0 in the record with WT_CURSOR::update +(and storing a value of 0 in the record will cause cursor scans to +skip the record). Additionally, creating a record past the end of the +table or file implies the creation of any missing intermediate records, +with byte values of 0. + +The <code>'u'</code> type is for raw byte arrays: if it appears at the end +of a format string (including in the default <code>"u"</code> format for +untyped tables), the size is not stored explicitly. When <code>'u'</code> +appears within a format string, the size is stored as a 32-bit integer in +the same byte order as the rest of the format string, followed by the data. + +There is a default collator that gives lexicographic (byte-wise) +comparisons, and the default encoding is designed so that lexicographic +ordering of encoded keys is usually the expected ordering. For example, +the variable-length encoding of integers is designed so that they have the +natural integer ordering under the default collator. + +See @subpage packing for details of WiredTiger's packing format. + +WiredTiger can also be extended with @ref WT_COLLATOR. + +@section schema_data_access Columns in key and values + +Every table has a key format and a value format as describe in @ref +schema_types. These types are configured when the table is created by +passing \c key_format and \c value_format keys to WT_SESSION::create. + +Cursors for a table have the same key format as the table itself. The key +columns of a cursor are set with WT_CURSOR::set_key and accessed with +WT_CURSOR::get_key. WT_CURSOR::set_key is analogous to \c printf, and takes +a list of values in the order the key columns are configured in \c +key_format. The columns values are accessed with WT_CURSOR::get_key, which +is analogous to \c scanf, and takes a list of pointers to values in the same +order. + +Cursors for a table have the same value format as the table, unless a +projection is specified to WT_SESSION::open_cursor. WT_CURSOR::set_value is +used to set value columns, and WT_CURSOR::get_value is used to get value +columns. + +@section schema_columns Describing columns + +The columns in a table can be assigned names by passing a \c columns key to +WT_SESSION::create. The column names are assigned first to the columns in +the \c key_format, and then to the columns in \c value_format. There must be +a name for every column, and no column names may be repeated. + +@section schema_column_groups Storing groups of columns together + +Once column names are assigned, they can be used to configure column groups, +where groups of columns are stored in separate files. + +There are two steps involved in setting up column groups: first, pass a list +of names for the column groups in the \c colgroups configuration key to +WT_SESSION::create. Then make a call to WT_SESSION::create for each column +group, using the URI <code>colgroup:\<table\>:\<colgroup name\></code> and a +\c columns key in the configuration. Columns can be stored in multiple +column groups, but all value columns must appear in at least on column group. + +Column groups have the same key as the table. This is particularly useful +for column stores, because record numbers are not stored explicitly on disk, +so there is no repetition of keys across multiple files. Also note that key +columns cannot be stored in column group values: they can be retrieved with +WT_CURSOR::get_key. + +@section schema_indices Adding an index + +Schema columns can also be used to configure indices on tables. To create an +index, call WT_SESSION::create using the URI +<code>index:\<table\>:\<index name\></code> and include a \c columns key in +the configuration. WiredTiger updates all indices for a table whenever the +table is modified. + +A cursor can be opened on an index by passing the index URI to +WT_SESSION::open_cursor. Index cursors use the specified index key columns +for WT_CURSOR::get_key and WT_CURSOR::set_key, and by default return all of +the table value columns in WT_CURSOR::get_value. Index cursors are +read-only: they cannot be used to perform updates. + +@section schema_examples Code samples + +The code below is taken from the complete example program +@ex_ref{ex_schema.c}. + +@snippet ex_schema.c schema decl +@snippet ex_schema.c schema work + +The code below is taken from the complete example program +@ex_ref{ex_call_center.c}. + +@snippet ex_call_center.c call-center decl +@snippet ex_call_center.c call-center work + +@todo new section: schema_advanced Advanced Schemas +@todo non-relational data such as multiple index keys per row +@todo application-supplied extractors and collators need to be +registered before recovery can run. + */ diff --git a/src/docs/security.dox b/src/docs/security.dox new file mode 100644 index 00000000000..004a2661f54 --- /dev/null +++ b/src/docs/security.dox @@ -0,0 +1,24 @@ +/*! @page security WiredTiger security + +@section directory Database directory permissions + +The WiredTiger database directory should have its permissions set to +ensure database objects are not accessible to users without appropriate +permissions. See @ref home for more information. + +@section file File permissions + +WiredTiger creates file system objects readable and writable by the +process owner, group and user, as modified by the process' umask value. +The group ownership of created file system objects may vary depending +on the system, and is not controlled by WiredTiger. + +@section environment_variables Environment variables + +Consider security when configuring WiredTiger to use the WIREDTIGER_HOME +environment variable, especially in applications which run with +permissions other than the user's. Such applications are potentially +vulnerable to allowing users access to databases they could not +otherwise access. See @ref home for more information. + +*/ diff --git a/src/docs/signals.dox b/src/docs/signals.dox new file mode 100644 index 00000000000..1d05f0f2019 --- /dev/null +++ b/src/docs/signals.dox @@ -0,0 +1,11 @@ +/*! @page signals WiredTiger signal handling + +WiredTiger has no signal handlers and does not modify process signal handler behavior in any way. + +WiredTiger restarts any system calls interrupted by a signal. + +WiredTiger applications exiting as a result of a signal should exit WiredTiger gracefully, closing any open WiredTiger handles, before terminating the process. + +WiredTiger is not re-entrant, and applications using WiredTiger should not make WiredTiger API calls from signal handlers. + +*/ diff --git a/src/docs/snapshots.dox b/src/docs/snapshots.dox new file mode 100644 index 00000000000..5367b86375b --- /dev/null +++ b/src/docs/snapshots.dox @@ -0,0 +1,38 @@ +/*! @page snapshots Snapshots + +WiredTiger supports snapshots, a read-only, static view of a data source. + +Snapshots offer basic operation durability without transactional logging, +across application or system failure. (Transactional logging offers +fine-grained durability, but requires a recovery step when files are first +opened, and impacts the performance of every operation; snapshots offer +durability without recovery or impacting operational performance, but the +creation of a snapshot is a relatively heavy-weight operation. WiredTiger +does not currently support transactional logging.) + +Snapshots may optionally be named: WiredTiger creates and manages unnamed +snapshots automatically. Snapshots are created using the WT_SESSION::sync +method, read using the WT_SESSION::open_cursor method, and discarded using the +WT_SESSION::drop method. Additionally, the \c -s option to the \c wt command +line utility will list a data source's snapshots in a human-readable format. + +When WiredTiger data sources are first opened, they are opened in the state of +the most recent snapshot taken on the file, in other words, updates after the +most recent snapshot will not appear in the data source. If no snapshot is +found when the data source is opened, the data source will appear empty. + +Cursors are opened in the current working version of a data source unless a +snapshot name is provided to WT_SESSION::open_cursor. Cursors opened in the +current working version snapshot support write operations, snapshots opened in +a snapshot are read-only. + +Named snapshots persist until they are explicitly dropped. Snapshots share +pages, and deleting a snapshot may or may not make pages available for re-use, +depending on whether the dropped snapshot contained the last reference to a +block of data. Creating a named snapshot drops all previous snapshots with +the same name. Snapshots cannot be dropped if they are currently open +in a cursor. + +Unnamed snapshots managed by WiredTiger are given the name +"WiredTigerInternal". + */ diff --git a/src/docs/spell.ok b/src/docs/spell.ok new file mode 100644 index 00000000000..027c6623ecd --- /dev/null +++ b/src/docs/spell.ok @@ -0,0 +1,302 @@ +personal_ws-1.1 en 200 +APIs +Atomicity +BLOBs +CFLAGS +CPPFLAGS +DB's +DBTs +DbCursor +DbEnv +DbMultiple +EB +EmpId +FreeBSD +GCC +GitHub +IEC +LDFLAGS +LIBS +LSB +LSM +MERCHANTABILITY +MVCC's +Makefiles +Mewhort +NoSQL +RepMgr +Rrx +URIs +Vv +WiredTiger +WiredTiger's +WiredTigerInternal +aR +ack'ed +alloc +allocsize +ao +api +apiflags +ar +arg +autoconf +automake +bdb +bdbmap +bigram +bindir +bitstring +bool +boolean +br +btree +builtin +bzip +cachesize +callbk +cd +cdb +cds +checksum +checksums +ckp +colgroup +colgroups +command's +comparator +cond +config +conn +const +control's +cpp +crashless +cursortype +dN +dNLen +dNOff +dT +dataN +dataitem +datasets +dbc +dbm +dbt +decl +del +desc +destructor +destructors +dlp +dontlock +dp +dsync +dumpfile +dup +dups +endcode +endcond +endian +endinternal +english +env +eof +erlang +errno +failchk +fd's +fieldname +fileformats +fileid +filename +filesystem +fillfactor +firstname +fput +freelist +gcc +gdbm +getopt +getter +gid +github +hb +hotbackup +href +hrow +hsearch +html +huffman +indices +init +intl +inuse +io +ip +je +jemalloc +jni +json +keyexist +keyfmt +keyname +keyvalue +lastname +len +li +libdir +libtool +libwiredtiger +lmin +loadtext +logc +lookup +lrtf +lsn +lt +mailto +mainpage +malloc +malloc'd +marshalled +marshalling +maxintlitem +maxintlpage +maxleafitem +maxleafpage +memalloc +memfree +memp +metadata +minkey +mmap +mpool +mpoolfile +msg +msgs +multi +multiprocess +multithreading +multiversion +mutex +mutexes +mutexing +mvcc +mygcc +ndary +ndbm +newsite +nocase +nocasecoll +nodup +noflush +nolocking +nommap +nop +nosql +nosync +notgranted +notyet +nowait +nul +num +objectsin +ol +oltp +oob +ovfl +pcoll +pdf +pget +php +png +posix +pre +primary's +printf +printlog +printvalue +priv +pthread +pthreads +qnx +rdbms +rdlock +readlock +readonly +realclean +realloc +realloc'd +recno +recnoN +recnum +reconf +recs +rerequests +ret +ro +rpc +rwlock +rx +sHQ +scalable +scanf +schemas +selectable +seqname +serializable +spinlock +spinlocks +sql +src +startsync +strerror +struct +structs +subdatabases +subpage +superset +sv +tablename +tcl +tcmalloc +td +th +thang +timestamp +timestamps +todo +toolchain +tpc +tpcb +transactional +transactionally +tt +txn +txns +typedef +uint +ul +umask +unallocated +unencoded +unescaped +untyped +uri +useconds +usr +utf +util +valign +valuefmt +vec +versa +whitespace +wiredtiger +workQ +writelock +writelocks +wrlock +xa +yieldcpu diff --git a/src/docs/sql-map.dox b/src/docs/sql-map.dox new file mode 100644 index 00000000000..8f288565436 --- /dev/null +++ b/src/docs/sql-map.dox @@ -0,0 +1,32 @@ +/*! \page sql_mapping Mapping SQL onto the WiredTiger API + +@todo decide whether to keep this page, if so, fill it out + +An RDBMS has the SQL language, a parser and a query planner. All of them +sit on top of WiredTiger, as they would on top of any key-value store. + +The difference with WiredTiger's API is that the query plan is going to be +based on fundamental operations including: + +# sequential scan through a range; +# join (various flavors); +# sort (group by); +# projection, and so on. + +Those operations would be implemented as different WiredTiger cursor types, +using WT_CONNECTION::add_cursor_type. + +The cursor types could be implemented as one or more extensions, loaded +automatically whenever the database is opened for the first time. Then the +cursor types would always be there, and the query planner just asks for a +cursor that combines together data from various other cursors and comes out as +a set of key/data pairs it can deal with. + +With the right set of special cursor types are implemented, one cursor could +return the SQL result set. That is, combining cursors would implement a +query plan. And that could happen over a socket, mixing local processing +with server-side processing. + +This same interface could deal with many types of compression, transforming +data on the fly in various ways (like views), and so on. + */ diff --git a/src/docs/style/DoxygenLayout.xml b/src/docs/style/DoxygenLayout.xml new file mode 100644 index 00000000000..3c186e36f89 --- /dev/null +++ b/src/docs/style/DoxygenLayout.xml @@ -0,0 +1,190 @@ +<doxygenlayout version="1.0"> + <!-- Navigation index tabs for HTML output --> + <navindex> + <tab type="mainpage" visible="yes" title=""/> + <tab type="pages" visible="yes" title="" intro=""/> + <tab type="modules" visible="yes" title="" intro=""/> + <tab type="namespaces" visible="yes" title=""> + <tab type="namespacelist" visible="yes" title="" intro=""/> + <tab type="namespacemembers" visible="yes" title="" intro=""/> + </tab> + <tab type="classes" visible="no" title=""> + <tab type="classlist" visible="yes" title="" intro=""/> + <tab type="classindex" visible="$ALPHABETICAL_INDEX" title=""/> + <tab type="hierarchy" visible="yes" title="" intro=""/> + <tab type="classmembers" visible="yes" title="" intro=""/> + </tab> + <tab type="files" visible="yes" title=""> + <tab type="filelist" visible="yes" title="" intro=""/> + <tab type="globals" visible="yes" title="" intro=""/> + </tab> + <tab type="dirs" visible="yes" title="" intro=""/> + <tab type="examples" visible="yes" title="" intro=""/> + <tab type="user" url="license.html" visible="yes" title="License"/> + <tab type="user" url="https://github.com/wiredtiger/wiredtiger/downloads/" visible="yes" title="Download"/> + </navindex> + + <!-- Layout definition for a class page --> + <class> + <briefdescription visible="yes"/> + <includes visible="$SHOW_INCLUDE_FILES"/> + <inheritancegraph visible="$CLASS_GRAPH"/> + <collaborationgraph visible="$COLLABORATION_GRAPH"/> + <allmemberslink visible="yes"/> + <memberdecl> + <nestedclasses visible="yes" title=""/> + <publictypes title=""/> + <publicslots title=""/> + <signals title=""/> + <publicmethods title=""/> + <publicstaticmethods title=""/> + <publicattributes title=""/> + <publicstaticattributes title=""/> + <protectedtypes title=""/> + <protectedslots title=""/> + <protectedmethods title=""/> + <protectedstaticmethods title=""/> + <protectedattributes title=""/> + <protectedstaticattributes title=""/> + <packagetypes title=""/> + <packagemethods title=""/> + <packagestaticmethods title=""/> + <packageattributes title=""/> + <packagestaticattributes title=""/> + <properties title=""/> + <events title=""/> + <privatetypes title=""/> + <privateslots title=""/> + <privatemethods title=""/> + <privatestaticmethods title=""/> + <privateattributes title=""/> + <privatestaticattributes title=""/> + <friends title=""/> + <related title="" subtitle=""/> + <membergroups visible="yes"/> + </memberdecl> + <detaileddescription title=""/> + <memberdef> + <inlineclasses title=""/> + <typedefs title=""/> + <enums title=""/> + <constructors title=""/> + <functions title=""/> + <related title=""/> + <variables title=""/> + <properties title=""/> + <events title=""/> + </memberdef> + <usedfiles visible="$SHOW_USED_FILES"/> + <authorsection visible="yes"/> + </class> + + <!-- Layout definition for a namespace page --> + <namespace> + <briefdescription visible="yes"/> + <memberdecl> + <nestednamespaces visible="yes" title=""/> + <classes visible="yes" title=""/> + <typedefs title=""/> + <enums title=""/> + <functions title=""/> + <variables title=""/> + <membergroups visible="yes"/> + </memberdecl> + <detaileddescription title=""/> + <memberdef> + <inlineclasses title=""/> + <typedefs title=""/> + <enums title=""/> + <functions title=""/> + <variables title=""/> + </memberdef> + <authorsection visible="yes"/> + </namespace> + + <!-- Layout definition for a file page --> + <file> + <briefdescription visible="yes"/> + <includes visible="$SHOW_INCLUDE_FILES"/> + <includegraph visible="$INCLUDE_GRAPH"/> + <includedbygraph visible="$INCLUDED_BY_GRAPH"/> + <sourcelink visible="yes"/> + <memberdecl> + <classes visible="yes" title=""/> + <namespaces visible="yes" title=""/> + <defines title=""/> + <typedefs title=""/> + <enums title=""/> + <functions title=""/> + <variables title=""/> + <membergroups visible="yes"/> + </memberdecl> + <detaileddescription title=""/> + <memberdef> + <inlineclasses title=""/> + <defines title=""/> + <typedefs title=""/> + <enums title=""/> + <functions title=""/> + <variables title=""/> + </memberdef> + <authorsection/> + </file> + + <!-- Layout definition for a group page --> + <group> + <briefdescription visible="yes"/> + <groupgraph visible="$GROUP_GRAPHS"/> + <memberdecl> + <classes visible="yes" title=""/> + <namespaces visible="yes" title=""/> + <dirs visible="yes" title=""/> + <nestedgroups visible="yes" title=""/> + <files visible="yes" title=""/> + <defines title=""/> + <typedefs title=""/> + <enums title=""/> + <enumvalues title=""/> + <functions title=""/> + <variables title=""/> + <signals title=""/> + <publicslots title=""/> + <protectedslots title=""/> + <privateslots title=""/> + <events title=""/> + <properties title=""/> + <friends title=""/> + <membergroups visible="yes"/> + </memberdecl> + <detaileddescription title=""/> + <memberdef> + <pagedocs/> + <inlineclasses title=""/> + <defines title=""/> + <typedefs title=""/> + <enums title=""/> + <enumvalues title=""/> + <functions title=""/> + <variables title=""/> + <signals title=""/> + <publicslots title=""/> + <protectedslots title=""/> + <privateslots title=""/> + <events title=""/> + <properties title=""/> + <friends title=""/> + </memberdef> + <authorsection visible="yes"/> + </group> + + <!-- Layout definition for a directory page --> + <directory> + <briefdescription visible="yes"/> + <directorygraph visible="yes"/> + <memberdecl> + <dirs visible="yes"/> + <files visible="yes"/> + </memberdecl> + <detaileddescription title=""/> + </directory> +</doxygenlayout> diff --git a/src/docs/style/background_navigation.png b/src/docs/style/background_navigation.png Binary files differnew file mode 100644 index 00000000000..d59e96ddef6 --- /dev/null +++ b/src/docs/style/background_navigation.png diff --git a/src/docs/style/doxygen.png b/src/docs/style/doxygen.png Binary files differnew file mode 100644 index 00000000000..f0a274bbaff --- /dev/null +++ b/src/docs/style/doxygen.png diff --git a/src/docs/style/footer.html b/src/docs/style/footer.html new file mode 100644 index 00000000000..cf0bb962e6f --- /dev/null +++ b/src/docs/style/footer.html @@ -0,0 +1,11 @@ +<!--BEGIN GENERATE_TREEVIEW--> + <li class="footer">Copyright (c) 2008-2012 WiredTiger, Inc. All rights reserved. Contact <a href="mailto:info@wiredtiger.com">info@wiredtiger.com</a> for more information.</li> + </ul> + </div> +<!--END GENERATE_TREEVIEW--> +<!--BEGIN !GENERATE_TREEVIEW--> +<hr class="footer"/><address class="footer"><small> +Copyright (c) 2008-2012 WiredTiger. All rights reserved. Contact <a href="mailto:info@wiredtiger.com">info@wiredtiger.com</a> for more information.</small></address> +<!--END !GENERATE_TREEVIEW--> +</body> +</html> diff --git a/src/docs/style/header.html b/src/docs/style/header.html new file mode 100644 index 00000000000..39b1d1b9372 --- /dev/null +++ b/src/docs/style/header.html @@ -0,0 +1,54 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml"> +<head> +<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/> +<meta http-equiv="X-UA-Compatible" content="IE=9"/> +<!--BEGIN PROJECT_NAME--><title>$projectname: $title</title><!--END PROJECT_NAME--> +<!--BEGIN !PROJECT_NAME--><title>$title</title><!--END !PROJECT_NAME--> +<link href="$relpath$tabs.css" rel="stylesheet" type="text/css"/> +<link href="$relpath$wiredtiger.css" rel="stylesheet" type="text/css" /> +$treeview +$search +$mathjax +</head> +<body> +<div id="top"><!-- do not remove this div! --> +<!--BEGIN TITLEAREA--> +<div id="titlearea"> +<table cellspacing="0" cellpadding="0"> + <tbody> + <tr style="height: 56px;"> + <!--BEGIN PROJECT_LOGO--> + <td id="projectlogo"> + <div class="logo"><a href="http://wiredtiger.com/"><img src="$relpath$LogoFinal-header.png" alt="WiredTiger" /></a></div> + </td> + <!--END PROJECT_LOGO--> + <!--BEGIN PROJECT_NAME--> + <td style="padding-left: 0.5em;"> + <div id="projectname"> + <!--BEGIN PROJECT_NUMBER--> <span id="projectnumber">$projectnumber</span><!--END PROJECT_NUMBER--> + </div> + <!--BEGIN PROJECT_BRIEF--><div id="projectbrief">$projectbrief</div><!--END PROJECT_BRIEF--> + </td> + <!--END PROJECT_NAME--> + <!--BEGIN !PROJECT_NAME--> + <!--BEGIN PROJECT_BRIEF--> + <td style="padding-left: 0.5em;"> + <div id="projectbrief">$projectbrief</div> + </td> + <!--END PROJECT_BRIEF--> + <!--END !PROJECT_NAME--> + <!--BEGIN DISABLE_INDEX--> + <!--BEGIN SEARCHENGINE--> + <td>$searchbox</td> + <!--END SEARCHENGINE--> + <!--END DISABLE_INDEX--> + </tr> + </tbody> +</table> +</div> +<div class="banner"> + <a href="https://github.com/wiredtiger/wiredtiger">Fork me on GitHub</a> + <a class="last" href="http://groups.google.com/group/wiredtiger-users">Join my user group</a> +</div> +<!--END TITLEAREA--> diff --git a/src/docs/style/img_downArrow.png b/src/docs/style/img_downArrow.png Binary files differnew file mode 100644 index 00000000000..024a03c2654 --- /dev/null +++ b/src/docs/style/img_downArrow.png diff --git a/src/docs/style/javadoc.css b/src/docs/style/javadoc.css new file mode 100644 index 00000000000..f345b05b158 --- /dev/null +++ b/src/docs/style/javadoc.css @@ -0,0 +1,35 @@ +/* Javadoc style sheet */ + +/* Define colors, fonts and other style attributes here to override the defaults */ + +/* Page background color */ +body { background-color: #FFFFFF } + +/* Table colors */ +.TableHeadingColor { background: #CCCCFF } /* Dark mauve */ +.TableSubHeadingColor { background: #EEEEFF } /* Light mauve */ +.TableRowColor { background: #FFFFFF } /* White */ + +/* Font used in left-hand frame lists */ +.FrameTitleFont { font-size: 10pts; font-family: Helvetica, Arial, san-serif } +.FrameHeadingFont { font-size: 10pts; font-family: Helvetica, Arial, san-serif } +.FrameItemFont { font-size: 10pts; font-family: Helvetica, Arial, san-serif } + +/* Example of smaller, sans-serif font in frames */ +/* .FrameItemFont { font-size: 10pt; font-family: Helvetica, Arial, sans-serif } */ + +/* Navigation bar fonts and colors */ +.NavBarCell1 { background-color:#EEEEFF;} /* Red */ +.NavBarCell1Rev { background-color:#00008B;} /* Light red */ +.NavBarFont1 { font-family: Arial, Helvetica, sans-serif; color:#000000;} +.NavBarFont1Rev { font-family: Arial, Helvetica, sans-serif; color:#FFFFFF;} + +.NavBarCell2 { font-family: Arial, Helvetica, sans-serif; background-color:#FFFFFF;} +.NavBarCell3 { font-family: Arial, Helvetica, sans-serif; background-color:#FFFFFF;} + +pre.code +{ + border: solid thin; + padding: 2px; + background-color: #ffffcc; +} diff --git a/src/docs/style/tabs.css b/src/docs/style/tabs.css new file mode 100644 index 00000000000..c543eb00429 --- /dev/null +++ b/src/docs/style/tabs.css @@ -0,0 +1,128 @@ +/* tabs styles, based on http://www.alistapart.com/articles/slidingdoors */ + +div.navigation { + display:block; + float:left; + clear:both; + width:100%; + padding-top:10px; + padding-bottom:30px; + border-bottom:1px dotted #E0E0E0; + height: 60px; + background:url(background_navigation.png); +} + +div.contents { + float:left; + clear:both; + +} + +address { + display:none; +} + +DIV.tabs +{ + float : left; + width : 100%; + margin-bottom : 4px; +} + +DIV.tabs UL +{ + margin : 0px; + padding-left : 0px; + list-style : none; +} + +DIV.tabs LI, DIV.tabs FORM +{ + display : inline; + margin : 0px; + padding : 0px; + background-color:#FFFFFF; +} + +DIV.tabs FORM +{ + float : right; +} + +DIV.tabs A +{ + float : left; + font-size : 80%; + font-weight : bold; + text-decoration : none; +} + +DIV.tabs A:hover +{ + background-position: 100% -150px; +} + +DIV.tabs A:link, DIV.tabs A:visited, +DIV.tabs A:active, DIV.tabs A:hover +{ + color: #1A419D; +} + +DIV.tabs SPAN +{ + float : left; + display : block; + padding : 5px 9px; + white-space : nowrap; + border-top:1px dotted #E0E0E0; + border-bottom:1px dotted #E0E0E0; +} + +DIV.tabs #MSearchBox +{ + float : right; + display : inline; + font-size : 1em; +} + +DIV.tabs TD +{ + font-size : 80%; + font-weight : bold; + text-decoration : none; +} + + + +/* Commented Backslash Hack hides rule from IE5-Mac \*/ +DIV.tabs SPAN {float : none;} +/* End IE5-Mac hack */ + +DIV.tabs A:hover SPAN +{ + background-position: 0% -150px; +} + +DIV.tabs LI.current A +{ + background-position: 100% -150px; + border-width : 0px; + background-color: #F0F0F0; + background: #F0F0F0 url(img_downArrow.png) center bottom no-repeat; +} + +DIV.tabs LI.current SPAN +{ + background-position: 0% -150px; + padding-bottom : 6px; +} + +DIV.navpath +{ + background : none; + border : none; + border-bottom : 1px solid #84B0C7; + text-align : center; + margin : 2px; + padding : 2px; +} diff --git a/src/docs/style/wiredtiger.css b/src/docs/style/wiredtiger.css new file mode 100644 index 00000000000..f3d3dcc6bee --- /dev/null +++ b/src/docs/style/wiredtiger.css @@ -0,0 +1,976 @@ +/* The standard CSS for doxygen */ + +body, table, div, p, dl { + font-family: "Helvetica Neue", Helvetica, Arial, sans-serif; + color: #373737; + font-size: 13px; + line-height: 1.3; +} + +.banner { + position: absolute; top: -2px; right: 1em; + overflow: hidden; + background-color: #e57504; + background-image: -webkit-linear-gradient(top, #dc7202, #ee7906); + background-image: -moz-linear-gradient(top, #dc7202, #ee7906); + background-image: -ms-linear-gradient(top, #dc7202, #ee7906); + border-radius: 0 0 8px 8px; + -moz-border-radius: 0 0 8px 8px; + box-shadow: 0 0 1em #888; +} + +.banner a { + border: 1px solid #ebaa65; + color: #fff; + display: block; + font: bold 9pt sans-serif; + margin: 0.05em 0 0.05em 0; + padding: 0.5em 2em; + text-align: center; + text-decoration: none; + text-shadow: 0 0 0.5em #444; +} + +.banner a.last { + border: none; +} + +/* @group Heading Levels */ + +h1 { + font-size: 150%; +} + +.title { + font-size: 150%; + font-weight: bold; + margin: 10px 2px; +} + +h2 { + font-size: 120%; +} + +h3 { + font-size: 100%; +} + +dt { + font-weight: bold; +} + +div.multicol { + -moz-column-gap: 1em; + -webkit-column-gap: 1em; + -moz-column-count: 3; + -webkit-column-count: 3; +} + +p.startli, p.startdd, p.starttd { + margin-top: 2px; +} + +p.endli { + margin-bottom: 0px; +} + +p.enddd { + margin-bottom: 4px; +} + +p.endtd { + margin-bottom: 2px; +} + +/* @end */ + +caption { + font-weight: bold; +} + +span.legend { + font-size: 70%; + text-align: center; +} + +h3.version { + font-size: 90%; + text-align: center; +} + +div.qindex, div.navtab{ + background-color: #EBEFF6; + border: 1px solid #A3B4D7; + text-align: center; +} + +div.qindex, div.navpath { + width: 100%; + line-height: 140%; +} + +div.navtab { + margin-right: 15px; +} + +/* @group Link Styling */ + +a { + color: #3D578C; + font-weight: normal; + text-decoration: none; +} + +.contents a:visited { + color: #4665A2; +} + +a:hover { + text-decoration: underline; +} + +a.qindex { + font-weight: bold; +} + +a.qindexHL { + font-weight: bold; + background-color: #9CAFD4; + color: #ffffff; + border: 1px double #869DCA; +} + +.contents a.qindexHL:visited { + color: #ffffff; +} + +a.el { + font-weight: bold; +} + +a.elRef { +} + +a.code { + color: #4665A2; +} + +a.codeRef { + color: #4665A2; +} + +/* @end */ + +dl.el { + margin-left: -1cm; +} + +.fragment { + font-family: monospace, fixed; + font-size: 105%; +} + +pre.fragment { + border: 1px solid #C4CFE5; + background-color: #FBFCFD; + padding: 4px 6px; + margin: 4px 8px 4px 2px; + overflow: auto; + word-wrap: break-word; + font-size: 9pt; + line-height: 125%; +} + +div.ah { + background-color: black; + font-weight: bold; + color: #ffffff; + margin-bottom: 3px; + margin-top: 3px; + padding: 0.2em; + border: solid thin #333; + border-radius: 0.5em; + -webkit-border-radius: .5em; + -moz-border-radius: .5em; + box-shadow: 2px 2px 3px #999; + -webkit-box-shadow: 2px 2px 3px #999; + -moz-box-shadow: rgba(0, 0, 0, 0.15) 2px 2px 2px; + background-image: -webkit-gradient(linear, left top, left bottom, from(#eee), to(#000),color-stop(0.3, #444)); + background-image: -moz-linear-gradient(center top, #eee 0%, #444 40%, #000); +} + +div.groupHeader { + margin-left: 16px; + margin-top: 12px; + font-weight: bold; +} + +div.groupText { + margin-left: 16px; + font-style: italic; +} + +body { + background-color: white; + color: black; + margin: 0; +} + +div.contents { + margin-top: 10px; + margin-left: 8px; + margin-right: 8px; +} + +td.indexkey { + background-color: #EBEFF6; + font-weight: bold; + border: 1px solid #C4CFE5; + margin: 2px 0px 2px 0; + padding: 2px 10px; +} + +td.indexvalue { + background-color: #EBEFF6; + border: 1px solid #C4CFE5; + padding: 2px 10px; + margin: 2px 0px; +} + +tr.memlist { + background-color: #EEF1F7; +} + +p.formulaDsp { + text-align: center; +} + +img.formulaDsp { + +} + +img.formulaInl { + vertical-align: middle; +} + +div.center { + text-align: center; + margin-top: 0px; + margin-bottom: 0px; + padding: 0px; +} + +div.center img { + border: 0px; +} + +address.footer { + text-align: right; + padding-right: 12px; +} + +img.footer { + border: 0px; + vertical-align: middle; +} + +/* @group Code Colorization */ + +span.keyword { + color: #008000 +} + +span.keywordtype { + color: #604020 +} + +span.keywordflow { + color: #e08000 +} + +span.comment { + color: #800000 +} + +span.preprocessor { + color: #806020 +} + +span.stringliteral { + color: #002080 +} + +span.charliteral { + color: #008080 +} + +span.vhdldigit { + color: #ff00ff +} + +span.vhdlchar { + color: #000000 +} + +span.vhdlkeyword { + color: #700070 +} + +span.vhdllogic { + color: #ff0000 +} + +/* @end */ + +/* +.search { + color: #003399; + font-weight: bold; +} + +form.search { + margin-bottom: 0px; + margin-top: 0px; +} + +input.search { + font-size: 75%; + color: #000080; + font-weight: normal; + background-color: #e8eef2; +} +*/ + +td.tiny { + font-size: 75%; +} + +.dirtab { + padding: 4px; + border-collapse: collapse; + border: 1px solid #A3B4D7; +} + +th.dirtab { + background: #EBEFF6; + font-weight: bold; +} + +hr { + height: 0px; + border: none; + border-top: 1px solid #4A6AAA; +} + +hr.footer { + height: 1px; +} + +/* @group Member Descriptions */ + +table.memberdecls { + border-spacing: 0px; + padding: 0px; +} + +.mdescLeft, .mdescRight, +.memItemLeft, .memItemRight, +.memTemplItemLeft, .memTemplItemRight, .memTemplParams { + background-color: #F9FAFC; + border: none; + margin: 4px; + padding: 1px 0 0 8px; +} + +.mdescLeft, .mdescRight { + padding: 0px 8px 4px 8px; + color: #555; +} + +.memItemLeft, .memItemRight, .memTemplParams { + border-top: 1px solid #C4CFE5; +} + +.memItemLeft, .memTemplItemLeft { + white-space: nowrap; +} + +.memItemRight { + width: 100%; +} + +.memTemplParams { + color: #4665A2; + white-space: nowrap; +} + +/* @end */ + +/* @group Member Details */ + +/* Styles for detailed member documentation */ + +.memtemplate { + font-size: 80%; + color: #4665A2; + font-weight: normal; + margin-left: 9px; +} + +.memnav { + background-color: #EBEFF6; + border: 1px solid #A3B4D7; + text-align: center; + margin: 2px; + margin-right: 15px; + padding: 2px; +} + +.mempage { + width: 100%; +} + +.memitem { + padding: 0; + margin-bottom: 10px; + margin-right: 5px; +} + +.memname { + white-space: nowrap; + font-weight: bold; + margin-left: 6px; +} + +.memproto, dl.reflist dt { + border-top: 1px solid #A8B8D9; + border-left: 1px solid #A8B8D9; + border-right: 1px solid #A8B8D9; + padding: 6px 0px 6px 0px; + color: #253555; + font-weight: bold; + text-shadow: 0px 1px 1px rgba(255, 255, 255, 0.9); + /* opera specific markup */ + box-shadow: 5px 5px 5px rgba(0, 0, 0, 0.15); + border-top-right-radius: 8px; + border-top-left-radius: 8px; + /* firefox specific markup */ + -moz-box-shadow: rgba(0, 0, 0, 0.15) 5px 5px 5px; + -moz-border-radius-topright: 8px; + -moz-border-radius-topleft: 8px; + /* webkit specific markup */ + -webkit-box-shadow: 5px 5px 5px rgba(0, 0, 0, 0.15); + -webkit-border-top-right-radius: 8px; + -webkit-border-top-left-radius: 8px; + background-image:url('nav_f.png'); + background-repeat:repeat-x; + background-color: #EEE7DD; + +} + +.memdoc, dl.reflist dd { + border-bottom: 1px solid #A8B8D9; + border-left: 1px solid #A8B8D9; + border-right: 1px solid #A8B8D9; + padding: 2px 5px; + background-color: #FBFCFD; + border-top-width: 0; + /* opera specific markup */ + border-bottom-left-radius: 8px; + border-bottom-right-radius: 8px; + box-shadow: 5px 5px 5px rgba(0, 0, 0, 0.15); + /* firefox specific markup */ + -moz-border-radius-bottomleft: 8px; + -moz-border-radius-bottomright: 8px; + -moz-box-shadow: rgba(0, 0, 0, 0.15) 5px 5px 5px; +/* background-image: -moz-linear-gradient(center top, #FFFFFF 0%, #FFFFFF 60%, #FBF9F7 95%, #F7F3EE); */ + /* webkit specific markup */ + -webkit-border-bottom-left-radius: 8px; + -webkit-border-bottom-right-radius: 8px; + -webkit-box-shadow: 5px 5px 5px rgba(0, 0, 0, 0.15); +/* background-image: -webkit-gradient(linear,center top,center bottom,from(#FFFFFF), color-stop(0.6,#FFFFFF), color-stop(0.60,#FFFFFF), color-stop(0.95,#FBF9F7), to(#F7F3EE)); */ +} + +dl.reflist dt { + padding: 5px; +} + +dl.reflist dd { + margin: 0px 0px 10px 0px; + padding: 5px; +} + +.paramkey { + text-align: right; +} + +.paramtype { + white-space: nowrap; +} + +.paramname { + color: #602020; + white-space: nowrap; +} +.paramname em { + font-style: normal; +} + +.params, .retval, .exception, .tparams { + border-spacing: 6px 2px; +} + +.params .paramname, .retval .paramname { + font-weight: bold; + vertical-align: top; +} + +.params .paramtype { + font-style: italic; + vertical-align: top; +} + +.params .paramdir { + font-family: "courier new",courier,monospace; + vertical-align: top; +} + + + + +/* @end */ + +/* @group Directory (tree) */ + +/* for the tree view */ + +.ftvtree { + font-family: sans-serif; + margin: 0px; +} + +/* these are for tree view when used as main index */ + +.directory { + font-size: 9pt; + font-weight: bold; + margin: 5px; +} + +.directory h3 { + margin: 0px; + margin-top: 1em; + font-size: 11pt; +} + +/* +The following two styles can be used to replace the root node title +with an image of your choice. Simply uncomment the next two styles, +specify the name of your image and be sure to set 'height' to the +proper pixel height of your image. +*/ + +/* +.directory h3.swap { + height: 61px; + background-repeat: no-repeat; + background-image: url("yourimage.gif"); +} +.directory h3.swap span { + display: none; +} +*/ + +.directory > h3 { + margin-top: 0; +} + +.directory p { + margin: 0px; + white-space: nowrap; +} + +.directory div { + display: none; + margin: 0px; +} + +.directory img { + vertical-align: -30%; +} + +/* these are for tree view when not used as main index */ + +.directory-alt { + font-size: 100%; + font-weight: bold; +} + +.directory-alt h3 { + margin: 0px; + margin-top: 1em; + font-size: 11pt; +} + +.directory-alt > h3 { + margin-top: 0; +} + +.directory-alt p { + margin: 0px; + white-space: nowrap; +} + +.directory-alt div { + display: none; + margin: 0px; +} + +.directory-alt img { + vertical-align: -30%; +} + +/* @end */ + +div.dynheader { + margin-top: 8px; +} + +address { + font-style: normal; + color: #61482A; +} + +table.doxtable { + border-collapse:collapse; +} + +table.doxtable td, table.doxtable th { + border: 1px solid #684C2D; + padding: 3px 7px 2px; +} + +table.doxtable th { + background-color: #7F5E37; + color: #FFFFFF; + font-size: 110%; + padding-bottom: 4px; + padding-top: 5px; + text-align:left; +} + +table.fieldtable { + width: 100%; + margin-bottom: 10px; + border: 1px solid #D9C2A8; + border-spacing: 0px; + -moz-border-radius: 4px; + -webkit-border-radius: 4px; + border-radius: 4px; + -moz-box-shadow: rgba(0, 0, 0, 0.15) 2px 2px 2px; + -webkit-box-shadow: 2px 2px 2px rgba(0, 0, 0, 0.15); + box-shadow: 2px 2px 2px rgba(0, 0, 0, 0.15); +} + +.fieldtable td, .fieldtable th { + padding: 3px 7px 2px; +} + +.fieldtable td.fieldtype, .fieldtable td.fieldname { + white-space: nowrap; + border-right: 1px solid #D9C2A8; + border-bottom: 1px solid #D9C2A8; + vertical-align: top; +} + +.fieldtable td.fielddoc { + border-bottom: 1px solid #D9C2A8; + width: 100%; +} + +.fieldtable tr:last-child td { + border-bottom: none; +} + +.fieldtable th { + background-image:url('nav_f.png'); + background-repeat:repeat-x; + background-color: #F2EBE2; + font-size: 90%; + color: #553E25; + padding-bottom: 4px; + padding-top: 5px; + text-align:left; + -moz-border-radius-topleft: 4px; + -moz-border-radius-topright: 4px; + -webkit-border-top-left-radius: 4px; + -webkit-border-top-right-radius: 4px; + border-top-left-radius: 4px; + border-top-right-radius: 4px; + border-bottom: 1px solid #D9C2A8; +} + + +.tabsearch { + top: 0px; + left: 10px; + height: 36px; + background-image: url('tab_b.png'); + z-index: 101; + overflow: hidden; + font-size: 13px; +} + +.navpath ul +{ + font-size: 11px; + background-image:url('tab_b.png'); + background-repeat:repeat-x; + height:30px; + line-height:30px; + color:#CCAD8A; + border:solid 1px #E4D4C2; + overflow:hidden; + margin:0px; + padding:0px; +} + +.navpath li +{ + list-style-type:none; + float:left; + padding-left:10px; + padding-right:15px; + background-image:url('bc_s.png'); + background-repeat:no-repeat; + background-position:right; + color:#7C5B36; +} + +.navpath li.navelem a +{ + height:32px; + display:block; + text-decoration: none; + outline: none; +} + +.navpath li.navelem a:hover +{ + color:#BD9568; +} + +.navpath li.footer +{ + list-style-type:none; + float:right; + padding-left:10px; + padding-right:15px; + background-image:none; + background-repeat:no-repeat; + background-position:right; + color:#7C5B36; + font-size: 8pt; +} + + +div.summary +{ + float: right; + font-size: 8pt; + padding-right: 5px; + width: 50%; + text-align: right; +} + +div.summary a +{ + white-space: nowrap; +} + +div.ingroups +{ + margin-left: 5px; + font-size: 8pt; + padding-left: 5px; + width: 50%; + text-align: left; +} + +div.ingroups a +{ + white-space: nowrap; +} + +div.header +{ + background-image:url('nav_h.png'); + background-repeat:repeat-x; + background-color: #FCFBF9; + margin: 0px; + border-bottom: 1px solid #E5D6C4; +} + +div.headertitle, div.logo +{ + padding: 5px 5px 5px 10px; +} + +dl +{ + padding: 0 0 0 10px; +} + +dl.note, dl.warning, dl.attention, dl.pre, dl.post, dl.invariant, dl.deprecated, dl.todo, dl.test, dl.bug +{ + border-left:4px solid; + padding: 0 0 0 6px; +} + +dl.note +{ + border-color: #D0D000; +} + +dl.warning, dl.attention +{ + border-color: #FF0000; +} + +dl.pre, dl.post, dl.invariant +{ + border-color: #00D000; +} + +dl.deprecated +{ + border-color: #505050; +} + +dl.todo +{ + border-color: #00C0E0; +} + +dl.test +{ + border-color: #3030E0; +} + +dl.bug +{ + border-color: #5373B4; +} + +#projectlogo +{ + text-align: center; + vertical-align: bottom; + border-collapse: separate; +} + +#projectlogo img +{ + border: 0px none; +} + +#projectname +{ + font: 300% Tahoma, Arial,sans-serif; + margin: 0px; + padding: 2px 0px; +} + +#projectbrief +{ + font: 120% Tahoma, Arial,sans-serif; + margin: 0px; + padding: 0px; +} + +#projectnumber +{ + font: 50% Tahoma, Arial,sans-serif; + margin: 0px; + padding: 0px; +} + +#titlearea +{ + padding: 0px; + margin: 0px; + width: 100%; + border-bottom: 1px solid #B48753; +} + +.image +{ + text-align: center; +} + +.dotgraph +{ + text-align: center; +} + +.mscgraph +{ + text-align: center; +} + +.caption +{ + font-weight: bold; +} + +div.zoom +{ + border: 1px solid #CEB190; +} + +dl.citelist { + margin-bottom:50px; +} + +dl.citelist dt { + color:#755633; + float:left; + font-weight:bold; + margin-right:10px; + padding:5px; +} + +dl.citelist dd { + margin:2px 0; + padding:5px 0; +} + +@media print +{ + #top { display: none; } + #side-nav { display: none; } + #nav-path { display: none; } + body { overflow:visible; } + h1, h2, h3, h4, h5, h6 { page-break-after: avoid; } + .summary { display: none; } + .memitem { page-break-inside: avoid; } + #doc-content + { + margin-left:0 !important; + height:auto !important; + width:auto !important; + overflow:inherit; + display:inline; + } + pre.fragment + { + overflow: visible; + text-wrap: unrestricted; + white-space: -moz-pre-wrap; /* Moz */ + white-space: -pre-wrap; /* Opera 4-6 */ + white-space: -o-pre-wrap; /* Opera 7 */ + white-space: pre-wrap; /* CSS3 */ + word-wrap: break-word; /* IE 5.5+ */ + } +} + diff --git a/src/docs/threads.dox b/src/docs/threads.dox new file mode 100644 index 00000000000..eb830de6b01 --- /dev/null +++ b/src/docs/threads.dox @@ -0,0 +1,36 @@ +/*! @page threads Multithreading + +All WT_CONNECTION methods are thread safe, and WT_CONNECTION handles can +be shared between threads. Applications typically open a single +connection to each database, per process. + +WT_SESSION and WT_CURSOR methods are not thread safe and WT_SESSION and +WT_CURSOR handles cannot be accessed concurrently by multiple threads. +Applications typically open one WT_SESSION handle for each thread +accessing a database, and then one or more WT_CURSOR handles within the +session. + +WT_SESSION and WT_CURSOR methods may be accessed by different threads +serially (for example, a pool of threads managed by the application with +a set of shared session or cursor handles). There is no thread-local +state in WiredTiger, but no built-in synchronization of session or +cursor handles, either, so if multiple threads access a session or +cursor handle, access must be serialized by the application. + +@section threads_example Code samples + +The code below is taken from the complete example program +@ex_ref{ex_thread.c}. + +This is an example of a thread entry point. A new session is opened for +the thread and used for all operations within that thread. + +@snippet ex_thread.c thread scan + +Here is the main function that starts the threads. It opens a single +connection, shared between the threads, and closes the connection after +waiting for all of the threads to exit. + +@snippet ex_thread.c thread main + + */ diff --git a/src/docs/tools/doxypy.py b/src/docs/tools/doxypy.py new file mode 100755 index 00000000000..54fef5f03a5 --- /dev/null +++ b/src/docs/tools/doxypy.py @@ -0,0 +1,414 @@ +#!/usr/bin/env python + +__applicationName__ = "doxypy" +__blurb__ = """ +doxypy is an input filter for Doxygen. It preprocesses python +files so that docstrings of classes and functions are reformatted +into Doxygen-conform documentation blocks. +""" + +__doc__ = __blurb__ + \ +""" +In order to make Doxygen preprocess files through doxypy, simply +add the following lines to your Doxyfile: + FILTER_SOURCE_FILES = YES + INPUT_FILTER = "python /path/to/doxypy.py" +""" + +__version__ = "0.4.2" +__date__ = "14th October 2009" +__website__ = "http://code.foosel.org/doxypy" + +__author__ = ( + "Philippe 'demod' Neumann (doxypy at demod dot org)", + "Gina 'foosel' Haeussge (gina at foosel dot net)" +) + +__licenseName__ = "GPL v2" +__license__ = """This program is free software: you can redistribute it and/or modify +it under the terms of the GNU General Public License as published by +the Free Software Foundation, either version 2 of the License, or +(at your option) any later version. + +This program is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +GNU General Public License for more details. + +You should have received a copy of the GNU General Public License +along with this program. If not, see <http://www.gnu.org/licenses/>. +""" + +import sys +import re + +from optparse import OptionParser, OptionGroup + +class FSM(object): + """Implements a finite state machine. + + Transitions are given as 4-tuples, consisting of an origin state, a target + state, a condition for the transition (given as a reference to a function + which gets called with a given piece of input) and a pointer to a function + to be called upon the execution of the given transition. + """ + + """ + @var transitions holds the transitions + @var current_state holds the current state + @var current_input holds the current input + @var current_transition hold the currently active transition + """ + + def __init__(self, start_state=None, transitions=[]): + self.transitions = transitions + self.current_state = start_state + self.current_input = None + self.current_transition = None + + def setStartState(self, state): + self.current_state = state + + def addTransition(self, from_state, to_state, condition, callback): + self.transitions.append([from_state, to_state, condition, callback]) + + def makeTransition(self, input): + """Makes a transition based on the given input. + + @param input input to parse by the FSM + """ + for transition in self.transitions: + [from_state, to_state, condition, callback] = transition + if from_state == self.current_state: + match = condition(input) + if match: + self.current_state = to_state + self.current_input = input + self.current_transition = transition + if options.debug: + print >>sys.stderr, "# FSM: executing (%s -> %s) for line '%s'" % (from_state, to_state, input) + callback(match) + return + +class Doxypy(object): + def __init__(self): + string_prefixes = "[uU]?[rR]?" + + self.start_single_comment_re = re.compile("^\s*%s(''')" % string_prefixes) + self.end_single_comment_re = re.compile("(''')\s*$") + + self.start_double_comment_re = re.compile("^\s*%s(\"\"\")" % string_prefixes) + self.end_double_comment_re = re.compile("(\"\"\")\s*$") + + self.single_comment_re = re.compile("^\s*%s(''').*(''')\s*$" % string_prefixes) + self.double_comment_re = re.compile("^\s*%s(\"\"\").*(\"\"\")\s*$" % string_prefixes) + + self.defclass_re = re.compile("^(\s*)(def .+:|class .+:)") + self.empty_re = re.compile("^\s*$") + self.hashline_re = re.compile("^\s*#.*$") + self.importline_re = re.compile("^\s*(import |from .+ import)") + + self.multiline_defclass_start_re = re.compile("^(\s*)(def|class)(\s.*)?$") + self.multiline_defclass_end_re = re.compile(":\s*$") + + ## Transition list format + # ["FROM", "TO", condition, action] + transitions = [ + ### FILEHEAD + + # single line comments + ["FILEHEAD", "FILEHEAD", self.single_comment_re.search, self.appendCommentLine], + ["FILEHEAD", "FILEHEAD", self.double_comment_re.search, self.appendCommentLine], + + # multiline comments + ["FILEHEAD", "FILEHEAD_COMMENT_SINGLE", self.start_single_comment_re.search, self.appendCommentLine], + ["FILEHEAD_COMMENT_SINGLE", "FILEHEAD", self.end_single_comment_re.search, self.appendCommentLine], + ["FILEHEAD_COMMENT_SINGLE", "FILEHEAD_COMMENT_SINGLE", self.catchall, self.appendCommentLine], + ["FILEHEAD", "FILEHEAD_COMMENT_DOUBLE", self.start_double_comment_re.search, self.appendCommentLine], + ["FILEHEAD_COMMENT_DOUBLE", "FILEHEAD", self.end_double_comment_re.search, self.appendCommentLine], + ["FILEHEAD_COMMENT_DOUBLE", "FILEHEAD_COMMENT_DOUBLE", self.catchall, self.appendCommentLine], + + # other lines + ["FILEHEAD", "FILEHEAD", self.empty_re.search, self.appendFileheadLine], + ["FILEHEAD", "FILEHEAD", self.hashline_re.search, self.appendFileheadLine], + ["FILEHEAD", "FILEHEAD", self.importline_re.search, self.appendFileheadLine], + ["FILEHEAD", "DEFCLASS", self.defclass_re.search, self.resetCommentSearch], + ["FILEHEAD", "DEFCLASS_MULTI", self.multiline_defclass_start_re.search, self.resetCommentSearch], + ["FILEHEAD", "DEFCLASS_BODY", self.catchall, self.appendFileheadLine], + + ### DEFCLASS + + # single line comments + ["DEFCLASS", "DEFCLASS_BODY", self.single_comment_re.search, self.appendCommentLine], + ["DEFCLASS", "DEFCLASS_BODY", self.double_comment_re.search, self.appendCommentLine], + + # multiline comments + ["DEFCLASS", "COMMENT_SINGLE", self.start_single_comment_re.search, self.appendCommentLine], + ["COMMENT_SINGLE", "DEFCLASS_BODY", self.end_single_comment_re.search, self.appendCommentLine], + ["COMMENT_SINGLE", "COMMENT_SINGLE", self.catchall, self.appendCommentLine], + ["DEFCLASS", "COMMENT_DOUBLE", self.start_double_comment_re.search, self.appendCommentLine], + ["COMMENT_DOUBLE", "DEFCLASS_BODY", self.end_double_comment_re.search, self.appendCommentLine], + ["COMMENT_DOUBLE", "COMMENT_DOUBLE", self.catchall, self.appendCommentLine], + + # other lines + ["DEFCLASS", "DEFCLASS", self.empty_re.search, self.appendDefclassLine], + ["DEFCLASS", "DEFCLASS", self.defclass_re.search, self.resetCommentSearch], + ["DEFCLASS", "DEFCLASS_MULTI", self.multiline_defclass_start_re.search, self.resetCommentSearch], + ["DEFCLASS", "DEFCLASS_BODY", self.catchall, self.stopCommentSearch], + + ### DEFCLASS_BODY + + ["DEFCLASS_BODY", "DEFCLASS", self.defclass_re.search, self.startCommentSearch], + ["DEFCLASS_BODY", "DEFCLASS_MULTI", self.multiline_defclass_start_re.search, self.startCommentSearch], + ["DEFCLASS_BODY", "DEFCLASS_BODY", self.catchall, self.appendNormalLine], + + ### DEFCLASS_MULTI + ["DEFCLASS_MULTI", "DEFCLASS", self.multiline_defclass_end_re.search, self.appendDefclassLine], + ["DEFCLASS_MULTI", "DEFCLASS_MULTI", self.catchall, self.appendDefclassLine], + ] + + self.fsm = FSM("FILEHEAD", transitions) + self.outstream = sys.stdout + + self.output = [] + self.comment = [] + self.filehead = [] + self.defclass = [] + self.indent = "" + + def __closeComment(self): + """Appends any open comment block and triggering block to the output.""" + + if options.autobrief: + if len(self.comment) == 1 \ + or (len(self.comment) > 2 and self.comment[1].strip() == ''): + self.comment[0] = self.__docstringSummaryToBrief(self.comment[0]) + + if self.comment: + block = self.makeCommentBlock() + self.output.extend(block) + + if self.defclass: + self.output.extend(self.defclass) + + def __docstringSummaryToBrief(self, line): + """Adds \\brief to the docstrings summary line. + + A \\brief is prepended, provided no other doxygen command is at the + start of the line. + """ + stripped = line.strip() + if stripped and not stripped[0] in ('@', '\\'): + return "\\brief " + line + else: + return line + + def __flushBuffer(self): + """Flushes the current outputbuffer to the outstream.""" + if self.output: + try: + if options.debug: + print >>sys.stderr, "# OUTPUT: ", self.output + print >>self.outstream, "\n".join(self.output) + self.outstream.flush() + except IOError: + # Fix for FS#33. Catches "broken pipe" when doxygen closes + # stdout prematurely upon usage of INPUT_FILTER, INLINE_SOURCES + # and FILTER_SOURCE_FILES. + pass + self.output = [] + + def catchall(self, input): + """The catchall-condition, always returns true.""" + return True + + def resetCommentSearch(self, match): + """Restarts a new comment search for a different triggering line. + + Closes the current commentblock and starts a new comment search. + """ + if options.debug: + print >>sys.stderr, "# CALLBACK: resetCommentSearch" + self.__closeComment() + self.startCommentSearch(match) + + def startCommentSearch(self, match): + """Starts a new comment search. + + Saves the triggering line, resets the current comment and saves + the current indentation. + """ + if options.debug: + print >>sys.stderr, "# CALLBACK: startCommentSearch" + self.defclass = [self.fsm.current_input] + self.comment = [] + self.indent = match.group(1) + + def stopCommentSearch(self, match): + """Stops a comment search. + + Closes the current commentblock, resets the triggering line and + appends the current line to the output. + """ + if options.debug: + print >>sys.stderr, "# CALLBACK: stopCommentSearch" + self.__closeComment() + + self.defclass = [] + self.output.append(self.fsm.current_input) + + def appendFileheadLine(self, match): + """Appends a line in the FILEHEAD state. + + Closes the open comment block, resets it and appends the current line. + """ + if options.debug: + print >>sys.stderr, "# CALLBACK: appendFileheadLine" + self.__closeComment() + self.comment = [] + self.output.append(self.fsm.current_input) + + def appendCommentLine(self, match): + """Appends a comment line. + + The comment delimiter is removed from multiline start and ends as + well as singleline comments. + """ + if options.debug: + print >>sys.stderr, "# CALLBACK: appendCommentLine" + (from_state, to_state, condition, callback) = self.fsm.current_transition + + # single line comment + if (from_state == "DEFCLASS" and to_state == "DEFCLASS_BODY") \ + or (from_state == "FILEHEAD" and to_state == "FILEHEAD"): + # remove comment delimiter from begin and end of the line + activeCommentDelim = match.group(1) + line = self.fsm.current_input + self.comment.append(line[line.find(activeCommentDelim)+len(activeCommentDelim):line.rfind(activeCommentDelim)]) + + if (to_state == "DEFCLASS_BODY"): + self.__closeComment() + self.defclass = [] + # multiline start + elif from_state == "DEFCLASS" or from_state == "FILEHEAD": + # remove comment delimiter from begin of the line + activeCommentDelim = match.group(1) + line = self.fsm.current_input + self.comment.append(line[line.find(activeCommentDelim)+len(activeCommentDelim):]) + # multiline end + elif to_state == "DEFCLASS_BODY" or to_state == "FILEHEAD": + # remove comment delimiter from end of the line + activeCommentDelim = match.group(1) + line = self.fsm.current_input + self.comment.append(line[0:line.rfind(activeCommentDelim)]) + if (to_state == "DEFCLASS_BODY"): + self.__closeComment() + self.defclass = [] + # in multiline comment + else: + # just append the comment line + self.comment.append(self.fsm.current_input) + + def appendNormalLine(self, match): + """Appends a line to the output.""" + if options.debug: + print >>sys.stderr, "# CALLBACK: appendNormalLine" + self.output.append(self.fsm.current_input) + + def appendDefclassLine(self, match): + """Appends a line to the triggering block.""" + if options.debug: + print >>sys.stderr, "# CALLBACK: appendDefclassLine" + self.defclass.append(self.fsm.current_input) + + def makeCommentBlock(self): + """Indents the current comment block with respect to the current + indentation level. + + @returns a list of indented comment lines + """ + doxyStart = "##" + commentLines = self.comment + + commentLines = map(lambda x: "%s# %s" % (self.indent, x), commentLines) + l = [self.indent + doxyStart] + l.extend(commentLines) + + return l + + def parse(self, input): + """Parses a python file given as input string and returns the doxygen- + compatible representation. + + @param input the python code to parse + @returns the modified python code + """ + lines = input.split("\n") + + for line in lines: + self.fsm.makeTransition(line) + + if self.fsm.current_state == "DEFCLASS": + self.__closeComment() + + return "\n".join(self.output) + + def parseFile(self, filename): + """Parses a python file given as input string and returns the doxygen- + compatible representation. + + @param input the python code to parse + @returns the modified python code + """ + f = open(filename, 'r') + + for line in f: + self.parseLine(line.rstrip('\r\n')) + if self.fsm.current_state == "DEFCLASS": + self.__closeComment() + self.__flushBuffer() + f.close() + + def parseLine(self, line): + """Parse one line of python and flush the resulting output to the + outstream. + + @param line the python code line to parse + """ + self.fsm.makeTransition(line) + self.__flushBuffer() + +def optParse(): + """Parses commandline options.""" + parser = OptionParser(prog=__applicationName__, version="%prog " + __version__) + + parser.set_usage("%prog [options] filename") + parser.add_option("--autobrief", + action="store_true", dest="autobrief", + help="use the docstring summary line as \\brief description" + ) + parser.add_option("--debug", + action="store_true", dest="debug", + help="enable debug output on stderr" + ) + + ## parse options + global options + (options, filename) = parser.parse_args() + + if not filename: + print >>sys.stderr, "No filename given." + sys.exit(-1) + + return filename[0] + +def main(): + """Starts the parser on the file given by the filename as the first + argument on the commandline. + """ + filename = optParse() + fsm = Doxypy() + fsm.parseFile(filename) + +if __name__ == "__main__": + main() diff --git a/src/docs/tools/fixlinks.py b/src/docs/tools/fixlinks.py new file mode 100755 index 00000000000..b249307f3c3 --- /dev/null +++ b/src/docs/tools/fixlinks.py @@ -0,0 +1,61 @@ +#!/usr/bin/env python +# +# Copyright (c) 2008-2012 WiredTiger, Inc. +# +# This is free and unencumbered software released into the public domain. +# +# Anyone is free to copy, modify, publish, use, compile, sell, or +# distribute this software, either in source code form or as a compiled +# binary, for any purpose, commercial or non-commercial, and by any +# means. +# +# In jurisdictions that recognize copyright laws, the author or authors +# of this software dedicate any and all copyright interest in the +# software to the public domain. We make this dedication for the benefit +# of the public at large and to the detriment of our heirs and +# successors. We intend this dedication to be an overt act of +# relinquishment in perpetuity of all present and future rights to this +# software under copyright law. +# +# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, +# EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. +# IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR +# OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, +# ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR +# OTHER DEALINGS IN THE SOFTWARE. +# +# This Python script is run as part of generating the documentation for the +# WiredTiger Python API. It runs after doxypy, and turns method names in +# comments into references to the corresponding function in the C API. + +import re, sys + +def process(source): + # Replace standard struct wrapper wording + source = re.sub(r'(\s+#.*)Proxy of C (\w+) struct', + lambda m: ('%sPython wrapper around C ::%s%s@copydoc ::%s' % (m.group(1), m.group(2).upper(), m.group(1), m.group(2).upper())), source) + + # Replace lowercase class names with upper case + source = re.sub(r'(\s+#.*)(wt_\w+)::', + lambda m: ('%s%s::' % (m.group(1), m.group(2).upper())), source) + + # Replace "char" with "string" in comments + while True: + newsource = re.sub(r'(\s+#.*)\bchar\b', r'\1string', source) + if newsource == source: + break + source = newsource + + # Copy documentation + source = re.sub(r'(\s+# )(\w+)\(self, (connection|cursor|session).*', + lambda m: ('%s%s%s@copydoc WT_%s::%s' % + (m.group(0), m.group(1), m.group(1), m.group(3).upper(), m.group(2))), + source) + + # Replace "self, handle" with "self" -- these are typedef'ed away + source = re.sub(r'(\s+#.*self), (?:connection|cursor|session)', r'\1', source) + return source + +if __name__ == '__main__': + sys.stdout.write(process(sys.stdin.read())) diff --git a/src/docs/tools/pyfilter b/src/docs/tools/pyfilter new file mode 100755 index 00000000000..67ee7ca4544 --- /dev/null +++ b/src/docs/tools/pyfilter @@ -0,0 +1,30 @@ +#!/bin/sh +# +# Copyright (c) 2008-2012 WiredTiger, Inc. +# +# This is free and unencumbered software released into the public domain. +# +# Anyone is free to copy, modify, publish, use, compile, sell, or +# distribute this software, either in source code form or as a compiled +# binary, for any purpose, commercial or non-commercial, and by any +# means. +# +# In jurisdictions that recognize copyright laws, the author or authors +# of this software dedicate any and all copyright interest in the +# software to the public domain. We make this dedication for the benefit +# of the public at large and to the detriment of our heirs and +# successors. We intend this dedication to be an overt act of +# relinquishment in perpetuity of all present and future rights to this +# software under copyright law. +# +# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, +# EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. +# IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR +# OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, +# ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR +# OTHER DEALINGS IN THE SOFTWARE. + +tooldir=`dirname $0` + +python $tooldir/doxypy.py "$@" | python $tooldir/fixlinks.py diff --git a/src/docs/top/Doxyfile b/src/docs/top/Doxyfile new file mode 100644 index 00000000000..468dd31aee4 --- /dev/null +++ b/src/docs/top/Doxyfile @@ -0,0 +1,9 @@ +# Override settings in the normal documentation build for the landing page. + +PROJECT_NUMBER = "Developer Site" +OUTPUT_DIRECTORY = ../../docs/top +INPUT = top license.dox +EXCLUDE = + +GENERATE_TREEVIEW = NO +USE_INLINE_TREES = NO diff --git a/src/docs/top/main.dox b/src/docs/top/main.dox new file mode 100644 index 00000000000..d7294dc0bd9 --- /dev/null +++ b/src/docs/top/main.dox @@ -0,0 +1,18 @@ +-/*! @mainpage WiredTiger Developer Site + +WiredTiger is an high performance, scalable, production quality, NoSQL, +@subpage license "Open Source" extensible platform for data management. + +To browse or download the WiredTiger source code, visit our + +- <a href="https://github.com/wiredtiger/wiredtiger"><b>Project page</b></a> + +To ask questions or discuss issues related to using WiredTiger, visit our + +- <a href="http://groups.google.com/group/wiredtiger-users"><b>User Group</b></a> + +View the documentation online: + +- <a href="1.2.0/index.html"><b>WiredTiger 1.2.0 documentation (current)</b></a> +- <a href="1.1.5/index.html"><b>WiredTiger 1.1.5 documentation</b></a> +*/ diff --git a/src/docs/transactions.dox b/src/docs/transactions.dox new file mode 100644 index 00000000000..b94515c007c --- /dev/null +++ b/src/docs/transactions.dox @@ -0,0 +1,86 @@ +/*! @page transactions Transactions + +@section transactions_acid ACID properties + +Transactions provide a powerful abstraction for multiple threads to operate +on data concurrently because they have the following properties: + +- Atomicity: all or none of a transaction is completed. +- Consistency: if each transaction maintains some property when considered + separately, then the combined effect of executing the transactions + concurrently will maintain the same property. +- Isolation: developers can reason about transactions as if they run + single-threaded. +- Durability: once a transaction commits, its updates cannot be lost. + +In WiredTiger release 1.2, support for transactions was added with the +following caveats to the ACID properties: + +- the maximum level of isolation supported is snapshot isolation. + See @ref transaction_isolation for more details. +- only coarse-grained durability is supported: updates become durable when they + are part of a checkpoint, not at commit time. If there is a crash, commits + since the last checkpoint will be lost. + +@section transactions_api Transactional API + +In WiredTiger, the transactional context is managed by the WT_SESSION +class. Applications call WT_SESSION::begin_transaction to start a new +transaction, which is only permitted when no cursors are open. Operations +performed with that WT_SESSION handle are then part of the transaction, and +their effects can be committed by calling WT_SESSION::commit_transaction or +WT_SESSION::rollback_transaction, both of which implicitly close any open +cursors. + +When transactions are used, concurrent update operations will fail with the +::WT_DEADLOCK error if they conflict with a concurrent transaction. +Transactions should be rolled back with WT_SESSION::rollback_transaction and +retried if this error occurs. + +@section transactions_cc Concurrency control + +WiredTiger uses optimistic concurrency control algorithms. This avoids the +bottleneck of a centralized lock manager, and means that transactional +operations do not block: reads do not block writes, and vice versa. + +Further, writes do not block writes, but as mentioned above, concurrent +transactions updating the same value will fail with ::WT_DEADLOCK. Some +applications may benefit from application-level synchronization to avoid +repeated attempts to rollback and update the same value. + +@section transaction_isolation Isolation levels + +The default isolation level is <code>snapshot</code>, which means that each +transaction reads the versions of records that were committed before the +transaction started. + +Snapshot isolation is a strong guarantee, but not equivalent to a +single-threaded execution of the transactions, known as serializable isolation. +Concurrent transactions T1 and T2 running under snapshot isolation may both +commit and produce a state that neither (T1 followed by T2) or (T2 followed by +T1) could have produced, if there is overlap between T1's reads and T2's +writes, and between T1's writes and T2's reads. + +Weaker isolation levels are also provided, including +<code>read-uncommitted</code>, which always reads the most recent version of +data, regardless of whether it is committed. + +@section transaction_recovery Checkpoints and Recovery + +Recovery is run automatically when a data source is opened. Any changes since +the last checkpoint are discarded, and the application restarts from a +consistent point in the transaction history. + +This suggests the importance of regular checkpoints: they limit the volume of +commits that may be lost in a crash. Checkpoints create a snapshot in every +data source in the database. See WT_SESSION::checkpoint for information about +checkpoints, and @ref snapshots for information about snapshots. + +@section transaction_example Code samples + +The code below is taken from the complete example program +@ex_ref{ex_transaction.c}. + +@snippet ex_transaction.c transaction + + */ diff --git a/src/docs/tuning.dox b/src/docs/tuning.dox new file mode 100644 index 00000000000..83de3584985 --- /dev/null +++ b/src/docs/tuning.dox @@ -0,0 +1,138 @@ +/*! @page tuning Performance Tuning + +@section cache Cache size + +The cache size for the database is configurable by setting the \c +cache_size configuration string when calling the ::wiredtiger_open +function. + +The effectiveness of the cache can be measured by reviewing the page +eviction statistics for the database. + +An example of setting a cache size to 500MB: + +@snippet ex_config.c configure cache size + +@section page Page and overflow sizes + +There are four page and item size configuration values: \c internal_page_max, +\c internal_item_max, \c leaf_page_max and \c leaf_item_max. All four should +be specified to the WT_SESSION::create method, that is, they are configurable +on a per-file basis. + +The \c internal_page_max and \c leaf_page_max configuration values specify +the maximum size for Btree internal and leaf pages. That is, when an +internal or leaf page reaches the specified size, it splits into two pages. +Generally, internal pages should be sized to fit into the system's L1 or L2 +caches in order to minimize cache misses when searching the tree, while leaf +pages should be sized to maximize I/O performance (if reading from disk is +necessary, it is usually desirable to read a large amount of data, assuming +some locality of reference in the application's access pattern). + +The \c internal_item_max and \c leaf_item_max configuration values specify +the maximum size at which an object will be stored on-page. Larger items +will be stored separately in the file from the page where the item logically +appears. Referencing overflow items is more expensive than referencing +on-page items, requiring additional I/O if the object is not already cached. +For this reason, it is important to avoid creating large numbers of overflow +items that are repeatedly referenced, and the maximum item size should +probably be increased if many overflow items are being created. Because +pages must be large enough to store any item that is not an overflow item, +increasing the size of the overflow items may also require increasing the +page sizes. + +With respect to compression, page and item sizes do not necessarily reflect +the actual size of the page or item on disk, if block compression has been +configured. Block compression in WiredTiger happens within the disk I/O +subsystem, and so a page might split even if subsequent compression would +result in a resulting page size that would be small enough to leave as a +single page. In other words, page and overflow sizes are based on in-memory +sizes, not disk sizes. + +There are two other, related configuration values, also settable by the +WT_SESSION::create method. They are \c allocation_size, and \c split_pct. + +The \c allocation_size configuration value is the underlying unit of +allocation for the file. As the unit of file allocation, it has two +effects: first, it limits the ultimate size of the file, and second, it +determines how much space is wasted when storing overflow items. + +By limiting the size of the file, the allocation size limits the amount +of data that can be stored in a file. For example, if the allocation +size is set to the minimum possible (512B), the maximum file size is +2TB, that is, attempts to allocate new file blocks will fail when the +file reaches 2TB in size. If the allocation size is set to the maximum +possible (512MB), the maximum file size is 2EB. + +The unit of allocation also determines how much space is wasted when +storing overflow items. For example, if the allocation size were set +to the minimum value of 512B, an overflow item of 1100 bytes would +require 3 allocation sized file units, or 1536 bytes, wasting almost 500 +bytes. For this reason, as the allocation size increases, page sizes +and overflow item sizes will likely increase as well, to ensure that +significant space isn't wasted by overflow items. + +The last configuration value is \c split_pct, which configures the size +of a split page. When a page grows sufficiently large that it must be +split, the newly split page's size is \c split_pct percent of the +maximum page size. This value should be selected to avoid creating a +large number of tiny pages or repeatedly splitting whenever new entries +are inserted. For example, if the maximum page size is 1MB, a \c +split_pct value of 10% would potentially result in creating a large +number of 100KB pages, which may not be optimal for future I/O. Or, if +the maximum page size is 1MB, a \c split_pct value of 90% would +potentially result in repeatedly splitting pages as the split pages grow +to 1MB over and over. The default value for \c split_pct is 75%, +intended to keep large pages relatively large, while still giving split +pages room to grow. + +An example of configuring page sizes: + +@snippet ex_file.c file create + +@section memory Memory allocation + +I/O intensive threaded applications, where the working set does not fit +into the available cache, can be dominated by memory allocation because +the WiredTiger engine has to free and re-allocate memory as part of many +queries. Replacing the system's malloc implementation with one that has +better threaded performance (for example, Google's +<a href="http://goog-perftools.sourceforge.net/doc/tcmalloc.html">tcmalloc</a>, +or <a href="http://www.canonware.com/jemalloc">jemalloc</a>), +can dramatically improve throughput. + +@section checksums Checksums + +WiredTiger configures checksums on file reads and writes, by default. +In read-only applications, or when file compression provides any +necessary checksum functionality, or when using backing storage systems +where blocks require no validation, performance can be increased by +turning off checksum support when calling the WT_SESSION::create method. + +@section statistics Performance monitoring with statistics + +WiredTiger maintains a variety of statistics that can be read with a +cursor. The statistics are at two levels: per-database statistics and +per-underlying file statistics. The database statistics are the +default; the underlying file statistics are available by specifying the +appropriate uri. + +The following is an example of printing run-time statistics about the +WiredTiger engine: + +@snippet ex_stat.c statistics database function + +The following is an example of printing statistics about an underlying +file: + +@snippet ex_stat.c statistics file function + +Both examples can use a common display routine that iterates through the +statistics until the cursor returns the end of the list. + +@snippet ex_stat.c statistics display function + +Note the raw value of the statistic is available from the \c value +field, as well as a printable string version of the value. + + */ |
