学习 LLVM(16) FoldingSet

文件位于 llvm/include/llvm/[[ADT]]/FoldingSet.h

fold: 折叠。

[[FoldingSet]] 对于昂贵建立或多态的对象是一个好的集合类。参见：http://llvm.org/docs/ProgrammersManual.html#dss_FoldingSet

== 定义的类或方法 ==
* FoldingSetImpl -- 实现 FoldingSet 的功能。主要结构是桶的数组。
* FoldingSetTrait -- 定义如何记录(profile)指定类型的对象。
* DefaultFoldingSetTrait -- FoldingSetTrait 的缺省实现。
* ContextualFoldingSetTrait --
* DefaultContextualFoldingSetTrait -- 上面类的缺省实现。
* FoldingSetNodeIDRef -- 描述到 FoldingSetNodeID 的引用。
* FoldingSetNodeID -- 收集一个节点的全部惟一数据位。
* FoldingSetNode
* FoldingSet
* ContextualFoldingSet
* FoldingSetIteratorImpl -- FoldingSetIterator 公共部分。
* FoldingSetIterator
* FoldingSetBucketIteratorImpl -- FoldingSetBucketIterator 公共部分。
* FoldingSetBucketIterator
* FoldingSetNodeWrapper
* FastFoldingSetNode -- FoldingSetNode 的子类，其保存 FoldingSetNodeID 信息而不是每次都调用 node 重复计算。即空间换时间。
* FoldingSetTrait<T*> -- FoldingSetTrait 对指针的特化。

== 模板类 DefaultFoldingSetTrait ==
DefaultFoldingSetTrait - 提供 FoldingSetTrait 的缺省实现。类概要：
<syntaxhighlight lang="cpp">
template<T> struct DefaultFoldingSetTrait {
  Profile(T &X, FoldingSetNodeID &ID); // 要求 X 提供方法 X.Profile(ID) 完成此 Profile() 请求。
  Equals(X, ID) // 测试是否 X.profile == ID。缺省实现也许不够效率，派生类能够 override 此实现。
  ComputeHash(X) // 计算 X 的哈希值。派生类能够提供更优化的实现。
}
</syntaxhighlight>

也即，这个 Trait 类提供 T 的 Profile,Equals,ComputeHash 的缺省实现。为实现，缺省要求 T 提供 Profile 方法，Equals,ComputeHash 缺省使用 Profile 进行计算。

== FoldingSetTrait ==
该模板类 FoldingSetTrait<T> 从 DefaultFoldingSetTrait<T> 继承，本身没有任何额外的方法和数据。咱们认为这是为了留给 T 作模板特化用的。配合 FoldingSetNodeWrapper 类，咱们能够给对象添加原来并未设计，而 FoldingSet 所需的 Profile 方法。

== 模板类 DefaultContextualFoldingSetTrait ==
* contextual: 环境的，上下文的，先后有关的。

相似于 DefaultFoldingSetTrait，但提供 ContextualFoldingSetTrait 的缺省实现。
<syntaxhighlight lang="cpp">
template<T, CTXT> // CTXT: 环境，上下文
struct DefaultContextualFoldingSetTrait {
  Profile(T &X, FoldingSetNodeID &ID, CTXT) // 要求 X 实现 X.Profile(ID,CTXT)
  Equals(...,CTXT); // 带有 CTXT 的 Equals()
  ComputeHash(...,CTXT) // 带有 CTXT 的 ComputeHash()
};
</syntaxhighlight>

这个类与 DefaultFoldingSetTrait 的区别在于多了一个 CTXT 模板参数，并在全部函数中有 CTXT 类型的参数。(但不是 CTXT& 类型的参数，奇怪吗？)

== 模板类 ContextualFoldingSetTrait ==
相似于 FoldingSetTrait，但以 DefaultContextualFoldingSetTrait 为基本实现。留给类型 T, CTXT 作特化用。

== 类 FoldingSetNodeID ==
FoldingSetNodeID - 这个类用于收集一个节点(node)的全部惟一数据位（作为惟一 Key）。当全部数据都收集到以后，为此节点产生一个 hash 值。

<syntaxhighlight lang="cpp">
class FoldingSetNodeID {
  SmallVector<unsigned, 32> Bits;  // 缺省使用 SmallVector 来存放惟一数据。

  this() // 缺省构造，和带参数构造。参见 FoldingSetNodeIDRef
  AddXXX(T) // 支持多种 T 类型的 AddXXX() 方法。包括指针，整数，字符串等。
  ComputeHash() // 计算此实例的 hash 值，用于在 FoldingSet 中查找节点。
  operator==()  // 比较。
  Intern()  // 参见 FoldingSetNodeIDRef 的说明。
}
</syntaxhighlight>

当前我推测，这个类用于帮助收集指定对象 obj 的可区分于别的 obj 的数据，也便可以认为是产生 obj 的惟一 Key (Primary Key, Unique Key)。各类 AddXXX() 方法加入的数据要足以区分这个 obj。下面研究典型几个的 Add() 函数：
* AddPointer(const void *Ptr) -- Ptr 当作整数 append 到 Bits 末尾。
* AddInteger(unsigned I) -- 将 I append 到 Bits 末尾。
* AddInteger(integer) -- 相似，根据 integer 类型大小，加入的 1~2 次 unsigned 值。
* AddString() -- 先加入大小，而后加入字符串到 Bits.
* 其它的相似，总之是构建一个 vector<unsigned> Bits，用以惟一化指定的 obj。也可认为是将 obj 给 serialize() 了。。。

* ComputeHash()：根据 Bits 中的全部已加入的数据，计算 hash 值。

这个对象的 sizeof() = 144 (不一样机器可能有不一样)，通常应是引用传递。里面的 [[SmallVector]] 若是装不下了，可能会在堆中分配空间的。

== 类 FoldingSetNodeIDRef ==
FoldingSetNodeIDRef 该类引用到保留(interned)起来的 FoldingSetNodeID，底层数据保存在某个分配器分配的堆中。通常不保存 FoldingSetNodeID 自身。

<syntaxhighlight lang="cpp">
class FoldingSetNodeIDRef {
  unsigned *Data;   // 指向底层数组
  unsigned Size;    // 数组长度

  this() // 构造，使用指定 Data,Size 构造。
  ComputeHash() // 为 Data,Size 计算 hash 值。
  operator==()  // 进行 == 判断。
}
</syntaxhighlight>

* 在 FoldingSetNodeID 中的方法 Intern(BumpPtrAllocator &alloc)，从 alloc 中分配空间保存 Data，而后用 Data,Size 构造 FoldingSetNodeIDRef 并返回。 alloc 负责管理分配了的内存。参见 [[BumpPtrAllocator]] 的说明。

 

== FoldingSetImpl ==
类 FoldingSetImpl 实现 folding set 的功能。主要的数据结构是一个桶(buckets)的数组。每一个桶经过节点的 hash 值进行索引。

=== FoldingSetImpl::Node ===
这个类的定义包含在 FoldingSetImpl 里面，为方便，拿出来单独写。
该类用于保存单向连接的列表节点。

<syntaxhighlight lang="cpp">
class FoldingSetImpl::Node {
  void *NextBucket;  // bucket 列表中的 next 连接。
  // 构造，
  get|setNextInBucket() // 获取/设置链表中下一个 Node.
}
</syntaxhighlight>

在 FoldingSet 集合中的节点被要求从这个类继承，也即须要有一个单连接指针指向下一个节点。（侵入式单链表）这里没有再使用复杂的模板 Traits，特化机制等等。

=== FoldingSetImpl ===
这个类实现了 FoldingSet 的基本功能。主要的数据结构是 Buckets 数组。经过 Node 的哈希值索引，其中的节点使用 Node.next 单向连接在一块儿。最后一个节点的 next 指针指向 bucket，这样便于节点删除操做。

<syntaxhighlight lang="cpp">
class FoldingSetImpl {
  void **Buckets;   // 桶的数组。
  unsigned NumBuckets;  // 桶的数量，也即数组大小。
  unsigned NumNodes;    // 当前集合中节点的数量。数量不少时候会增加总的桶数。

  this(), virtual ~()   // 构造与虚析构(为何是虚的？)。
  RemoveNode(Node *)    // 从集合中删除指定节点。
  GetOrInsertNode(Node *)  // 得到或插入节点，若是已经有了则返回，不然插入。
  FindNodeOrInsertPos(ID, &InsertPos)   // 查找ID的节点。不存在则返回插入点。
  InsertNode(Node *)    // 插入节点。

  size(),empty() // 容器标准方法。
  // 派生类必须实现的虚方法，和 FoldingSetTrait 类的方法一致。
  virtual GetNodeProfile(), NodeEquals(), ComputeNodeHash()
}
</syntaxhighlight>

* 问题：为何析构是虚函数？为何 GetNodeProfile() 等也被定义为虚函数呢？
* 咱们稍后在学习 FoldingSet 具体实现的时候，再看看是否须要学习几个重要函数的实现机制。

== 模板类 FoldingSet ==
FoldingSet<T> 模板类用于实现对特定的模板参数 T 实现的 FoldingSet。类 T 必须从 FoldingSetImpl::Node 类继承，并实现 Profile() 函数。

<syntaxhighlight lang="cpp">
template <T> class FoldingSet : public FoldingSetImpl {
  virtual GetNodeProfile()    // 实现父类的虚函数，转换节点为一个 ID
  virtual NodeEquals()        // 使用 Trait 类比较 Node 是否相等
  virtual ComputeNodeHash()   // 计算节点的哈希值

  this(Log2InitSize=6)  // 构造。桶的初始数量为 2 的 Log2InitSize 幂次。2**6 = 32.
 
  iterator 实现为 FoldingSetIterator<T>, const_iterator ...
  begin(),end()
  bucket_iterator 实现为 FoldingSetBucketIterator<T>
  bucket_begin,bucket_end()

  GetOrInsertNode(Node *N)  // 获取或插入节点
  FindNodeOrInsertPos(ID, InsertPos)  // 查找或提供插入点。
}
</syntaxhighlight>

* FoldingSet 的基本功能实如今 FoldingSetImpl 中，FoldingSet 对类型作了简单封装。为此须要看 FoldingSetImpl 的函数实现，以理解其实现机理。

== FoldingSetImpl 和 FoldingSet 实现机理 ==
为研究 FoldingSet 实现机理，咱们看几个主要函数的实现，及其要点。

=== GetOrInsertNode ===
函数原型为 Node *GetOrInsertNode(Node *N)，其做用是，若是已经有一个节点等于(Trait::Equals)指定的节点，则返回已有的；不然，插入 N 到集合中而后返回。

伪代码以下：
<syntaxhighlight lang="cpp">
Node *FS::GetOrInsertNode(Node *N) { // F 是 FoldingSetImpl 简写
  ID = GetNodeProfile(N) // 获得节点 N 的惟一标识 ID。
  Node *E, InsertPos *I = FindNodeOrInsertPos(ID) // 查找这个节点，若是没有则返回插入点
  if (E) // 标识为 ID 的节点存在
    return E  // 则返回已经存在的这个节点
  InsertNode(N, I)  // 将节点 N 插入到位置 I
  return N   // 返回插入的节点。
}
</syntaxhighlight>

* GetNodeProfile(N) 伪代码获得节点 N 的惟一标识，结果为 FoldingSetNodeID ID
* FindNodeOrInsertPos(ID) 下面研究
* InsertNode(N,I) 下面研究

这个函数能够认为是两个子功能合并在一块儿：GetNode(N.ID), InsertNode(N)

=== FindNodeOrInsertPos(ID) ===
查找指定 ID 的节点，若是存在则返回；不然得到插入的位置。这个函数能够认为是两个子功能的合并：FindNode(ID), CalcInsertPos(ID)。

伪代码以下：
<syntaxhighlight lang="cpp">
Node *FS:FindNodeOrInsertPos(ID, InsertPos &I) { // I 用于作返回值。
  hash = ID.ComputeHash()     // 计算 ID 对应的哈希值
  Bucket = GetBucketFor(hash) // 获得 ID 所在的桶(Bucket)
 
  while (Node *n = get_next_node()) // 循环：从桶中获得下一个节点。是单链表。
    if (n->ID == ID)  // 若是节点 n 的 ID 与参数 ID 相同，则为找到了。
      return n  // 找到了，返回
 
  // 没找到，返回空指针、插入位置。其实，就算找到了，也能够返回插入位置的。。。
  InsertPos &I = Bucket
  return (Node *)null
}
</syntaxhighlight>

* 注：为节省空间，桶中的节点使用了单链表连接在一块儿，最后一个节点指回 Bucket 自身。get_next_node() 利用指针的最低位 bit (Bit0) 置位表示指回了 Bucket。参见函数 FoldingSetImpl::GetNextPtr() 及其说明。

=== InsertNode ===
InsertNode 有两种形式，其中 InsertNode(Node*) 的调用形式转换为对 InsertNode(Node*, InsertPos I) 的调用，因此这里主要研究后一种形式。InsertPos 经过 FindNodeOrInsertPos() 方法获得。

<syntaxhighlight lang="cpp">
void FS::InsertNode(Node *N, InsertPos I) {
  // 若是元素数量太多，则增大哈希表桶的总数。
  Grow() if (NumNodes > 2*NumBuckets)

  Bucket *= I  // 插入点 I 实际上就是 Bucket 桶的指针。
  N->SetNextInBucket(Next)   // 设置 N 的 next 指针。具体 Next 算法见程序
  *Bucket = N  // 新节点插入到桶中节点列表的第一个。
}
</syntaxhighlight>

须要注意的是，Next 若是指回 Bucket 本身，则设置其指针的最后 bit 为 1。

=== RemoveNode ===
从 FoldingSet 中删除一个节点。返回 true 若是存在并删除成功；返回 false 表示不存在。

<syntaxhighlight lang="cpp">
bool FS:RemoveNode(Node *N) {
  *next = N->getNextInBucket()  // 获得 N 的 next 指针，若是为 null 表示不在 FS 中。
  若是 next == null 表示不在 FS 中，则返回 return false
  ...
  while () {
    // 在单链表 next->next->... 中查找，直到碰到指向 N 的那个节点，
    // 将其 next 指向 N 的next（修改单链表） 返回 true
    // 或者发现桶的指针须要更新，则更新。返回 true
  }
}
</syntaxhighlight>

这里使用了循环的单链表来寻找 next 指针及进行修改。若是不使用循环，则须要计算 N 的 ID，而后找到 Bucket，进行单链表的搜索。

综上所述，FoldingSet 上面各个函数实现了一个哈希表，解决冲突用的是链地址法。

其实，使用标准 hash_map，对 key，value 进行一些特殊处理，是否是也能解决需求呢？