静态库中自定义哈希函数失效问题的排查与解决

问题场景 #

尝试将自定义结构体作为unordered_map的键，已正确实现自定义哈希函数与比较逻辑。静态库（STATIC）和动态库（SHARED）编译均无报错，但运行静态库构建的test_exec时，触发AddressSanitizer致命浮点错误（FPE），错误日志如下：

AddressSanitizer:DEADLYSIGNAL #

19573ERROR: AddressSanitizer: FPE on unknown address 0x561e54882917 (pc 0x561e54882917 bp 0x7ffea9e6f580 sp 0x7ffea9e6f580 T0)
#0 0x561e54882917 in std::__detail::_Mod_range_hashing::operator()(unsigned long, unsigned long) const (/home/TEST/minimal_example/build_DEBUG/test_exec+0x4917)
#1 0x561e5488855f in std::__detail::_Hash_code_base<std::__cxx11::basic_string<char, std::char_traits<char>, std::allocator<char> >, std::pair<std::__cxx11::basic_string<char, std::char_traits<char>, std::allocator<char> > const, test::MyEnum>, std::__detail::_Select1st, std::hash<std::__cxx11::basic_string<char, std::char_traits<char>, std::allocator<char> > >, std::__detail::_Mod_range_hashing, std::__detail::_Default_ranged_hash, true>::_M_bucket_index(unsigned long, unsigned long) const (/home/TEST/minimal_example/build_DEBUG/test_exec+0xa55f)
AddressSanitizer:DEADLYSIGNAL
AddressSanitizer: nested bug in the same thread, aborting

问题根源 #

这是典型的全局变量初始化顺序问题：

• 若原代码中unordered_map作为静态全局变量直接在头文件定义，或在库的全局作用域直接初始化，会导致程序启动阶段，unordered_map的内部桶结构尚未完成初始化（桶数量为0）就被外部代码访问。
• std::__detail::_Mod_range_hashing会用哈希值对桶数量取模，此时桶数量为0，触发除以零的浮点错误。
• 静态库与动态库的差异：动态库的全局变量初始化时机晚于主程序启动逻辑，而静态库的全局变量会被合并到主程序的初始化段，可能在主程序代码执行前提前初始化，一旦存在跨编译单元的全局变量依赖，就会触发未初始化访问问题。

解决方法 #

通过延迟初始化避免启动阶段的顺序冲突：

1. 在库的头文件（如test_lib.h）中用extern声明全局变量：

   extern const MyMap MAP;
   

2. 在库的实现文件（如test_lib.cpp）中通过函数调用完成初始化：

   // 先实现一个填充并返回MyMap的函数
   MyMap get_map() {
       MyMap map;
       // 向map中添加键值对
       return map;
   }
   
   const MyMap MAP = get_map();
   

这种方式通过函数返回值初始化全局变量，确保unordered_map的内部结构完全初始化后才会被其他代码访问，从根本上解决了初始化顺序导致的未定义行为。

内容的提问来源于stack exchange，提问作者Juggling6743