【lucene】DocumentsWriterFlushControl

一句话

`DocumentsWriterFlushControl` 是 Lucene 在 多线程写入 场景下的 “全局刷盘调度器”——负责决定 何时、由哪些 DWPT（DocumentsWriterPerThread） 去 flush，并保证 内存不会爆掉、线程不会饿死。

---

它到底管哪些事？

1. 触发时机

   • 每个线程写完文档后，都会把数据放到自己的 DWPT 缓冲区。

   • `DocumentsWriterFlushControl` 内部持有一个 `FlushPolicy`（默认是 `FlushByRamOrCountsPolicy`），根据

     ‑ RAMBufferSizeMB（内存阈值）

     ‑ MaxBufferedDocs（文档数阈值）

     ‑ MaxBufferedDeleteTerms（删除项阈值）

     来判断 “这个 DWPT 是否该 flush”。

2. 并发调度

   • 当多线程同时达到阈值时，`FlushControl` 会把需要刷新的 DWPT 标记为 `flushPending`，然后放进一个 flushQueue。

   • 内部用 `DocumentsWriterStallControl` 做 “健康管理”：如果 flush 线程赶不上写线程，写线程会被阻塞，防止 OOM。

“flush 线程赶不上写线程”指的是：

写入线程把数据塞进 DWPT 的速度，比后台真正把 DWPT 刷到磁盘的速度要快得多，导致 所有可用 DWPT 都被占满、总内存用量逼近上限，如果不刹车就会 OOM。

具体过程

1. 每个 DWPT 是一块独立的内存缓冲区。  

2. 当 DWPT 达到阈值（RAMBufferSizeMB 或 doc 数）时，会被标记为 flushPending，等待后台线程把它写成一个 segment。  

3. 如果后台 flush 线程（或磁盘 I/O）太慢，flushPending 的 DWPT 迟迟得不到释放。  

4. 活跃的写线程还在不断创建 新的 DWPT 或继续往已有 DWPT 里添加文档。  

5. 结果：

   • 活跃的 DWPT 数量越来越多；

   • 总内存占用持续上升；

   • 最终触发 `DocumentsWriterFlushControl` 的 stall 保护——写线程被 主动阻塞（stall），直到 flush 线程腾出一个 DWPT 为止。

一句话总结

“flush 线程赶不上写线程”就是 写得太快、刷得太慢，Lucene 通过 stall 机制 强制写线程 暂停，防止把 JVM 内存撑爆。

3. full-flush vs 单 DWPT flush

   • `commit/close/forceMerge` 等操作会触发 full flush → `flushAllThreads()` → `markForFullFlush()` 把所有 active DWPT 一次性刷盘并生成 commit point。

   • 普通的 `updateDocument` 只是 单个 DWPT flush，不会全局落盘。

4. 线程同步

   • 使用 Balking + TicketQueue 模式：

     ‑ `markForFullFlush` 把 DWPT 状态从 active → flushing，并放入 `flushingWriters` Map，相当于“轻量级锁”。

     ‑ flush 线程每完成一个 DWPT 就“交票”，主线程 `waitForFlush()` 会感知并继续。

---

再简单一点

`DocumentsWriterFlushControl` 就是 IndexWriter 的 “内存管家 + 刷盘调度器”：

- 写线程只管往 DWPT 里塞数据；  

- 它来决定“谁、什么时候”把 DWPT 刷成 segment；  

- 同时保证 内存可控、并发安全、不丢数据。