diff --git a/Makefile.am b/Makefile.am index c990590..1b767c3 100644 --- a/Makefile.am +++ b/Makefile.am @@ -15,7 +15,6 @@ ACLOCAL_AMFLAGS = -I m4 #-Wconversion docs: - doxygen doc/Doxyfile-api doxygen doc/Doxyfile-developers tidy: precoverage diff --git a/doc/Doxyfile-developers b/doc/Doxyfile-developers index 4b7cdf6..8d83c06 100644 --- a/doc/Doxyfile-developers +++ b/doc/Doxyfile-developers @@ -1,231 +1,1309 @@ -# Doxyfile 1.3.6-20040222 +# Doxyfile 1.5.3 + +# 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 = "Stasis" + +# 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 = 1 + +# 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 = doc/developers + +# 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, Finnish, French, German, Greek, Hungarian, +# Italian, Japanese, Japanese-en (Japanese with English messages), Korean, +# Korean-en, Lithuanian, Norwegian, Polish, Portuguese, Romanian, Russian, +# Serbian, Slovak, Slovene, Spanish, Swedish, and Ukrainian. + OUTPUT_LANGUAGE = English -USE_WINDOWS_ENCODING = NO + +# 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 = + +# 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 = + +# If the SHORT_NAMES tag is set to YES, doxygen will generate much shorter +# (but less readable) file names. This can be useful is your file systems +# 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 = NO + +# 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 -DETAILS_AT_TOP = NO + +# If the DETAILS_AT_TOP tag is set to YES then Doxygen +# will output the detailed description near the top, like JavaDoc. +# If set to NO, the detailed description appears after the member +# documentation. + +DETAILS_AT_TOP = YES + +# 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 -DISTRIBUTE_GROUP_DOC = NO + +# 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 = + +# 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 = YES + +# 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 = NO + +# 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 make 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 + +# 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 + #--------------------------------------------------------------------------- # 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 = YES + +# If the EXTRACT_PRIVATE tag is set to YES all private members of a class +# will be included in the documentation. + EXTRACT_PRIVATE = YES + +# If the EXTRACT_STATIC tag is set to YES all static members of a file +# will be included in the documentation. + EXTRACT_STATIC = YES + +# 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 namespace 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 = YES + +# 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 = YES + +# 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 = YES + +# 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_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 = 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 = YES + +# 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 define 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 defines in the +# documentation can be controlled using \showinitializer or \hideinitializer +# command in the documentation regardless of this setting. + MAX_INITIALIZER_LINES = 30 + +# 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 = YES + +# 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 = YES + +# 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 , where is the value of +# the FILE_VERSION_FILTER tag, and 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 = + #--------------------------------------------------------------------------- # 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 = YES -WARNINGS = YES + +# 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 = NO + +# 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 -WARN_FORMAT = "$file:$line: $text" + +# This WARN_NO_PARAMDOC option can be abled 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 = NO + +# 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 = + #--------------------------------------------------------------------------- # configuration options related to the input files #--------------------------------------------------------------------------- -INPUT = stasis \ - src \ - test -# libdfa \ -# pbl \ -# + +# 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 = doc/modules \ + stasis \ + src +# test/stasis + +# 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++ *.java *.ii *.ixx *.ipp *.i++ *.inl *.h *.hh *.hxx +# *.hpp *.h++ *.idl *.odl *.cs *.php *.php3 *.inc *.m *.mm *.py + FILE_PATTERNS = *.c \ *.h + +# 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 = src/2pc \ - src/libdfa \ - src/pbl \ - test/2pc \ - test/cht \ - test/dfa \ - test/lladd-old \ - test/messages \ - test/monotree \ - src/apps/cht + src/libdfa \ + src/pbl \ + src/pobj \ + test/2pc \ + test/cht \ + test/dfa \ + test/lladd-old \ + test/messages \ + test/monotree \ + src/apps \ + src/timing + +# The EXCLUDE_SYMLINKS tag can be used select whether or not files or +# directories that are symbolic links (a Unix filesystem 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 = + +# 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 = . + +# 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 -IMAGE_PATH = -INPUT_FILTER = + +# 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 = doc/figures + +# 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 , where +# is the value of the INPUT_FILTER tag, and 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 = "perl -pe 's/^START_TEST\(([^\)]+)\)/test_$1()/;s/^END_TEST//;' " + +# 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, INPUT_FILTER +# is applied to all files. + +FILTER_PATTERNS = + +# 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 + #--------------------------------------------------------------------------- # 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. If you have enabled CALL_GRAPH or CALLER_GRAPH +# then you must also enable this option. If you don't then doxygen will produce +# a warning and turn it on anyway + SOURCE_BROWSER = YES -INLINE_SOURCES = NO # YES -STRIP_CODE_COMMENTS = YES + +# 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 = NO + +# If the REFERENCED_BY_RELATION tag is set to YES (the default) +# then for each documented function all documented +# functions referencing it will be listed. + REFERENCED_BY_RELATION = YES + +# If the REFERENCES_RELATION tag is set to YES (the default) +# then for each documented function all documented entities +# called/used by that function will be listed. + REFERENCES_RELATION = YES + +# 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 documentstion. + +REFERENCES_LINK_SOURCE = YES + +# 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 = YES + #--------------------------------------------------------------------------- # 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 = YES + +# 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 = + #--------------------------------------------------------------------------- # 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 = html + +# 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. + HTML_HEADER = + +# 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 = + +# 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 = + +# 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 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 compressed HTML help file (.chm) +# of the generated HTML documentation. + GENERATE_HTMLHELP = 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_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 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 + +# 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 + +# This tag can be used to set the number of enum values (range [1..20]) +# that doxygen will group on one line in the generated HTML documentation. + ENUM_VALUES_PER_LINE = 4 + +# If the GENERATE_TREEVIEW tag 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 (for instance Mozilla 1.0+, +# Netscape 6.0+, Internet explorer 5.0+, or Konqueror). Windows users are +# probably better off using the HTML help feature. + GENERATE_TREEVIEW = 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 = 250 + #--------------------------------------------------------------------------- # 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 = YES + +# 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. + 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, a4wide, letter, legal and +# executive. If left blank a4wide will be used. + PAPER_TYPE = letter + +# 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 = + +# 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 = NO + #--------------------------------------------------------------------------- # 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 #--------------------------------------------------------------------------- -ENABLE_PREPROCESSING = YES -MACRO_EXPANSION = NO -EXPAND_ONLY_PREDEF = NO -SEARCH_INCLUDES = YES -INCLUDE_PATH = -INCLUDE_FILE_PATTERNS = -## Needed for doxygen to make sane documentation from check tests. -# or, I'll just write a perl script since it's easier. -#PREDEFINED = START_TEST END_TEST -EXPAND_AS_DEFINED = -SKIP_FUNCTION_MACROS = NO -#YES -QUIET=YES -WARNINGS=NO -# Muh-ha-ha-ha_ha -INPUT_FILTER="perl -pe 's/^START_TEST\(([^\)]+)\)/test_$1()/;s/^END_TEST//;'" +# 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 = NO + +# 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 +# in the INCLUDE_PATH (see below) will be search if 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 = + +# 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. + +EXPAND_AS_DEFINED = + +# If the SKIP_FUNCTION_MACROS tag is set to YES (the default) then +# doxygen's preprocessor will remove all function-like macros that are alone +# on a line, have an all uppercase name, and do not end with a semicolon. Such +# function macros are typically used for boiler-plate code, and will confuse +# the parser if not removed. + +SKIP_FUNCTION_MACROS = NO + #--------------------------------------------------------------------------- # 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 is superseded by the HAVE_DOT option below. This is only a +# fallback. 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 -HAVE_DOT = NO # 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 + +# 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 = YES + +# 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, SOURCE_BROWSER and HAVE_DOT tags 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 = YES + +# If the CALLER_GRAPH, SOURCE_BROWSER 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 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 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 = -MAX_DOT_GRAPH_WIDTH = 1024 -MAX_DOT_GRAPH_HEIGHT = 1024 + +# The MAX_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 +# MAX_DOT_GRAPH_NOTES 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, which results in a white background. +# 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 + #--------------------------------------------------------------------------- # Configuration::additions related to the search engine #--------------------------------------------------------------------------- + +# The SEARCHENGINE tag specifies whether or not a search engine should be +# used. If set to NO the values of all tags below this one will be ignored. + SEARCHENGINE = YES diff --git a/doc/figures/StasisDBMS.png b/doc/figures/StasisDBMS.png new file mode 100644 index 0000000..bb17373 Binary files /dev/null and b/doc/figures/StasisDBMS.png differ diff --git a/doc/figures/StasisDBMS.svg b/doc/figures/StasisDBMS.svg new file mode 100644 index 0000000..926aa1f --- /dev/null +++ b/doc/figures/StasisDBMS.svg @@ -0,0 +1,413 @@ + + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + Query Processor + RelationalStorage API + Tuple Store + Indices / Ref.Integrity + Allocation andspace mgmt + Recovery + Page formats/ metadata + BufferManager + Logger + Page evictionLRU/DBMIN/? + OS Wrappers: I/O, Memory mgmtThreading, etc... + StasisCoreLibrary + Operations API + Record API + TransactionalPage API + StasisExtensions + + + + Lock Manager + + + + + diff --git a/doc/modules b/doc/modules new file mode 100644 index 0000000..d11bced --- /dev/null +++ b/doc/modules @@ -0,0 +1,50 @@ +/** + @defgroup LLADD_CORE +*//** + @defgroup BUFFER_MANAGER + @ingroup LLADD_CORE +*//** @defgroup BUFFER_MANAGER_IMPLEMENTATIONS + @ingroup BUFFER_MANAGER +*//** + @defgroup PAGE_EVICTION + @ingroup BUFFER_MANAGER +*//** + @defgroup LOGGER + @ingroup LLADD_CORE +*//** + @defgroup LOGGING_DISCIPLINES + @ingroup LOGGER +*//** + @defgroup RECOVERY + @ingroup LLADD_CORE +*//** + @defgroup PAGE_FORMATS +*//** + @defgroup PAGE_HOWTO + @ingroup PAGE_FORMATS +*//** + @defgroup PAGE_HEADER + @ingroup PAGE_FORMATS +*//** + @defgroup PAGE_UTIL + @ingroup PAGE_FORMATS +*//** + @defgroup PAGE_RECORD_INTERFACE + @ingroup PAGE_FORMATS +*//** + @defgroup PAGE_IMPLEMENTATIONS + @ingroup PAGE_FORMATS +*//** + @defgroup ALLOCATION +*//** + @defgroup OPERATIONS +*//** + @defgroup COLLECTIONS + @ingroup OPERATIONS +*//** + @defgroup ARRAY_LIST + @ingroup COLLECTIONS +*//** + @defgroup ROSE + @ingroup OPERATIONS +*/ \ No newline at end of file diff --git a/src/stasis/bufferPool.c b/src/stasis/bufferPool.c index d11f8e9..a0ac7dd 100644 --- a/src/stasis/bufferPool.c +++ b/src/stasis/bufferPool.c @@ -41,7 +41,9 @@ terms specified in this license. ---*/ /** - * @file Implementation of in memory buffer pool + * @file + * + * Implementation of in memory buffer pool * * $Id$ * diff --git a/src/stasis/io/non_blocking.c b/src/stasis/io/non_blocking.c index 6670cac..fdc46a9 100644 --- a/src/stasis/io/non_blocking.c +++ b/src/stasis/io/non_blocking.c @@ -180,7 +180,7 @@ typedef struct nbw_impl { static inline void freeFastHandle(nbw_impl * impl, const tree_node * n); /** Obtain a slow handle from the pool of existing ones, or obtain a new one - by calling impl->slow_factory.. */ + by calling impl.slow_factory. */ static stasis_handle_t * getSlowHandle(nbw_impl * impl) { pthread_mutex_lock(&impl->mut); stasis_handle_t * slow diff --git a/src/stasis/logger/logger2.c b/src/stasis/logger/logger2.c index 5b278d0..714f362 100644 --- a/src/stasis/logger/logger2.c +++ b/src/stasis/logger/logger2.c @@ -41,7 +41,9 @@ terms specified in this license. ---*/ /** - @file Abstract log implementation. Provides access to methods that + @file + + Abstract log implementation. Provides access to methods that directly read and write log entries, force the log to disk, etc. @todo Switch logger2 to use function pointers diff --git a/src/stasis/operations/arrayList.c b/src/stasis/operations/arrayList.c index 8e6ce3d..f025d8b 100644 --- a/src/stasis/operations/arrayList.c +++ b/src/stasis/operations/arrayList.c @@ -12,19 +12,6 @@ #define _XOPEN_SOURCE 600 #include - - -/** - Implement resizable arrays, just like java's ArrayList class. - - Essentially, the base page contains a fixed size array of rids - pointing at contiguous blocks of pages. Each block is twice as - big as the previous block. - - The base block is of type FIXED_PAGE, of int's. The first few slots are reserved: - -*/ - typedef struct { int firstPage; int initialSize; @@ -166,7 +153,6 @@ static compensated_function int TarrayListExtendInternal(int xid, recordid rid, int blockSize = tlp.initialSize * pow(tlp.multiplier, i); int newFirstPage = TpageAllocMany(xid, blockSize); DEBUG("block %d\n", i); - /* We used to call OPERATION_INITIALIZE_FIXED_PAGE on each page in current indirection block. */ tmp.slot = i + FIRST_DATA_PAGE_OFFSET; /* Iterate over the (large number) of new blocks, clearing their contents */ /* @todo XXX arraylist generates N log entries initing pages. diff --git a/src/stasis/recovery2.c b/src/stasis/recovery2.c index 7df7da0..28ae124 100644 --- a/src/stasis/recovery2.c +++ b/src/stasis/recovery2.c @@ -1,6 +1,8 @@ /** - @file Implements three phase recovery + @file + + Implements three phase recovery */ @@ -20,7 +22,7 @@ #include #include -/** @todo Get rid of linkedlist.[ch] */ +/** @todo Get rid of linkedlist */ #include #include // Needed for pageReadLSN. @@ -28,7 +30,7 @@ static pblHashTable_t * transactionLSN; static LinkedList * rollbackLSNs = NULL; /** @todo There is no real reason to have this mutex (which prevents - concurrent aborts, except that we need to protect rollbackLSNs's + concurrent aborts), except that we need to protect rollbackLSNs's from concurrent modifications. */ static pthread_mutex_t rollback_mutex = PTHREAD_MUTEX_INITIALIZER; diff --git a/src/stasis/transactional2.c b/src/stasis/transactional2.c index 1103a97..00b247f 100644 --- a/src/stasis/transactional2.c +++ b/src/stasis/transactional2.c @@ -68,9 +68,7 @@ void setupOperationsTable() { operationsTable[OPERATION_NOOP] = getNoop(); operationsTable[OPERATION_INSTANT_SET] = getInstantSet(); operationsTable[OPERATION_ARRAY_LIST_ALLOC] = getArrayListAlloc(); - // operationsTable[OPERATION_INITIALIZE_FIXED_PAGE] = getInitFixed(); operationsTable[OPERATION_INITIALIZE_PAGE] = getInitializePage(); - // operationsTable[OPERATION_UNINITIALIZE_PAGE] = getUnInitPage(); operationsTable[OPERATION_LINEAR_INSERT] = getLinearInsert(); operationsTable[OPERATION_UNDO_LINEAR_INSERT] = getUndoLinearInsert(); diff --git a/stasis/bufferManager.h b/stasis/bufferManager.h index 530ab0f..e5dc5c3 100644 --- a/stasis/bufferManager.h +++ b/stasis/bufferManager.h @@ -73,7 +73,7 @@ terms specified in this license. When such a value is returned, the transaction aborts, and an error is passed up to the application. - * @ingroup LLADD_CORE + @ingroup BUFFER_MANAGER * $Id$ */ diff --git a/stasis/logger/logger2.h b/stasis/logger/logger2.h index eb8a5df..2616a7c 100644 --- a/stasis/logger/logger2.h +++ b/stasis/logger/logger2.h @@ -43,7 +43,9 @@ terms specified in this license. /** * @file * - * New version of logger. Based on logger.h + * Interface to Stasis' log file. + * + * @ingroup LOGGING_DISCIPLINE * * $Id$ * diff --git a/stasis/operations.h b/stasis/operations.h index 8cb04a7..5148334 100644 --- a/stasis/operations.h +++ b/stasis/operations.h @@ -45,10 +45,21 @@ terms specified in this license. * * Interface for defining new logical operations. * - * @ingroup LLADD_CORE OPERATIONS + * @ingroup OPERATIONS * @todo The functions in operations.h don't belong in the API, but it defines some constants and typedefs that should be there. * $Id$ */ +/** + @defgroup COLLECTIONS Collections + + Stasis provides a number of general-purpose data structures for use + by applications. + + Stasis provides a number of general-purpose data structures for use + by applications. This section documents these data structures and + associated interfaces, such as iterators. +*/ + #ifndef __OPERATIONS_H__ #define __OPERATIONS_H__ diff --git a/stasis/operations/arrayList.h b/stasis/operations/arrayList.h index 858bf85..c6e76f6 100644 --- a/stasis/operations/arrayList.h +++ b/stasis/operations/arrayList.h @@ -40,34 +40,86 @@ permission to use and distribute the software in accordance with the terms specified in this license. ---*/ /** - @file + @file - Implements an extendible array of fixed length records with O(1) - complexity for all operations. + @ingroup ARRAY_LIST - @ingroup OPERATIONS + @defgroup ARRAY_LIST ArrayList + + O(1) growable array. + + ArrayList provides an growable array of fixed length records with + O(1) complexity for all operations. The list grows by doubling the + amount of space it reserves each time the list is extended. + Therefore, this data structure can use up to twice as much storage + as is strictly necessary. + + These arrays are similar to those in Java's ArrayList class. + Essentially, the base page contains a fixed size array of recordid's + pointing at contiguous blocks of pages. Each block is twice as big + as the previous block. + + The base block is of type FIXED_PAGE, of int values. The first few slots + are reserved and store information about the arrayList (size of + array entries, number/size of allocated regions, etc.) + + @todo arrayList's base block should store pageid_t values, not ints. + + @ingroup COLLECTIONS $Id$ */ + +/** @ingroup ARRAY_LIST */ +/** @{ */ #ifndef __ARRAY_LIST_H #define __ARRAY_LIST_H +/** Allocate a new array list. + + @param xid The transaction allocating the new arrayList. + + @param numPages The number of pages to be allocated as part of the + first region. (The arraylist starts with zero capacity + regardless of this parameter's value.) + + @param multiplier Each time the array list runs out of space, the + allocate multipler times more space than last time. + + @param recordSize The size of the things stored in this arrayList. + Must fit on a single page (arrayList cannot store blobs.) + +*/ + compensated_function recordid TarrayListAlloc(int xid, int numPages, int multiplier, int recordSize); +/** + Extend the ArrayList in place. + + @param xid the transaction performing the expansion + @param rid the recordid pointing to the ArrayList. + @param slots the number of slots to end to the end of the ArrayList. + */ +compensated_function int TarrayListExtend(int xid, recordid rid, int slots); +/** + Do not call this function. + + @deprecated This function is known to be broken, and is only + called by a deprecated hash implementation. + */ +compensated_function int TarrayListInstantExtend(int xid, recordid rid, int slots); +/** + Get the length of an ArrayList. + + @param xid the transaction performing the expansion + @param rid the recordid pointing to the ArrayList. + @return The number of items stored in the ArrayList. + */ +compensated_function int TarrayListLength(int xid, recordid rid); + +/** Used by Tread() and Tset() to map from arrayList index to recordid. */ +recordid dereferenceArrayListRid(int xid, Page * p, int offset); Operation getArrayListAlloc(); -Operation getInitFixed(); -Operation getUnInitPage(); - -/** Initialized a fixed page with the maximum possible number of slots - allocated. The rid.size field is used to determine the size of - record that the slots can hold. */ -#define TinitFixed(xid, rid) Tupdate(xid, rid, NULL, OPERATION_INITIALIZE_FIXED_PAGE) -/** Un-initializes a page. */ -#define TunInitPage(xid, rid) Tupdate(xid, rid, NULL, OPERATION_UNINITIALIZE_PAGE) - -recordid dereferenceArrayListRid(int xid, Page * p, int offset); -compensated_function int TarrayListExtend(int xid, recordid rid, int slots); -compensated_function int TarrayListInstantExtend(int xid, recordid rid, int slots); -compensated_function int TarrayListLength(int xid, recordid rid); +/** @} */ #endif diff --git a/stasis/operations/lsmTree.h b/stasis/operations/lsmTree.h index a0fc7e9..6a5fea0 100644 --- a/stasis/operations/lsmTree.h +++ b/stasis/operations/lsmTree.h @@ -87,12 +87,14 @@ void TlsmFree(int xid, recordid tree, lsm_page_deallocator_t dealloc, /** Lookup a leaf page. + @param xid The transaction that is looking up this page + + @param tree The tree to be queried. + @param key The value you're looking for. The first page that may contain this value will be returned. (lsmTree supports - duplicate keys...) - - @param keySize Must match the keySize passed to TlsmCreate. - Currently unused. + duplicate keys...) LSM trees currently store fixed + length keys, so there is no keySize parameter. */ pageid_t TlsmFindPage(int xid, recordid tree, const byte *key); diff --git a/stasis/page.h b/stasis/page.h index c7adb15..ed40c95 100644 --- a/stasis/page.h +++ b/stasis/page.h @@ -48,13 +48,13 @@ terms specified in this license. * This file provides a re-entrant interface for pages that are labeled * with an LSN and a page type. * - * @ingroup LLADD_CORE pageFormats + * @ingroup PAGE_FORMATS * * $Id$ */ /** - @defgroup pageFormats Page format implementations + @defgroup PAGE_FORMATS Page layouts Stasis allows developers to define their own on-disk page formats. Currently, each page format must end with a hard-coded header @@ -90,7 +90,7 @@ terms specified in this license. and APIs. However, Stasis's record oriented page interface provides a default set of methods for page access. - @see pageRecordInterface + @see PAGE_RECORD_INTERFACE @todo Page deallocators should call stasis_page_cleanup() @todo Create variant of loadPage() that takes a page type @@ -196,8 +196,7 @@ struct Page_s { /*@}*/ /** - @defgroup pageLSNHeaderGeneric LSN and Page Types - @ingroup pageFormats + @defgroup PAGE_HEADER Default page header Most Stasis pages contain an LSN and a page type. These are used by recovery to determine whether or not to perform redo. At @@ -279,8 +278,7 @@ lsn_t stasis_page_lsn_read(const Page * page); /*@}*/ /** - @defgroup pageUtils Utility methods for page manipulation - @ingroup pageFormats + @defgroup PAGE_UTIL Byte-level page manipulation These methods make it easy to manipulate pages that use a standard Stasis header (one with an LSN and page type). @@ -291,6 +289,60 @@ lsn_t stasis_page_lsn_read(const Page * page); Methods with "_ptr_" in their names take non-const pages, and return non-const pointers. + @par Implementing new pointer arithmetic macros + + Stasis page type implementations typically do little more than + pointer arithmetic. However, implementing page types cleanly and + portably is a bit tricky. Stasis has settled upon a compromise in + this matter. Its page file formats are compatible within a single + architecture, but not across systems with varying lengths of + primitive types, or that vary in endianness. + + Over time, types that vary in length such as "int", "long", etc + will be removed from Stasis, but their usage still exists in a few + places. Once they have been removed, file compatibility problems + should be limited to endianness (though application code will still + be free to serialize objects in a non-portable manner). + + Most page implementations leverage C's pointer manipulation + semantics to lay out pages. Rather than casting pointers to + char*'s and then manually calculating byte offsets using sizeof(), + the existing page types prefer to cast pointers to appropriate + types, and then add or subtract the appropriate number of values. + + For example, instead of doing this: + + @code + // p points to an int, followed by a two bars, then the foo whose address + // we want to calculate + + int * p; + foo* f = (foo*)( ((char*)p) + sizeof(int) + 2 * sizeof(bar)) + @endcode + + the implementations would do this: + + @code + int * p; + foo * f = (foo*)( ((bar*)(p+1)) + 2 ) + @endcode + + The main disadvantage of this approach is the large number of ()'s + involved. However, it lets the compiler deal with the underlying + multiplications, and often reduces the number of casts, leading to + slightly more readable code. Take this implementation of + stasis_page_type_ptr(), for example: + + @code + int * stasis_page_type_ptr(Page *p) { + return ( (int*)stasis_page_lsn_ptr(Page *p) ) - 1; + } + @endcode + + Here, the page type is stored as an integer immediately before the + LSN pointer. Using arithmetic over char*'s would require an extra + cast to char*, and a multiplication by sizeof(int). + */ /*@{*/ static inline byte* @@ -365,14 +417,37 @@ void stasis_page_init(); void stasis_page_deinit(); /** - @defgroup pageRecordInterface Record-oriented page interface - @ingroup pageFormats + @defgroup PAGE_RECORD_INTERFACE Record interface + @ingroup PAGE_FORMATS + + Page formats define the layout of data on pages. Currently, all + pages contain a header with an LSN and a page type in it. This + information is used by recovery and the buffer manager to invoke + callbacks at appropriate times. (LSN-free pages are currently not + supported.) + + Stasis' record-oriented page interface uses the page type to determine + which page implementation should be used to access or modify + records. This API's functions begin with "stasis_record". Two + commonly used examples are stasis_read_record() and + stasis_write_record(). + + This interface is not re-entrant. Rather, page implementations + assume that their callers will latch pages using + readLock(p->rwlatch) and writeLock(p-rwlatch) before attempting to + access the page. A second latch, p->loadlatch, should not be + acquired by page manipulation code. Instead, it is used by the + buffer manager to protect against races during page eviction. + + @par Registering new page type implementations + + Page implementations are registered with Stasis by passing a + page_impl struct into registerPageType(). page_impl.page_type + should contain an integer that is unique across all page types, + while the rest of the fields contain function pointers to the page + type's implementation. + - Stasis provides a default record-oriented interface to page - implementations. By defining these methods, and registering - appropriate callbacks, page implementations allow callers to - access their data through standard Stasis methods such as Tread() - and Tset(). */ /*@{*/ static const size_t USABLE_SIZE_OF_PAGE = (PAGE_SIZE - sizeof(lsn_t) - sizeof(int)); diff --git a/stasis/transactional.h b/stasis/transactional.h index 8854fd2..cf41d2a 100644 --- a/stasis/transactional.h +++ b/stasis/transactional.h @@ -56,13 +56,59 @@ terms specified in this license. /** @mainpage Introduction to Stasis - This is the main section. -
    -
  • @ref gettingStarted
    • -
  • @ref pageFormats
    • -
  • @ref LLADD_CORE
    • -
  • @ref OPERATIONS
    • -
+ Stasis is a flexible transactional storage library. Unlike + existing systems, it provides application and server developers + with much freedom, but little guidance regarding page file layouts, + data models, and concurrency schemes. This often means that Stasis + can outperform general purpose storage solutions by orders of + magnitude, but it does require more effort on the part of its end + users. We are in the process of implementing a library of commonly + used, general-purpose transactional data structures on top of + Stasis. + + @section The Stasis data model + + Stasis does not really have a data model. While designing and + implementing Stasis, we focused on providing end users with + mechanisms, not policy. As much as possible, we have + avoiding hardcoding application-specific implmentation details such + as data formats and concurrency models. Instead, Stasis provides a + number of reusable lower-level mechanisms that make it easy for + applications to implement custom transactional storage systems. + + At the lowest level, Stasis provides transactional pages; + the buffer manager manages a set of pages and regions on disk, and + coordinates with the log and other Stasis mechanisms to provide + recovery and concurrent transactions. On top of this low level + API, we have developed record oriented interfaces that facilitate + development and interchangability of new page formats. Conformance + to these APIs is recommended, but not required. Stasis records are + simply arrays of bytes (not tuples). A Stasis recordid is simply a + record that contains a pointer to another record. + + Stasis's @ref OPERATIONS provide a set of methods that manipulate + records in a transactional, durable fashion. They are implemented + on top of the record (and sometimes page) API's, and range from low + level access methods like record reads and writes to higher level + data structure implementations, such as hash tables and log-oriented + tree indexes. Stasis' library of operations makes use of a number of + different @ref LOGGING_DISCIPLINES. Most new operations will want to + choose one of these disciplines, as many subtlties arise during the + development of new concurrent, high-performance recovery + algorithms. + + @image html "StasisDBMS.png" "Stasis' place in a conventional DBMS architecture" + + @section Tutorial + + @ref gettingStarted explains how to download and compile Stasis, + and includes a number of sample programs. + + The "Modules" section in the navigation pane contains detailed + documentation of Stasis' major components. + + @see Modules + */ /** @@ -109,11 +155,11 @@ terms specified in this license. This will fail if your system defaults to an old (pre-1.7) version of autotools. Fortunately, multiple versions of autotools may exist on the same system. Execute the following commands to - compile with version 1.8 of autotools: + compile with version 1.8 (or 1.9) of autotools: @code - $ ./reconf-1.8 + $ ./reconf-1.8 # or ./reconf-1.9 $ ./configure --quiet $ make -j4 > /dev/null $ cd test/stasis @@ -133,7 +179,7 @@ terms specified in this license. @section usage Using Stasis in your software - Synopsis: + Synopsis (examples/ex1.c): @include examples/ex1.c @@ -153,25 +199,27 @@ terms specified in this license. or naming of objects within the page file. This means that the application must maintain such information manually. - In order to facilitate this, Stasis provides the function TgetRecordType() and - guarantees that the first recordid returned by any allocation will point to - the same page and slot as the constant ROOT_RECORD. TgetRecordType - will return NULLRID if the record passed to it does not exist. + In order to facilitate this, Stasis provides the function + TrecordType() and guarantees that the first recordid returned by + any allocation will point to the same page and slot as the constant + ROOT_RECORD. TrecordType() will return UNINITIALIZED_RECORD if the + record passed to it does not exist. A second function, + TrecordSize() returns the size of a record in bytes, or -1 if the + record does not exist. - Therefore, the following code will safely initialize or reopen a data - store: + Therefore, the following code (found in examples/ex2.c) will safely + initialize or reopen a data store: @include examples/ex2.c - @see test.c for a complete, executable example of reopening an existing store. - @todo Explain how to determine the correct value of rootEntry.size in the case of a hashtable. - @see OPERATIONS for more operations that may be useful for your software. + @see OPERATIONS for other transactional primitives that may be + useful for your software. - @subsection consistency Using Stasis in multithreaded applications. + @subsection consistency Using Stasis in multithreaded applications Unless otherwise noted, Stasis' operations are re-entrant. This means that an application may call them concurrently without @@ -229,7 +277,7 @@ terms specified in this license. Stasis components can be classified as follows: - I/O utilities (file handles, OS compatibility wrappers) - - Write ahead logging component interfaces (logger.h, XXX) + - Write ahead logging component interfaces (logger.h, logger/inMemoryLog.h logger/logEntry.h logger/logger2.h logger/logHandle.h logger/logMemory.h logger/logWriter.h) - Write ahead logging component implementations (hash based buffer manager, in memory log, etc...) - Page formats and associated operations (page/slotted.c page/fixed.c) - Application visible methods (Talloc, Tset, ThashInsert, etc) @@ -353,106 +401,50 @@ terms specified in this license. Interesting files in this part of Stasis include logger2.c, bufferManager.c, and recovery2.c. - @subsection page Page types + @subsection page Custom page formats - Page types define the layout of data on pages. Currently, all - pages contain a header with an LSN and a page type in it. This - information is used by recovery and the buffer manager to invoke - callbacks at appropriate times. (LSN-free pages are currently not - supported.) + Stasis provides a default @ref PAGE_RECORD_INTERFACE to custom page + implementations. Methods that define their own log disciplines, or + otherwise need to bypass Stasis' default recovery mechanisms should + call into this API. - XXX: This section is not complete. - - @todo Discuss readRecord, writeRecord (high level page access - methods) - - @todo Explain the latching convention. (Also, explain which - latches are not to be used by page implementations, and which - latches may not be used by higher level code.) - - @par Registering new page type implementations - - Page implementations are registered with Stasis by passing a - page_impl struct into registerPageType(). page_impl.page_type - should contain an integer that is unique across all page types, - while the rest of the fields contain function pointers to the page - type's implementation. - - @par Pointer arithmetic - - Stasis page type implementations typically do little more than - pointer arithmetic. However, implementing page types cleanly and - portably is a bit tricky. Stasis has settled upon a compromise in - this matter. Its page file formats are compatible within a single - architecture, but not across systems with varying lengths of - primitive types, or that vary in endianness. - - Over time, types that vary in length such as "int", "long", etc - will be removed from Stasis, but their usage still exists in a few - places. Once they have been removed, file compatibility problems - should be limited to endianness (though application code will still - be free to serialize objects in a non-portable manner). - - Most page implementations leverage C's pointer manipulation - semantics to lay out pages. Rather than casting pointers to - char*'s and then manually calculating byte offsets using sizeof(), - the existing page types prefer to cast pointers to appropriate - types, and then add or subtract the appropriate number of values. - - For example, instead of doing this: - - @code - // p points to an int, followed by a two bars, then the foo whose address - // we want to calculate - - int * p; - foo* f = (foo*)( ((char*)p) + sizeof(int) + 2 * sizeof(bar)) - @endcode - - the implementations would do this: - - @code - int * p; - foo * f = (foo*)( ((bar*)(p+1)) + 2 ) - @endcode - - The main disadvantage of this approach is the large number of ()'s - involved. However, it lets the compiler deal with the underlying - multiplications, and often reduces the number of casts, leading to - slightly more readable code. Take this implementation of - stasis_page_type_ptr(), for example: - - @code - int * stasis_page_type_ptr(Page *p) { - return ( (int*)stasis_page_lsn_ptr(Page *p) ) - 1; - } - @endcode - - Here, the page type is stored as an integer immediately before the - LSN pointer. Using arithmetic over char*'s would require an extra - cast to char*, and a multiplication by sizeof(int). + By defining these methods and registering appropriate callbacks, + page implementations allow callers to access their data through + standard Stasis methods such as Tread() and Tset(). This module + also includes a set of utility methods to simplify the pointer + arithmetic associated with manipulating the buffer manager's copy + of pages. @par A note on storage allocation - Finally, while Stasis will correctly call appropriate functions - when it encounters a properly registered third party page type, it - currently provides few mechanisms to allocate such pages in the - first place. There are examples of three approaches in the current - code base: + Stasis currently provides a few different mechanisms that allocate + entire pages and page ranges at once. There are examples of three + approaches in the current code base: - # Implement a full-featured, general purpose allocator, like the + - Implement a full-featured, general purpose allocator, like the one in alloc.h. This is more difficult than it sounds. - # Allocate entire regions at a time, and manually initialize pages - within them. arrayList.h attempts to do this, but gets it wrong - by relying upon lazy initialization to eventually set page types - correctly. Doing so is problematic if the page was deallocated, - then reused without being reset. + - Allocate entire regions at a time, and manually initialize pages + within them. arrayList.h does this. This is the most flexible + and efficient approach, but requires extra management code if + region allocation is not a natural approach. - # Allocate a single page at a time using TallocPage(), and - TsetPage(). This is currently the most attractive route, though - TsetPage() does not call pageLoaded() when it resets page types, - which can lead to trouble. + - Allocate a single page at a time using TallocPage(), then call + page initialization methods on each page. Currently, + TallocPage() is poorly implemented and wastes one page for every + page it allocates. + + Note that before you initialize a new page you need to call + stasis_page_cleanup() to notify the page's old format that it should + free resources associated with the old version of the page. + Stasis' allocation routines guarantee that the pages they return + were freed by committed transactions (and therefore, that their + contents can be discarded). Therefore, you do not need to log the + preimage of pages returned by the allocator. + + @todo Should we change the API so that allocation routines (TpageAlloc(), TregionAlloc()) call stasis_page_cleanup() on behalf of their callers? + + @todo Optimize page, region allocation to call page initializers automatically during forward operation and redo? @see page.h, fixed.h, and slotted.h for more information on the page API's, and the implementations of two common page formats. @@ -461,8 +453,7 @@ terms specified in this license. These methods start with "T". Look at the examples above. These are the "wrapper functions" from the OSDI paper. They are - supported by operation implementations, which can be found in the - operations/ directory. + supported by @ref OPERATIONS. @section extending Implementing you own operations @@ -472,9 +463,6 @@ terms specified in this license. @see linearHashNTA.h for a more sophisticated example that makes use of Nested Top Actions. */ -/** - * @defgroup pageFormats Page format implementations - */ /** * @defgroup OPERATIONS Logical Operations * @@ -483,6 +471,53 @@ terms specified in this license. * @todo Write a brief howto to explain the implementation of new operations. * */ +/** + * @defgroup LOGGING_DISCIPLINES Logging Disciplines + * + * Stasis' log API provides a number of methods that directly + * manipulate the log. + * + * @section SNF STEAL/NO-FORCE recovery + * Stasis includes a function, Tupdate(), that + * provides traditional STEAL/NO-FORCE logging for recovery. The + * STEAL/NO-FORCE strategy allows dirty, uncommitted pages to be + * written back to disk (STEAL), which prevents long running + * transactions from exhausting RAM. It does not force write pages to + * disk at commit (NO-FORCE), and instead only forces the log. This + * prevents the hard drive head from performing unnecessary seeks + * during commit. Recovery works by "repeating history"; all actions + * are redone up to some point in time after the last successful + * transaction committed, but before the crash. Conceptually, any + * partially commited transactions are then rolled back using + * Tabort(), as they would be during normal operation. For more + * information about STEAL/NO-FORCE recovery strategies, see the ARIES + * paper (XXX cite aries properly) + * + * + * @section SF STEAL/FORCE and bulk-logged recovery + * + * Stasis supports other logging disciplines as well. In particular, + * the buffer manager allows REGIONS (XXX document region allocator) + * to be synchronously written to disk, allowing operations to make + * use of a STEAL/FORCE recovery strategy. This is attractive when a + * transaction is writing a large, contiguous region of disk, as + * STEAL/FORCE operations do not write redo information to the log. + * If the STEAL/FORCE transaction is overwriting newly allocated + * pages, it can also avoid writing undo information to the log, as + * the newly allocated pages do not contain useful data. This allows + * large objects to be written with no tangible logging overhead, and + * has been implemented by a number of commercial systems. It is used + * by the Stasis' Rose indexes. (XXX cite LSM trees, etc.) + * + * @section LSNFREE LSN-Free pages + * + * Stasis' third (and most exotic) logging strategy makes use of + * LSN-free pages. By constraining the behavior of redo and undo log + * entries, we can entirely avoid storing Stasis metadata on pages. + * This logging discipline is under development. + * + */ + /** * @file