Documentation/translations/zh_CN/core-api/xarray.rst

Source file repositories/reference/linux-study-clean/Documentation/translations/zh_CN/core-api/xarray.rst

File Facts

System
Linux kernel
Corpus path
Documentation/translations/zh_CN/core-api/xarray.rst
Extension
.rst
Size
20097 bytes
Lines
374
Domain
Support Tooling And Documentation
Bucket
Documentation
Inferred role
Support Tooling And Documentation: documentation
Status
atlas-only

Why This File Exists

Repository support layer: documentation, build tooling, samples, user-space helper tools, generated initramfs support, licenses, and validation utilities.

Dependency Surface

Detected Declarations

Annotated Snippet

.. SPDX-License-Identifier: GPL-2.0+
.. include:: ../disclaimer-zh_CN.rst

:Original: Documentation/core-api/xarray.rst

:翻译:

 司延腾 Yanteng Si <siyanteng@loongson.cn>
 周彬彬 Binbin Zhou <zhoubinbin@loongson.cn>

:校译:



.. _cn_core-api_xarray:

======
XArray
======

:作者: Matthew Wilcox

概览
====

XArray是一个抽象的数据类型，它的行为就像一个非常大的指针数组。它满足了许多与哈
希或传统可调整大小的数组相同的需求。与哈希不同的是，它允许你以一种高效的缓存方
式合理地转到下一个或上一个条目。与可调整大小的数组相比，不需要复制数据或改变MMU
的映射来增加数组。与双链表相比，它的内存效率更高，可并行，对缓存更友好。它利用
RCU的优势来执行查找而不需要锁定。

当使用的索引是密集聚集的时候，XArray的实现是有效的；而哈希对象并使用哈希作为索引
将不会有好的表现。XArray对小的索引进行了优化，不过对大的索引仍有良好的性能。如果
你的索引可以大于 ``ULONG_MAX`` ，那么XArray就不适合你的数据类型。XArray最重要
的用户是页面高速缓存。

普通指针可以直接存储在XArray中。它们必须是4字节对齐的，这对任何从kmalloc()和
alloc_page()返回的指针来说都是如此。这对任意的用户空间指针和函数指针来说都不是
真的。你可以存储指向静态分配对象的指针，只要这些对象的对齐方式至少是4（字节）。

你也可以在XArray中存储0到 ``LONG_MAX`` 之间的整数。你必须首先使用xa_mk_value()
将其转换为一个条目。当你从XArray中检索一个条目时，你可以通过调用xa_is_value()检
查它是否是一个值条目，并通过调用xa_to_value()将它转换回一个整数。

一些用户希望对他们存储在XArray中的指针进行标记。你可以调用xa_tag_pointer()来创建
一个带有标签的条目，xa_untag_pointer()将一个有标签的条目转回一个无标签的指针，
xa_pointer_tag()来检索一个条目的标签。标签指针使用相同的位，用于区分值条目和普通
指针，所以你必须决定他们是否要在任何特定的XArray中存储值条目或标签指针。

XArray不支持存储IS_ERR()指针，因为有些指针与值条目或内部条目冲突。

XArray的一个不寻常的特点是能够创建占据一系列索引的条目。一旦存储到其中，查询该范围
内的任何索引将返回与查询该范围内任何其他索引相同的条目。存储到任何索引都会存储所有
的索引条目。多索引条目可以明确地分割成更小的条目，或者将其存储 ``NULL`` 到任何条目中
都会使XArray忘记范围。

普通API
=======

首先初始化一个XArray，对于静态分配的XArray可以用DEFINE_XARRAY()，对于动态分配的
XArray可以用xa_init()。一个新初始化的XArray在每个索引处都包含一个 ``NULL`` 指针。

然后你可以用xa_store()来设置条目，用xa_load()来获取条目。xa_store将用新的条目覆盖任
何条目，并返回存储在该索引的上一个条目。你可以使用xa_erase()来代替调用xa_store()的
``NULL`` 条目。一个从未被存储过的条目、一个被擦除的条目和一个最近被存储过 ``NULL`` 的
条目之间没有区别。

你可以通过使用xa_cmpxchg()有条件地替换一个索引中的条目。和cmpxchg()一样，它只有在该索
引的条目有 ‘旧‘ 值时才会成功。它也会返回该索引上的条目；如果它返回与传递的 ‘旧‘ 相同的条
目，那么xa_cmpxchg()就成功了。

Annotation

Implementation Notes