[Bug] TSAN build fails with undefined symbol: BlockFileCache::get_cell<std::lock_guard<std::mutex>>

[heguanhui]

Search before asking

• I had searched in the issues and found no similar issues.

Version

master

What's Wrong?

When building BE UT with TSAN, the linker reports an undefined symbol error:

ld.lld: error: undefined symbol: doris::io::FileBlockCell* doris::io::BlockFileCache::get_cell<std::lock_guard<std::mutex>>(doris::io::UInt128Wrapper const&, unsigned long, T&)
>>> referenced by block_file_cache_test.cpp:2976 (./be/ut_build_TSAN/./be/test/io/cache/block_file_cache_test.cpp:2976)
>>>               test/CMakeFiles/doris_be_test.dir/io/cache/block_file_cache_test.cpp.o:(doris::io::BlockFileCacheTest_late_holder_remove_skips_replaced_cache_cell_Test::TestBody())
>>> referenced by block_file_cache_test.cpp:2989 (./be/ut_build_TSAN/./be/test/io/cache/block_file_cache_test.cpp:2989)
>>>               test/CMakeFiles/doris_be_test.dir/io/cache/block_file_cache_test.cpp.o:(doris::io::BlockFileCacheTest_late_holder_remove_skips_replaced_cache_cell_Test::TestBody())
clang++: error: linker command failed with exit code 1 (use -v to see invocation)
ninja: build stopped: subcommand failed.

What You Expected?

BE UT should build and link successfully with TSAN enabled.

How to Reproduce?

1. Build BE UT with TSAN: bash build.sh --be --ut --tsan
2. Linker fails with undefined symbol for BlockFileCache::get_cell<std::lock_guard<std::mutex>>

Root Cause

BlockFileCache::get_cell is a template function with requires IsXLock<T> constraint, defined in block_file_cache.cpp. It lacks explicit template instantiation for std::lock_guard<std::mutex>. In non-TSAN builds, the compiler may inline the template, masking the issue. TSAN builds disable inlining (instrumentation requires intercepting each function call), exposing the missing symbol.

The same pattern already exists for the remove template function at block_file_cache.cpp:2515:

template void BlockFileCache::remove(FileBlockSPtr file_block,
                                     std::lock_guard<std::mutex>& cache_lock,
                                     std::lock_guard<std::mutex>& block_lock, bool sync);

And for LRUQueue templates in file_cache_common.cpp:149-150:

template size_t LRUQueue::get_capacity(std::lock_guard<std::mutex>& cache_lock) const;
template void LRUQueue::remove(Iterator queue_it, std::lock_guard<std::mutex>& cache_lock);

get_cell is simply missing the same explicit instantiation.

Are you willing to submit PR?

• Yes I am willing to submit a PR!

[zclllyybb]

Breakwater-GitHub-Analysis-Slot: slot_59868e2812ba

Initial triage result: this looks like a real master build/linkage bug, not an environment-only TSAN report.

I checked refreshed upstream/master at 8255f94bc5fbee08c45f133a3d2fad87667e3e03. BlockFileCache::get_cell is declared as a constrained template in be/src/io/cache/block_file_cache.h and defined only in be/src/io/cache/block_file_cache.cpp. The failing BlockFileCacheTest.late_holder_remove_skips_replaced_cache_cell path calls cache.get_cell(key, 0, cache_lock) directly from the test translation unit, and SCOPED_CACHE_LOCK creates std::lock_guard<std::mutex> cache_lock.

That matches the undefined symbol:

doris::io::BlockFileCache::get_cell<std::lock_guard<std::mutex>>(...)

I found an explicit instantiation for BlockFileCache::remove(... std::lock_guard<std::mutex>&, std::lock_guard<std::mutex>&, ...), and the same explicit-instantiation pattern exists for LRUQueue, but I did not find an explicit instantiation for BlockFileCache::get_cell<std::lock_guard<std::mutex>> in be/src/io/cache.

So the reported root cause is consistent with the source. Since the template definition is not in the header, the test object can compile against the declaration but still need an emitted specialization from block_file_cache.cpp. A focused fix is to add the missing specialization near the existing explicit template instantiations:

template FileBlockCell* BlockFileCache::get_cell(const UInt128Wrapper& hash, size_t offset,
                                                 std::lock_guard<std::mutex>& cache_lock);

No behavior change should be expected; this is a template-instantiation/linkage fix.

There is already a matching public PR: #64228. Suggested next steps for maintainers:

1. Review that PR as the direct fix for this issue.
2. Ask for bash build.sh --be --ut --tsan or the failing BE UT link step to be rerun after the fix.
3. Keep or split any unrelated test-file changes in the PR if they are not required for this TSAN linkage failure, so the issue fix remains narrow.

No additional reproduction information is needed to accept the diagnosis. If the proposed fix still fails, the next useful evidence would be the full TSAN link command and the block_file_cache.cpp.o symbol table for the get_cell specialization.