diff options
author | Dana Robinson <43805+derobins@users.noreply.github.com> | 2022-03-06 23:33:00 (GMT) |
---|---|---|
committer | GitHub <noreply@github.com> | 2022-03-06 23:33:00 (GMT) |
commit | 78375882485a99a81caa933928ed08d7a38ef88b (patch) | |
tree | f18c41d7794d546b6562dd2aa36932c78f00a16a /doxygen/dox | |
parent | 7e176db164d1a6f944e703c612c4952b15d333f4 (diff) | |
download | hdf5-78375882485a99a81caa933928ed08d7a38ef88b.zip hdf5-78375882485a99a81caa933928ed08d7a38ef88b.tar.gz hdf5-78375882485a99a81caa933928ed08d7a38ef88b.tar.bz2 |
VFD SWMR: normalization with develop (#1472)
Much normalization with develop. Still needs tools changes wrt VFD plugins.
Diffstat (limited to 'doxygen/dox')
-rw-r--r-- | doxygen/dox/About.dox | 2 | ||||
-rw-r--r-- | doxygen/dox/Glossary.dox | 565 | ||||
-rw-r--r-- | doxygen/dox/H5AC_cache_config_t.dox | 8 | ||||
-rw-r--r-- | doxygen/dox/Overview.dox | 38 |
4 files changed, 595 insertions, 18 deletions
diff --git a/doxygen/dox/About.dox b/doxygen/dox/About.dox index 9000a78..b03ebf6 100644 --- a/doxygen/dox/About.dox +++ b/doxygen/dox/About.dox @@ -124,6 +124,4 @@ version. Talk to your friendly IT-team if you need write access, or you need someone to push an updated version for you! -\todo Make the publication a GitHub action! - */ diff --git a/doxygen/dox/Glossary.dox b/doxygen/dox/Glossary.dox new file mode 100644 index 0000000..9ccd27d --- /dev/null +++ b/doxygen/dox/Glossary.dox @@ -0,0 +1,565 @@ +/** \page GLS Glossary + +\section GLS_A A + +<DL> + <DT>Array datatype</DT> + <DD>A family of HDF5 datatypes whose elements are arrays of a fixed rank (≤ + 32) and fixed finite extent. All array elements must be of the same HDF5 + datatype.</DD> +</DL> + +<DL> + <DT>Array variable</DT> + <DD><P>A variable that can store (logically) dense, rectilinear, multidimensional + arrays of elements of a given HDF5 datatype.</P> + <P>The combination of array rank (dimensionality) and extent is called an + array variable's shape. This includes the degenerate array shapes of a + singleton (scalar) and the empty array (null).</P> + <P>The array element datatype is sometimes referred to as the array + variable's type, which is not entirely accurate because the array variable's + type is 'array of element type' rather than 'element type'.</P> + <P>In HDF5, there are two kinds of array variables, attributes and datasets, + and the distinction is functional (i.e., how they can be used) rather than + conceptual. Attributes are commonly used for descriptive "light-weight" + HDF5 object metadata while datasets are HDF5 objects used to store + "heavy-weight" problem-sized data.</P> + </DD> +</DL> + +<DL> + <DT>Attribute</DT> + <DD><P>A named array variable that is associated with an HDF5 object, its + owner or attributee, and used to represent application domain-specific + metadata of the object. Intuitively, the set of an object's attributes can + be thought of as its key-value pair collection. Attribute names (keys) can + be arbitrary Unicode strings, but must be unique per object, i.e., an + object can have at most one attribute with a given name.</P> + <P>A scalar attribute is an attribute backed by a singleton array + variable. A null attribute is attribute backed by an empty array + variable.</P> +</DD> +</DL> + +\section GLS_B B + +<DL> + <DT>Bitfield datatype</DT> + <DD>A family of HDF5 datatypes whose elements are fixed-width bit fields.</DD> +</DL> + +\section GLS_C C + +<DL> + <DT>Chunked layout</DT> + <DD> + <P>A dataset storage layout where the dataset elements are partitioned into + fixed-size multidimensional chunks or tiles. Chunked layout is mandatory + for datasets with one or more dimensions of indefinite (infinite) extent + or where compression or other filters are applied to the dataset elements.</P> + <P>Chunked layout may improve I/O performance for certain access patterns.</P> +</DD> +</DL> + +<DL> + <DT>Committed datatype</DT> + <DD>An immutable kind of HDF5 object that is used to store an HDF5 datatype + definition, which can be referenced by multiple array variables. When linked + to an HDF5 group, a committed datatype can be located by an HDF5 path name, + and is sometimes called a named datatype.</DD> +</DL> + +<DL> + <DT>Compact layout</DT> + <DD></DD> +</DL> + +<DL> + <DT>Compound datatype</DT> + <DD> + <P>A family of HDF5 datatypes whose elements are records with named fields + of other HDF5 datatypes. Currently, on ASCII field names are supported.</P> + <P>Similar to a <CODE>struct</CODE> in C or a <CODE>COMMON</CODE> block in + Fortran.</P> +</DD> +</DL> + +<DL> + <DT>Contiguous layout</DT> + <DD>A dataset storage layout where the dataset elements are physically stored + in an HDF5 file as a contiguous block of bytes.</DD> +</DL> + +\section GLS_D D + +<DL> + <DT>Dataset</DT> + <DD> + <P>A kind of HDF5 object, a linked array variable. which can be located in + an HDF5 file through a path name. Datasets are commonly used to store + "heavy-weight" problem-sized data.</P> + <P>The HDF5 library offers a lot of features aimed at optimized dataset + access and storage, including compression and partial I/O.</P> +</DD> +</DL> + +<DL> + <DT>Dataspace</DT> + <DD>The shape of an array variable. With the exception of degenerate cases + (empty set, singleton), this is a rectilinear lattice or grid of a certain + rank (dimensionality) and extent.</DD> +</DL> + +<DL> + <DT>Datatype</DT> + <DD> + <P>An HDF5 datatype consists of an abstract data type (a set of elements) + and a bit-level representation of these elements in storage such as an HDF5 + file or memory.</P> + <P>The HDF5 library comes with a large set of predefined datatypes and + offers mechanisms for creating user-defined datatypes.</P> + <P>The ten major families or classes of HDF5 datatypes are:</P> + <UL> + <LI>Integer datatypes</LI> + <LI>Floating-point number datatypes</LI> + <LI>String datatypes</LI> + <LI>Bitfield datatypes</LI> + <LI>Opaque datatypes</LI> + <LI>Compound datatypes</LI> + <LI>Reference datatypes</LI> + <LI>Enumerated datatypes</LI> + <LI>Variable-length sequence datatypes</LI> + <LI>Array datatypes</LI> + </UL> +</DD> +</DL> + +\section GLS_E E + +<DL> + <DT>Enumeration datatype</DT> + <DD>A family of HDF5 datatypes whose elements represent named integer values + called members or enumerators. Currently, only ASCII names are supported.</DD> +</DL> + +<DL> + <DT>External layout</DT> + <DD>A form of contiguous layout where a dataset's elements are physically + stored in unformatted binary files outside the HDF5 file.</DD> +</DL> + +<DL> + <DT>External link</DT> + <DD>An HDF5 link whose destination is specified as a pair of an HDF5 file name +and an HDF5 path name in that file.</DD> +</DL> + +\section GLS_F F + +<DL> + <DT>Field</DT> + <DD>See compound datatype.</DD> +</DL> + +<DL> + <DT>File</DT> + <DD> + <OL> + <LI>A byte stream (in a storage context such as a file system or in + memory) formatted according to the HDF5 File Format Specification.</LI> + <LI>A (logical) container for HDF5 objects.</LI> + </OL> + </DD> +</DL> + +<DL> + <DT>File format</DT> + <DD></DD> +</DL> + +<DL> + <DT>Fill value</DT> + <DD></DD> +</DL> + +<DL> + <DT>Filter</DT> + <DD></DD> +</DL> + +\section GLS_G G + +<DL> + <DT>Group</DT> + <DD> + <P>A kind of HDF5 object that stores a collection of HDF5 links. Each HDF5 + file contains at least one group, it's root group.</P> + <P>Among the destinations of an HDF5 group's links may be other HDF5 groups + (including the group itself!). This ability is sometimes referred to as the + closure property of groups. It is the basis for creating hierarchical or + more general graph-like structures.</P> +</DD> +</DL> + +\section GLS_H H + +<DL> + <DT>Hard link</DT> + <DD>An HDF5 link whose destination is specified (internally) as the address of + an HDF5 object in the same HDF5 file.</DD> +</DL> + +<DL> + <DT>Hierarchy</DT> + <DD>See group.</DD> +</DL> + +<DL> + <DT>Hyperslab</DT> + <DD> + <P>A regular multidimensional pattern described by four vectors whose length + equals the rank of the pattern.</P> + <OL> + <LI><CODE>start</CODE> - the offset where the first block of the hyperslab begins</LI> + <LI><CODE>stride</CODE> - the offset between pattern blocks</LI> + <LI><CODE>count</CODE> - the number of blocks</LI> + <LI><CODE>block</CODE> - the extent of an individual pattern block</LI> + </OL> + <P>For example, the black squares on a (two-dimensional) chessboard with + origin at <CODE>(0,0)</CODE> can be represented as the union of two + hyperslabs representing the even <CODE>(0,2,4,6)</CODE> and + odd <CODE>(1,3,5,7)</CODE> rows, respectively.</P> + <IMG SRC="https://upload.wikimedia.org/wikipedia/commons/thumb/d/d7/Chessboard480.svg/176px-Chessboard480.svg.png"/> + <P>The hyperslab parameters for the even rows are: <CODE>start (0,0)</CODE>, + <CODE>stride (2,2)</CODE>, <CODE>count (4,4)</CODE>, <CODE>block + (1,1)</CODE>. Likewise the parameters for the odd rows are: <CODE>start + (1,1)</CODE>, <CODE>stride (2,2)</CODE>, <CODE>count + (4,4)</CODE>, <CODE>block (1,1)</CODE>.</P> +</DD> +</DL> + +\section GLS_I I + +<DL> + <DT>Identifier</DT> + <DD>An opaque, transient handle used by the HDF5 library to manipulate + in-memory representations of HDF5 items.</DD> +</DL> + +\section GLS_L L + +<DL> + <DT>Library</DT> + <DD></DD> +</DL> + +<DL> + <DT>Link</DT> + <DD> + <P>A named, uni-directional association between a source and a + destination. In HDF5, the source is always the HDF5 group that hosts the + link in its link collection.</P> + <P>There are several ways to specify a link's destination:</P> + <UL> + <LI>The address of an HDF5 object in the same HDF5 file; so-called hard + link.</LI> + <LI>A path name in the same or a different file; so-called soft or + external link.</LI> + <LI>User-defined</LI> + </UL> + <P>A link name can be any Unicode string that does not contain slashes + (<CODE>"/"</CODE>) or consists of a single dot character + (<CODE>"."</CODE>). A link name must be unique in a group's link + collection.</P> + </DD> +</DL> + +\section GLS_M M + +<DL> + <DT>Metadata</DT> + <DD>Data that in a given context has a descriptive or documentation function + for other data. Typically, the metadata is small compared to the data it + describes.</DD> +</DL> + +<DL> + <DT>Member</DT> + <DD> + <P>A link destination is sometimes referred to as a member of the link's + source (group). This way of speaking invites confusion: A destination (e.g., + object) can be the destination of multiple links in the same (!) or + different groups. It would then be a "member" of a given group with + multiplicity greater than one and be a member of multiple groups.</P> + <P> It is the link that is a member of the group's link collection and not + the link destination.</P> + </DD> +</DL> + +\section GLS_N N + +<DL> + <DT>Name</DT> + <DD> + <P>A Unicode string that depending on the item it names might be subject to + certain character restrictions, such as ASCII-encoded only. In HDF5, the + user might encounter the following names:</P> + <UL> + <LI>A link name</LI> + <LI>A path name</LI> + <LI>An attribute name</LI> + <LI>A field name (compound datatypes)</LI> + <LI>A constant name (enumeration datatypes)</LI> + <LI>A tag name (opaque datatypes)</LI> + <LI>A file name</LI> + </UL> + </DD> +</DL> + + +<DL> + <DT>Named datatype</DT> + <DD>See committed datatype.</DD> +</DL> + +<DL> + <DT>Null dataspace</DT> + <DD>A shape which represents the empty set. Array variables with this shape + cannot store any values.</DD> +</DL> + +\section GLS_O O + +<DL> + <DT>Object</DT> + <DD>An HDF5 group, dataset or named datatype; an HDF5 item that can be linked + to zero or more groups and decorated with zero or more HDF5 attributes.</DD> +</DL> + +<DL> + <DT>Object reference</DT> + <DD> + <OL> + <LI>A datatype for representing references to objects in a file.</LI> + <LI>A value of the object reference datatype.</LI> + </OL> + </DD> +</DL> + +<DL> + <DT>Opaque datatype</DT> + <DD>A family of HDF5 datatypes whose elements are byte sequences of a given + fixed length. An opaque datatype can be tagged with a sequence of up to 256 + ASCII characters, e.g., MIME code.</DD> +</DL> + +\section GLS_P P + +<DL> + <DT>Path name</DT> + <DD>A Unicode string that is the concatenation of link names separated by + slashes (<CODE>'/'</CODE>). In HDF5, path names are used to locate and refer + to HDF5 objects.</DD> +</DL> + +<DL> + <DT>Plugin</DT> + <DD>An HDF5 library feature or capability that can be added dynamically at + application run time rather than library compilation time. Plugins are + usually implemented as shared libraries, and their discovery and loading + behavior can be controlled programmatically or through environment + variables. + </DD> +</DL> + +<DL> + <DT>Point selection</DT> + <DD>A dataspace selection that consists of a set of points (coordinates) in + the same dataspace.</DD> +</DL> + +<DL> + <DT>Property list</DT> + <DD> + <P>An HDF5 API construct, a means of customizing the behavior of the HDF5 + library when creating, accessing or modifying HDF5 items.</P> + <P>While the default property settings are sufficient in many cases, certain + HDF5 features, such as compression, can be reasonably controlled only by the + user who has to provide the desired settings via property lists.</P> +</DD> +</DL> + +\section GLS_R R + +<DL> + <DT>Rank</DT> + <DD>The number of dimensions of a non-null dataspace.</DD> +</DL> + +<DL> + <DT>Reference</DT> + <DD> + <OL> + <LI>An HDF5 object reference</LI> + <LI>An HDF5 dataset region reference</LI> + </OL> + </DD> +</DL> + +<DL> + <DT>Reference datatype</DT> + <DD> + <OL> + <LI>An HDF5 datatype whose elements represent references to HDF5 + objects.</LI> + <LI>An HDF5 datatype whose elements represent references to regions of an + HDF5 dataset.</LI> + </OL> + </DD> +</DL> + +<DL> + <DT>Region reference</DT> + <DD>See dataset region reference.</DD> +</DL> + +<DL> + <DT>Root group</DT> + <DD> + <P>An HDF5 group that is present in all HDF5 files and that acts as the + entry or base point for all other data stored in an HDF5 file.</P> + <P>The root group is "the mother of all objects" in an HDF5 file in the + sense that all objects (and their attributes) can be discovered, + beginning at the root group, by combinations of the following + operations:</P> + <UL> + <LI>Link traversal</LI> + <LI>De-referencing of object references</LI> + </UL> + <P>This discovery is portable and robust with respect to file-internal + storage reorganization.</P> +</DD> +</DL> + +\section GLS_S S + +<DL> + <DT>Scalar dataspace</DT> + <DD>A kind of HDF5 dataspace that has the shape of a singleton, i.e., a set + containing a single element. Array variables with this shape store exactly one + element.</DD> +</DL> + +<DL> + <DT>Selection</DT> + <DD> + <OL> + <LI>A subset of points of an HDF5 dataspace. The subset might be a point + selection or a combination (union, intersection, etc.) of hyperslabs.</LI> + <LI>A subset of dataset elements associated with a dataspace selection as + described under 1.</LI> + </OL> + </DD> +</DL> + +<DL> + <DT>Serialization</DT> + <DD> + <OL> + <LI>The flattening of an N-dimensional array into a 1-dimensional + array.</LI> + <LI>The encoding of a complex data item as a linear byte stream.</LI> + </OL> + </DD> +</DL> + +<DL> + <DT>Soft link</DT> + <DD>A kind of HDF5 link in which the link destination is specified as an HDF5 + path name. The path name may or may not refer to an actual object.</DD> +</DL> + +<DL> + <DT>Storage layout</DT> + <DD>The storage arrangement for dataset elements, links in a group's link + collection, or attributes in an object's attribute collection.</DD> +</DL> + +<DL> + <DT>String datatype</DT> + <DD></DD> +</DL> + +<DL> + <DT>Super block</DT> + <DD>An HDF5 file format primitive; a block of data which contains information + required to access HDF5 files in a portable manner on multiple platforms. The + super block contains information such as version numbers, the size of offsets + and lengths, and the location of the root group.</DD> +</DL> + +<DL> + <DT>SWMR</DT> + <DD>Single Writer Multiple Reader, a file access mode in which a single + process is permitted to write data to an HDF5 file while other processes are + permitted to read data from the same file without the need of inter-process + communication or synchronization.</DD> +</DL> + +<DL> + <DT>Symbolic link</DT> + <DD>An external link or a soft link.</DD> +</DL> + +\section GLS_U U + +<DL> + <DT>User block</DT> + <DD>An HDF5 file format primitive that allows one to set aside a fixed-size + (at least 512 bytes or any power of 2 thereafter) contiguous range of bytes at + the beginning of an HDF5 file for application purposes which will be + skipped/ignored by the HDF5 library.</DD> +</DL> + +<DL> + <DT>UTF-8</DT> + <DD> + <P>A variable-length (1-4 bytes per code point) encoding of the Unicode set + of code points. This is the encoding supported by HDF5 to represent Unicode + strings.</P> + <P>The ASCII encoding is a proper subset of UTF-8.</P> +</DD> +</DL> + +\section GLS_V V + +<DL> + <DT>Variable-length (sequence) datatype</DT> + <DD>A family of HDF5 datatypes whose elements are variable-length sequences of + a given datatype.</DD> +</DL> + +<DL> + <DT>Virtual Dataset (VDS)</DT> + <DD>An HDF5 dataset with virtual storage layout. A dataset whose elements are + partially or entirely stored physically in other datasets.</DD> +</DL> + +<DL> + <DT>Virtual File Driver (VFD)</DT> + <DD></DD> +</DL> + + +<DL> + <DT>Virtual layout</DT> + <DD></DD> +</DL> + + +<DL> + <DT>Virtual Object Layer (VOL)</DT> + <DD></DD> +</DL> + +*/ diff --git a/doxygen/dox/H5AC_cache_config_t.dox b/doxygen/dox/H5AC_cache_config_t.dox index 9b9862b..2584aac 100644 --- a/doxygen/dox/H5AC_cache_config_t.dox +++ b/doxygen/dox/H5AC_cache_config_t.dox @@ -26,7 +26,7 @@ * * \Emph{*** DEPRECATED ***} Use \Code{H5Fstart/stop} logging functions instead * - * The trace file is a debuging feature that allow the capture of + * The trace file is a debugging feature that allow the capture of * top level metadata cache requests for purposes of debugging and/or * optimization. This field should normally be set to \c FALSE, as * trace file collection imposes considerable overhead. @@ -82,7 +82,7 @@ * H5C_incr__off ) && ( decr_mode == H5C_decr__off )}). There * is no logical reason why this should be so, but it simplifies * implementation and testing, and I can't think of any reason - * why it would be desireable. If you can think of one, I'll + * why it would be desirable. If you can think of one, I'll * revisit the issue. (JM) * \endparblock * @@ -383,7 +383,7 @@ * to disk.\n * When the sync point is reached (or when there is a user generated * flush), process zero flushes sufficient entries to bring it into - * complience with its min clean size (or flushes all dirty entries in + * compliance with its min clean size (or flushes all dirty entries in * the case of a user generated flush), broad casts the list of * entries just cleaned to all the other processes, and then exits * the sync point.\n @@ -412,4 +412,4 @@ * received from process zero.\n * To avoid possible messages from the past/future, all caches must * wait until all caches are done before leaving the sync point. - */
\ No newline at end of file + */ diff --git a/doxygen/dox/Overview.dox b/doxygen/dox/Overview.dox index 754722e..040769c 100644 --- a/doxygen/dox/Overview.dox +++ b/doxygen/dox/Overview.dox @@ -1,14 +1,12 @@ /** \mainpage notitle -This is the documentation set for HDF5. You can -<a href="hdf5-doc.tgz">download</a> it as a tgz archive for offline reading. - -This is the documention set for HDF5 in terms of specifications and software -developed and maintained by <a href="https://www.hdfgroup.org/">The HDF -Group</a>. It is impractical to document the entire HDF5 ecosystem in one place, -and you should also consult the documentation sets of the many outstanding -community projects. +This is the documentation set for HDF5. +It includes specifications and documentation +of software and tools developed and maintained by +<a href="https://www.hdfgroup.org/">The HDF Group</a>. It is impractical to document +the entire HDF5 ecosystem in one place, and you should also consult the documentation +sets of the many outstanding community projects. For a first contact with HDF5, the best place is to have a look at the \link GettingStarted getting started \endlink page that shows you how to write and @@ -19,12 +17,28 @@ technical documentation consists to varying degrees of information related to <em>tasks</em>, <em>concepts</em>, or <em>reference</em> material. As its title suggests, the \link RM Reference Manual \endlink is 100% reference material, while the \link Cookbook \endlink is focused on tasks. The different guide-type -documents cover a mix of tasks, concepts, and reference, to help a certain +documents cover a mix of tasks, concepts, and reference, to help a specific <em>audience</em> succeed. -Finally, do not miss the search engine (top right-hand corner)! If you are -looking for a specific function, it'll take you there directly. If unsure, it'll -give you an idea of what's on offer and a few promising leads. +\par Versions + Version-specific documentation (see the version in the title area) can be found + here: + - HDF5 <code>develop</code> branch (this site) + - <a href="https://docs.hdfgroup.org/hdf5/v1_12/index.html">HDF5 1.12.x</a> + - <a href="https://docs.hdfgroup.org/hdf5/v1_10/index.html">HDF5 1.10.x</a> + - <a href="https://docs.hdfgroup.org/hdf5/v1_8/index.html">HDF5 1.8.x</a> + +\par Search + If you are looking for a specific function, constant, type, etc., use the + search box in the top right-hand corner!\n Otherwise, check out the + \link FTS full-text search\endlink. + +\par Offline reading + You can <a href="hdf5-doc.tgz">download</a> it as a tgz archive for offline reading. + +\par History + A snapshot (~April 2017) of the pre-Doxygen HDF5 documentation can be found + <a href="https://docs.hdfgroup.org/archive/support/HDF5/doc/index.html">here</a>. \par ToDo List There is plenty of <a href="./todo.html">unfinished business</a>. |