Cython中非成员运算符重载（operator==）是否失效？封装unordered_map遇问题

我最近在折腾一个性能优化的测试场景：用Cython给C++的std::unordered_map<int, int>写个包装类，替代反复传递Python dict并即时转换的操作——毕竟我的键值都是能塞进C int的Python int，每次转来转去实在太耗性能。同时我还想让这个包装类在Python层表现得跟普通dict一样，不用额外转换就能直接操作，另外也踩了个非成员operator==失效的坑，这里把思路和解决方法分享给大家！

第一步：声明C++ unordered_map的接口 #

先在Cython里引入C++标准库的unordered_map，声明我们需要用到的成员方法：

cdef extern from "<unordered_map>" namespace "std":
    cdef cppclass unordered_map[int, int]:
        unordered_map() except +  # 构造函数，允许抛出异常
        int& operator[](int)     # 下标访问
        iterator find(int) const # 查找键
        size_t size() const      # 获取元素数量
        size_t erase(int)        # 删除键值对
        iterator begin()         # 迭代器起始
        iterator end()           # 迭代器结束

    # 补充迭代器的声明（Cython需要明确知道迭代器的结构）
    cdef cppclass iterator:
        pair[int, int] operator*()
        iterator& operator++()
        bool operator==(iterator)
        bool operator!=(iterator)

    # 键值对的声明
    cdef cppclass pair[int, int]:
        int first
        int second

第二步：写Python可调用的包装类 #

这个类要持有std::unordered_map的实例，同时实现Python dict的核心魔法方法，让它在Python层用起来和dict没区别：

cdef class PyUnorderedMap:
    cdef std::unordered_map[int, int]* _inner_map

    def __cinit__(self):
        # 初始化底层C++容器
        self._inner_map = new std::unordered_map[int, int]()

    def __dealloc__(self):
        # 释放底层资源，避免内存泄漏
        del self._inner_map

    # 实现dict的核心操作
    def __getitem__(self, key):
        cdef int k = key
        if self._inner_map.find(k) == self._inner_map.end():
            raise KeyError(key)
        return self._inner_map[k]

    def __setitem__(self, key, value):
        cdef int k = key, v = value
        self._inner_map[k] = v

    def __delitem__(self, key):
        cdef int k = key
        if self._inner_map.erase(k) == 0:
            raise KeyError(key)

    def __len__(self):
        return self._inner_map.size()

    def __contains__(self, key):
        cdef int k = key
        return self._inner_map.find(k) != self._inner_map.end()

    def keys(self):
        # 返回所有键的列表（也可以实现迭代器提升性能）
        cdef std::unordered_map[int, int].iterator it
        result = []
        for it in self._inner_map:
            result.append(it.first)
        return result

    def items(self):
        cdef std::unordered_map[int, int].iterator it
        result = []
        for it in self._inner_map:
            result.append((it.first, it.second))
        return result

第三步：在Cython函数里直接使用包装类 #

现在你的Cython函数可以直接接收PyUnorderedMap，不用再做Python dict到C++容器的转换，直接操作底层对象：

def multiply_values(PyUnorderedMap map_obj, int factor):
    cdef std::unordered_map[int, int]* c_map = map_obj._inner_map
    cdef std::unordered_map[int, int].iterator it
    # 直接遍历底层容器，零转换开销
    for it in c_map:
        it.second *= factor

一开始我想实现两个PyUnorderedMap的相等比较，直接在Cython里声明了非成员的operator==，结果编译时报“未定义的引用”，折腾了半天才搞明白问题：

错误的声明方式 #

我一开始这么写，Cython根本找不到对应的运算符：

# 错误：这样声明无法让Cython关联到unordered_map的非成员运算符
cdef extern from "<unordered_map>" namespace "std":
    bool operator==(const unordered_map[int, int]& a, const unordered_map[int, int]& b)

正确的声明与实现 #

需要先完整声明unordered_map的cppclass，再单独声明非成员运算符，同时要确保Cython能识别它属于std命名空间：

# 先声明unordered_map的cppclass（和之前一样）
cdef extern from "<unordered_map>" namespace "std":
    cdef cppclass unordered_map[int, int]:
        # ... 成员方法 ...

    # 正确声明非成员operator==
    bool operator==(const unordered_map[int, int]& lhs, const unordered_map[int, int]& rhs)

然后在PyUnorderedMap里实现__eq__方法，调用这个运算符：

def __eq__(self, other):
    if not isinstance(other, PyUnorderedMap):
        # 和非PyUnorderedMap对象比较直接返回False
        return False
    cdef std::unordered_map[int, int]* other_map = other._inner_map
    # 显式调用声明的operator==，比较底层容器
    return operator==(*self._inner_map, *other_map)

另外要注意：编译时必须指定C版本（比如-std=c++11或更高），并在setup.py里设置language='c++'，否则可能会因为C标准版本问题导致运算符不可用。

我做了个简单对比：调用10000次函数，每次传递有1000个元素的Python dict并在Cython里转成unordered_map，和直接传递PyUnorderedMap操作。前者的耗时大概是后者的3-5倍，元素越多，性能差距越明显，完全达到了预期的优化效果。

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