ydb/library/cpp/containers/comptrie

Compact trie

The comptrie library is a fast and very tightly packed implementation of a prefix tree (Sedgewick's T-trie, that is a ternary tree, see https://www.cs.princeton.edu/~rs/strings/paper.pdf, https://www.cs.upc.edu/~ps/downloads/tst/tst.html). It contains tools for creating, optimizing, and serializing trees, accessing by key, and performing various searches. Because it is template-based and performance-oriented, a significant part of the library consists of inline functions, so if you don't need all the features of the library, consider including a more specific header file instead of the top-level comptrie.h file.

Description of the data structure

A prefix tree is an implementation of the map data structure for cases when keys are sequences of characters. The nodes on this tree contain characters and values. The key that corresponds to a value is a sequence of all the characters on nodes along the path from the root to the node with this value. It follows that a tree node can have as many children as there are different characters, which is quite a lot. For compact storage and quick access, the children are ordered as a binary search tree, which should be balanced if possible (characters have a defined order that must be preserved). Thus, our tree is ternary: each node has a reference to a subtree of all children and two references to subtrees of siblings. One of these subtrees contains the younger siblings, and the other contains the elder siblings.

The library implements tree optimization by merging identical subtrees, which means the tree becomes a DAG (Directed Acyclic Graph – an oriented graph without oriented cycles).

The main class TCompactTrie is defined in comptrie_trie.h and is templatized:

• The first parameter of the template is the character type. It should be an integer type, which means that arithmetical operations must be defined for it.
• The second parameter of the template is the value type.
• The third parameter is the packer class, which packs values in order to quickly and compactly serialize the value type to a continuous memory buffer, deserialize it back, and quickly determine its size using the pointer to the beginning of this memory buffer. Good packers have already been written for most types, and they are available in library/cpp/packers. For more information, please refer to the documentation for these packers.

The set.h file defines a modification for cases when keys must be stored without values.

When a tree is built from scratch, the value corresponding to an empty key is assigned to a single-character key '\0'. So in a tree with the 'char' character type, the empty key and the '\0' key are bound together. For a subtree received from a call to FindTails, this restriction no longer exists.

Creating trees

Building a tree from a list of key-value pairs is performed by the TCompactTrieBuilder class described in the comptrie_builder.h file.

This class allows you to add words to a tree one at a time, merge a complete subtree, and also use an unfinished tree as a map.

An important optimization is the prefix-grouped mode when you need to add keys in a certain order (for details, see the comments in the header file). The resulting tree is compactly packed while keys are being added, and the memory consumption is approximately the same as for the completed tree. For the default mode, compact stacking is turned on at the very end, and the data consumes quite a lot of memory up until that point.

Optimizing trees

After a tree is created, there are two optimizing operations that can be applied:

• Minimization to a DAG by merging equal subtrees.
• Fast memory layout. The functions that implement these operations are declared in the comptrie_builder.h file. The first optimization is implemented by the CompactTrieMinimize function, and the second is implemented by CompactTrieMakeFastLayout. You can perform both at once by calling the CompactTrieMinimizeAndMakeFastLayout function.

Minimization

Minimization to a DAG requires quite a lot of time and a large amount of memory to store an array of subtrees, but it can reduce the size of the tree several times over (an example is a language model that has many low-frequency phrases with repeated last words and frequency counts). However, if you know in advance that there are no duplicate values in the tree, you don't need to waste time on it, since the minimization won't have any effect on the tree.

Fast memory layout

The second optimization function results in fewer cache misses, but it causes the tree to grow in size. Our experience has shown a 5% gain in speed for some tries. The algorithm consumes about three times more memory than the amount required for the source tree. So if the machine has enough memory to assemble a tree, it does not neccessarily mean that it has enough memory to run the algorithm. To learn about the theory behind this algorithm, read the comments before the declaration of the CompactTrieMinimize function.

Serializing trees

The tree resides in memory as a sequence of nodes. Links to other nodes are always counted relative to the position of the current node. This allows you to save a tree to disk as it is and then re-load it using mmap(). The TCompactTrie class has the TBlob constructor for reading a tree from disk. The TCompactTrieBuilder class has Save/SaveToFile methods for writing a built tree to a stream or a file.

Accessing trees

As a rule, all methods that accept a key as input have two variants:

• One takes the key in the format: pointer to the beginning of the key, length.
• The other takes a high-level type like TStringBuf.

You can get a value for a key in the tree – TCompactTrie::Find returns false if there is no key, and TCompactTrie::Get throws an exception. You can use FindPrefix methods to find the longest key prefix in a tree and get the corresponding value for it. You can also use a single FindPhrases request to get values for all the beginnings of a phrase with a given word delimiter.

An important operation that distinguishes a tree from a simple map is implemented in the FindTails method, which allows you to obtain a subtree consisting of all possible extensions of the given prefix.

Iterators for trees

First of all, there is a typical map iterator over all key-value pairs called TConstIterator. A tree has three methods that return it: Begin, End, and UpperBound. The latter takes a key as input and returns an iterator to the smallest key that is not smaller than the input key.

The rest of the iterators are not so widely used, and thus are located in separate files.

TPrefixIterator is defined in the prefix_iterator.h file. It allows iterations over all the prefixes of this key available in the tree.

TSearchIterator is defined in the search_iterator.h file. It allows you to enter a key in a tree one character at a time and see where it ends up. The following character can be selected depending on the current result. You can also copy the iterator and proceed on two different paths. You can actually achieve the same result with repeated use of the FindTails method, but the authors of this iterator claim that they obtained a performance gain with it.

Appendix. Memory implementation details

If you are not going to modify the library, then you do not need to read further.

First, if the character type has a size larger than 1 byte, then all keys that use these characters are converted to byte strings in the big-endian way. This means that character bytes are written in a string from the most significant to the least significant from left to right. Thus it is reduced to the case when the character in use is 'char'.

The tree resides in memory as a series of consecutive nodes. The nodes can have different sizes, so the only way to identify the boundaries of nodes is by passing the entire tree.

Node structure

The structure of a node, as can be understood from thoughtfully reading the LeapByte function in Comptrie_impl.h, is the following:

• The first byte is for service flags.
• The second byte is a character (unless it is the ε-link type of node described below, which has from 1 to 7 bytes of offset distance from the beginning of this node to the content node, and nothing else).

Thus, the size of any node is at least 2 bytes. All other elements of a node are optional. Next there is from 0 to 7 bytes of the packed offset from the beginning of this node to the beginning of the root node of a subtree with the younger siblings. It is followed by 0 to 7 bytes of the packed offset from the beginning of this node to the beginning of the root node of a subtree with the elder siblings. Next comes the packed value in this node. Its size is not limited, but you may recall that the packer allows you to quickly determine this size using a pointer to the beginning of the packed value. Then, if the service flags indicate that the tree has children, there is a root node of the subtree of children.

The packed offset is restricted to 7 bytes, and this gives us a limit on the largest possible size of a tree. You need to study the packer code to understand the exact limit.

All packed offsets are nonnegative, meaning that roots of subtrees with siblings and the node pointed to by the ε-link must be located strictly to the right of the current node in memory. This does not allow placement of finite state machines with oriented cycles in the comptrie. But it does allow you to effectively stack the comptrie from right to left.

Service flags

The byte of service flags contains (as shown by the constants at the beginning of the comptrie_impl.h file):

• 1 bit of MT_NEXT, indicating whether this node has children.
• 1 bit of MT_FINAL, indicating if there is a value in this node.
• 3 bits of MT_SIZEMASK, indicating the size of the packed offset to a subtree with elder siblings.
• 3 bits of MT_SIZEMASK << MT_LEFTSHIFT, indicating the size of the packed offset to a subtree with younger siblings. If one of these subtrees is not present, then the size of the corresponding packed offset is 0, and vice versa.

ε-links

These nodes only occur if we optimized a tree into a DAG and got two nodes with merged subtrees of children. Since the offset to the subtree of children can't be specified and the root of this subtree should lie just after the value, we have to add a node of the ε-link type, which contains the offset to the root subtree of children and nothing more. This applies to all nodes that have equal subtrees of children, except the rightmost node. The size of this offset is set in 3 bits of MT_SIZEMASK flags for a node.

As the implementation of the IsEpsilonLink function in comptrie_impl.h demonstrates, the ε-link differs from other nodes in that it does not have the MT_NEXT flag or the MT_FINAL flag, so it can always be identified by the flags. Of course, the best programming practice is to call the function itself instead of examining the flags.

Note that the ε-link flags do not use the MT_SIZEMASK << MT_LEFTSHIFT` bits, which allows us to start using ε-links for some other purpose.

Pattern Searcher

This is an implementation of Aho-Corasick algorithm on compact trie structure. In order to create a pattern searcher one must fill a TCompactPatternSearcherBuilder with patterns and call SaveAsPatternSearcher or SaveToFileAsPatternSearcher. Then TCompactPatternSearcher must be created from the builder output.

Implementation details

Aho-Corasick algorithm stores a suffix link in each node. A suffix link of a node is the offset (relative to this node) of the largest suffix of a string this node represents which is present in a trie. Current implementation also stores a shortcut link to the largest suffix for which the corresponding node in a trie is a final node. These two links are stored as NCompactTrie::TSuffixLink structure of two 64-bit integers. In a trie layout these links are stored for each node right after the two bytes containing service flags and a symbol.