# SOME DESCRIPTIVE TITLE.

# Copyright (C) 2001-2025, Python Software Foundation

# This file is distributed under the same license as the Python package.

# FIRST AUTHOR <EMAIL@ADDRESS>, YEAR.

#

# Translators:

# Rafael Fontenelle <[email protected]>, 2025

#

#, fuzzy

msgid ""

msgstr ""

"Project-Id-Version: Python 3.12\n"

"Report-Msgid-Bugs-To: \n"

"POT-Creation-Date: 2025-07-25 16:03+0000\n"

"PO-Revision-Date: 2025-07-18 19:57+0000\n"

"Last-Translator: Rafael Fontenelle <[email protected]>, 2025\n"

"Language-Team: Chinese (China) (https://app.transifex.com/python-doc/teams/5390/zh_CN/)\n"

"MIME-Version: 1.0\n"

"Content-Type: text/plain; charset=UTF-8\n"

"Content-Transfer-Encoding: 8bit\n"

"Language: zh_CN\n"

"Plural-Forms: nplurals=1; plural=0;\n"

#: ../../c-api/gcsupport.rst:6

msgid "Supporting Cyclic Garbage Collection"

msgstr "使对象类型支持循环垃圾回收"

#: ../../c-api/gcsupport.rst:8

msgid ""

"Python's support for detecting and collecting garbage which involves "

"circular references requires support from object types which are "

"\"containers\" for other objects which may also be containers. Types which "

"do not store references to other objects, or which only store references to "

"atomic types (such as numbers or strings), do not need to provide any "

"explicit support for garbage collection."

msgstr ""

"Python "

"对循环引用的垃圾检测与回收需要“容器”对象类型的支持，此类型的容器对象中可能包含其它容器对象。不保存其它对象的引用的类型，或者只保存原子类型（如数字或字符串）的引用的类型，不需要显式提供垃圾回收的支持。"

#: ../../c-api/gcsupport.rst:15

msgid ""

"To create a container type, the :c:member:`~PyTypeObject.tp_flags` field of "

"the type object must include the :c:macro:`Py_TPFLAGS_HAVE_GC` and provide "

"an implementation of the :c:member:`~PyTypeObject.tp_traverse` handler. If "

"instances of the type are mutable, a :c:member:`~PyTypeObject.tp_clear` "

"implementation must also be provided."

msgstr ""

"要创建一个容器类，类型对象的 :c:member:`~PyTypeObject.tp_flags` 字段必须包括 "

":c:macro:`Py_TPFLAGS_HAVE_GC` 并提供一个 :c:member:`~PyTypeObject.tp_traverse` "

"处理器的实现。 如果该类型的实例是可变的，则还必须提供 :c:member:`~PyTypeObject.tp_clear` 的实现。"

#: ../../c-api/gcsupport.rst:21

msgid ":c:macro:`Py_TPFLAGS_HAVE_GC`"

msgstr ":c:macro:`Py_TPFLAGS_HAVE_GC`"

#: ../../c-api/gcsupport.rst:22

msgid ""

"Objects with a type with this flag set must conform with the rules "

"documented here. For convenience these objects will be referred to as "

"container objects."

msgstr "设置了此标志位的类型的对象必须符合此处记录的规则。为方便起见，下文把这些对象称为容器对象。"

#: ../../c-api/gcsupport.rst:26

msgid "Constructors for container types must conform to two rules:"

msgstr "容器类型的构造函数必须符合两个规则："

#: ../../c-api/gcsupport.rst:28

msgid ""

"The memory for the object must be allocated using :c:macro:`PyObject_GC_New`"

" or :c:macro:`PyObject_GC_NewVar`."

msgstr ""

"该对象的内在必须使用 :c:macro:`PyObject_GC_New` 或 :c:macro:`PyObject_GC_NewVar` 来分配。"

#: ../../c-api/gcsupport.rst:31

msgid ""

"Once all the fields which may contain references to other containers are "

"initialized, it must call :c:func:`PyObject_GC_Track`."

msgstr "初始化了所有可能包含其他容器的引用的字段后，它必须调用 :c:func:`PyObject_GC_Track` 。"

#: ../../c-api/gcsupport.rst:34

msgid ""

"Similarly, the deallocator for the object must conform to a similar pair of "

"rules:"

msgstr "同样的，对象的释放器必须符合两个类似的规则："

#: ../../c-api/gcsupport.rst:37

msgid ""

"Before fields which refer to other containers are invalidated, "

":c:func:`PyObject_GC_UnTrack` must be called."

msgstr "在引用其它容器的字段失效前，必须调用 :c:func:`PyObject_GC_UnTrack` 。"

#: ../../c-api/gcsupport.rst:40

msgid ""

"The object's memory must be deallocated using :c:func:`PyObject_GC_Del`."

msgstr "必须使用 :c:func:`PyObject_GC_Del` 释放对象的内存。"

#: ../../c-api/gcsupport.rst:43

msgid ""

"If a type adds the Py_TPFLAGS_HAVE_GC, then it *must* implement at least a "

":c:member:`~PyTypeObject.tp_traverse` handler or explicitly use one from its"

" subclass or subclasses."

msgstr ""

"如果一个类型添加了 Py_TPFLAGS_HAVE_GC，则它 *必须* 实现至少一个 "

":c:member:`~PyTypeObject.tp_traverse` 句柄或显式地使用来自其一个或多个子类的句柄。"

#: ../../c-api/gcsupport.rst:47

msgid ""

"When calling :c:func:`PyType_Ready` or some of the APIs that indirectly call"

" it like :c:func:`PyType_FromSpecWithBases` or :c:func:`PyType_FromSpec` the"

" interpreter will automatically populate the "

":c:member:`~PyTypeObject.tp_flags`, :c:member:`~PyTypeObject.tp_traverse` "

"and :c:member:`~PyTypeObject.tp_clear` fields if the type inherits from a "

"class that implements the garbage collector protocol and the child class "

"does *not* include the :c:macro:`Py_TPFLAGS_HAVE_GC` flag."

msgstr ""

"当调用 :c:func:`PyType_Ready` 或者某些间接调用该函数的 API 如 "

":c:func:`PyType_FromSpecWithBases` 或 :c:func:`PyType_FromSpec` 时解释器将自动填充 "

":c:member:`~PyTypeObject.tp_flags`, :c:member:`~PyTypeObject.tp_traverse` 和 "

":c:member:`~PyTypeObject.tp_clear` 字段，如果该类型是继承自实现了垃圾回收器协议的类并且该子类 *没有* 包括 "

":c:macro:`Py_TPFLAGS_HAVE_GC` 旗标的话。"

#: ../../c-api/gcsupport.rst:57

msgid ""

"Analogous to :c:macro:`PyObject_New` but for container objects with the "

":c:macro:`Py_TPFLAGS_HAVE_GC` flag set."

msgstr ""

"类似于 :c:macro:`PyObject_New` 但专用于设置了 :c:macro:`Py_TPFLAGS_HAVE_GC` 旗标的容器对象。"

#: ../../c-api/gcsupport.rst:62

msgid ""

"Analogous to :c:macro:`PyObject_NewVar` but for container objects with the "

":c:macro:`Py_TPFLAGS_HAVE_GC` flag set."

msgstr ""

"与 :c:macro:`PyObject_NewVar` 类似但专用于设置了 :c:macro:`Py_TPFLAGS_HAVE_GC` "

"旗标的容器对象。"

#: ../../c-api/gcsupport.rst:67

msgid ""

"Analogous to :c:macro:`PyObject_GC_New` but allocates *extra_size* bytes at "

"the end of the object (at offset :c:member:`~PyTypeObject.tp_basicsize`). "

"The allocated memory is initialized to zeros, except for the :c:type:`Python"

" object header <PyObject>`."

msgstr ""

"与 :c:macro:`PyObject_GC_New` 类似但会在对象的末尾分配 *extra_size* 个字节（在 "

":c:member:`~PyTypeObject.tp_basicsize` 偏移量处）。 除 :c:type:`Python "

"对象标头<PyObject>` 外，分配的内存将初始化为零。"

#: ../../c-api/gcsupport.rst:73

msgid ""

"The extra data will be deallocated with the object, but otherwise it is not "

"managed by Python."

msgstr "附加数据将与对象一起被释放，但在其他情况下则不会由 Python 来管理。"

#: ../../c-api/gcsupport.rst:77

msgid ""

"The function is marked as unstable because the final mechanism for reserving"

" extra data after an instance is not yet decided. For allocating a variable "

"number of fields, prefer using :c:type:`PyVarObject` and "

":c:member:`~PyTypeObject.tp_itemsize` instead."

msgstr ""

"此函数被标记为非稳定的因为在实例之后保留附加数据的机制尚未确定。 要分配可变数量的字段，推荐改用 :c:type:`PyVarObject` 和 "

":c:member:`~PyTypeObject.tp_itemsize`。"

#: ../../c-api/gcsupport.rst:88

msgid ""

"Resize an object allocated by :c:macro:`PyObject_NewVar`. Returns the "

"resized object of type ``TYPE*`` (refers to any C type) or ``NULL`` on "

"failure."

msgstr ""

"重新调整 :c:macro:`PyObject_NewVar` 所分配对象的大小。 返回调整大小后的类型为 ``TYPE*`` 的对象（指向任意 C "

"类型）或在失败时返回 ``NULL``。"

#: ../../c-api/gcsupport.rst:92

msgid ""

"*op* must be of type :c:expr:`PyVarObject *` and must not be tracked by the "

"collector yet. *newsize* must be of type :c:type:`Py_ssize_t`."

msgstr ""

"*op* 必须为 :c:expr:`PyVarObject *` 类型并且不能已被回收器所追踪。 *newsize* 必须为 "

":c:type:`Py_ssize_t` 类型。"

#: ../../c-api/gcsupport.rst:99

msgid ""

"Adds the object *op* to the set of container objects tracked by the "

"collector. The collector can run at unexpected times so objects must be "

"valid while being tracked. This should be called once all the fields "

"followed by the :c:member:`~PyTypeObject.tp_traverse` handler become valid, "

"usually near the end of the constructor."

msgstr ""

"把对象 *op* 加入到垃圾回收器跟踪的容器对象中。对象在被回收器跟踪时必须保持有效的，因为回收器可能在任何时候开始运行。在 "

":c:member:`~PyTypeObject.tp_traverse` 处理前的所有字段变为有效后，必须调用此函数，通常在靠近构造函数末尾的位置。"

#: ../../c-api/gcsupport.rst:108

msgid ""

"Returns non-zero if the object implements the garbage collector protocol, "

"otherwise returns 0."

msgstr "如果对象实现了垃圾回收器协议则返回非零值，否则返回 0。"

#: ../../c-api/gcsupport.rst:111

msgid ""

"The object cannot be tracked by the garbage collector if this function "

"returns 0."

msgstr "如果此函数返回 0 则对象无法被垃圾回收器追踪。"

#: ../../c-api/gcsupport.rst:116

msgid ""

"Returns 1 if the object type of *op* implements the GC protocol and *op* is "

"being currently tracked by the garbage collector and 0 otherwise."

msgstr "如果 *op* 对象的类型实现了 GC 协议且 *op* 目前正被垃圾回收器追踪则返回 1， 否则返回 0。"

#: ../../c-api/gcsupport.rst:119

msgid "This is analogous to the Python function :func:`gc.is_tracked`."

msgstr "这类似于 Python 函数 :func:`gc.is_tracked`。"

#: ../../c-api/gcsupport.rst:126

msgid ""

"Returns 1 if the object type of *op* implements the GC protocol and *op* has"

" been already finalized by the garbage collector and 0 otherwise."

msgstr "如果 *op* 对象的类型实现了 GC 协议且 *op* 已经被垃圾回收器终结则返回 1， 否则返回 0。"

#: ../../c-api/gcsupport.rst:129

msgid "This is analogous to the Python function :func:`gc.is_finalized`."

msgstr "这类似于 Python 函数 :func:`gc.is_finalized`。"

#: ../../c-api/gcsupport.rst:136

msgid ""

"Releases memory allocated to an object using :c:macro:`PyObject_GC_New` or "

":c:macro:`PyObject_GC_NewVar`."

msgstr ""

"使用 :c:macro:`PyObject_GC_New` 或 :c:macro:`PyObject_GC_NewVar` 释放分配给对象的内存。"

#: ../../c-api/gcsupport.rst:142

msgid ""

"Remove the object *op* from the set of container objects tracked by the "

"collector. Note that :c:func:`PyObject_GC_Track` can be called again on "

"this object to add it back to the set of tracked objects. The deallocator "

"(:c:member:`~PyTypeObject.tp_dealloc` handler) should call this for the "

"object before any of the fields used by the "

":c:member:`~PyTypeObject.tp_traverse` handler become invalid."

msgstr ""

"从回收器跟踪的容器对象集合中移除 *op* 对象。 请注意可以在此对象上再次调用 :c:func:`PyObject_GC_Track` "

"以将其加回到被跟踪对象集合。 释放器 (:c:member:`~PyTypeObject.tp_dealloc` 句柄) 应当在 "

":c:member:`~PyTypeObject.tp_traverse` 句柄所使用的任何字段失效之前为对象调用此函数。"

#: ../../c-api/gcsupport.rst:151

msgid ""

"The :c:func:`!_PyObject_GC_TRACK` and :c:func:`!_PyObject_GC_UNTRACK` macros"

" have been removed from the public C API."

msgstr ""

":c:func:`!_PyObject_GC_TRACK` 和 :c:func:`!_PyObject_GC_UNTRACK` 宏已从公有 C API "

"中删除。"

#: ../../c-api/gcsupport.rst:154

msgid ""

"The :c:member:`~PyTypeObject.tp_traverse` handler accepts a function "

"parameter of this type:"

msgstr ":c:member:`~PyTypeObject.tp_traverse` 处理接收以下类型的函数形参。"

#: ../../c-api/gcsupport.rst:159

msgid ""

"Type of the visitor function passed to the "

":c:member:`~PyTypeObject.tp_traverse` handler. The function should be called"

" with an object to traverse as *object* and the third parameter to the "

":c:member:`~PyTypeObject.tp_traverse` handler as *arg*. The Python core "

"uses several visitor functions to implement cyclic garbage detection; it's "

"not expected that users will need to write their own visitor functions."

msgstr ""

"传给 :c:member:`~PyTypeObject.tp_traverse` 处理的访问函数的类型。*object* "

"是容器中需要被遍历的一个对象，第三个形参对应于 :c:member:`~PyTypeObject.tp_traverse` 处理的 *arg* "

"。Python核心使用多个访问者函数实现循环引用的垃圾检测，不需要用户自行实现访问者函数。"

#: ../../c-api/gcsupport.rst:166

msgid ""

"The :c:member:`~PyTypeObject.tp_traverse` handler must have the following "

"type:"

msgstr ":c:member:`~PyTypeObject.tp_traverse` 处理必须是以下类型："

#: ../../c-api/gcsupport.rst:171

msgid ""

"Traversal function for a container object. Implementations must call the "

"*visit* function for each object directly contained by *self*, with the "

"parameters to *visit* being the contained object and the *arg* value passed "

"to the handler. The *visit* function must not be called with a ``NULL`` "

"object argument. If *visit* returns a non-zero value that value should be "

"returned immediately."

msgstr ""

"用于容器对象的遍历函数。 它的实现必须对 *self* 所直接包含的每个对象调用 *visit* 函数，*visit* "

"的形参为所包含对象和传给处理程序的 *arg* 值。 *visit* 函数调用不可附带 ``NULL`` 对象作为参数。 如果 *visit* "

"返回非零值，则该值应当被立即返回。"

#: ../../c-api/gcsupport.rst:178

msgid ""

"To simplify writing :c:member:`~PyTypeObject.tp_traverse` handlers, a "

":c:func:`Py_VISIT` macro is provided. In order to use this macro, the "

":c:member:`~PyTypeObject.tp_traverse` implementation must name its arguments"

" exactly *visit* and *arg*:"

msgstr ""

"为了简化 :c:member:`~PyTypeObject.tp_traverse` 处理的实现，Python提供了一个 "

":c:func:`Py_VISIT` 宏。若要使用这个宏，必须把 :c:member:`~PyTypeObject.tp_traverse` "

"的参数命名为 *visit* 和 *arg* 。"

#: ../../c-api/gcsupport.rst:185

msgid ""

"If *o* is not ``NULL``, call the *visit* callback, with arguments *o* and "

"*arg*. If *visit* returns a non-zero value, then return it. Using this "

"macro, :c:member:`~PyTypeObject.tp_traverse` handlers look like::"

msgstr ""

"如果 *o* 不为 ``NULL``，则调用 *visit* 回调函数，附带参数 *o* 和 *arg*。 如果 *visit* "

"返回一个非零值，则返回该值。 使用此宏之后，:c:member:`~PyTypeObject.tp_traverse` 处理程序的形式如下::"

#: ../../c-api/gcsupport.rst:190

msgid ""

"static int\n"

"my_traverse(Noddy *self, visitproc visit, void *arg)\n"

"{\n"

" Py_VISIT(self->foo);\n"

" Py_VISIT(self->bar);\n"

" return 0;\n"

"}"

msgstr ""

"static int\n"

"my_traverse(Noddy *self, visitproc visit, void *arg)\n"

"{\n"

" Py_VISIT(self->foo);\n"

" Py_VISIT(self->bar);\n"

" return 0;\n"

"}"

#: ../../c-api/gcsupport.rst:198

msgid ""

"The :c:member:`~PyTypeObject.tp_clear` handler must be of the "

":c:type:`inquiry` type, or ``NULL`` if the object is immutable."

msgstr ""

":c:member:`~PyTypeObject.tp_clear` 处理程序必须为 :c:type:`inquiry` 类型，如果对象不可变则为 "

"``NULL``。"

#: ../../c-api/gcsupport.rst:204

msgid ""

"Drop references that may have created reference cycles. Immutable objects "

"do not have to define this method since they can never directly create "

"reference cycles. Note that the object must still be valid after calling "

"this method (don't just call :c:func:`Py_DECREF` on a reference). The "

"collector will call this method if it detects that this object is involved "

"in a reference cycle."

msgstr ""

"丢弃产生循环引用的引用。不可变对象不需要声明此方法，因为他们不可能直接产生循环引用。需要注意的是，对象在调用此方法后必须仍是有效的（不能对引用只调用 "

":c:func:`Py_DECREF` 方法）。当垃圾回收器检测到该对象在循环引用中时，此方法会被调用。"

#: ../../c-api/gcsupport.rst:213

msgid "Controlling the Garbage Collector State"

msgstr "控制垃圾回收器状态"

#: ../../c-api/gcsupport.rst:215

msgid ""

"The C-API provides the following functions for controlling garbage "

"collection runs."

msgstr "这个 C-API 提供了以下函数用于控制垃圾回收的运行。"

#: ../../c-api/gcsupport.rst:220

msgid ""

"Perform a full garbage collection, if the garbage collector is enabled. "

"(Note that :func:`gc.collect` runs it unconditionally.)"

msgstr "执行完全的垃圾回收，如果垃圾回收器已启用的话。 （请注意 :func:`gc.collect` 会无条件地执行它。）"

#: ../../c-api/gcsupport.rst:223

msgid ""

"Returns the number of collected + unreachable objects which cannot be "

"collected. If the garbage collector is disabled or already collecting, "

"returns ``0`` immediately. Errors during garbage collection are passed to "

":data:`sys.unraisablehook`. This function does not raise exceptions."

msgstr ""

"返回已回收的 + 无法回收的不可获取对象的数量。 如果垃圾回收器被禁用或已在执行回收，则立即返回 ``0``。 在垃圾回收期间发生的错误会被传给 "

":data:`sys.unraisablehook`。 此函数不会引发异常。"

#: ../../c-api/gcsupport.rst:233

msgid ""

"Enable the garbage collector: similar to :func:`gc.enable`. Returns the "

"previous state, 0 for disabled and 1 for enabled."

msgstr "启用垃圾回收器：类似于 :func:`gc.enable`。 返回之前的状态，0 为禁用而 1 为启用。"

#: ../../c-api/gcsupport.rst:241

msgid ""

"Disable the garbage collector: similar to :func:`gc.disable`. Returns the "

"previous state, 0 for disabled and 1 for enabled."

msgstr "禁用垃圾回收器：类似于 :func:`gc.disable`。 返回之前的状态，0 为禁用而 1 为启用。"

#: ../../c-api/gcsupport.rst:249

msgid ""

"Query the state of the garbage collector: similar to :func:`gc.isenabled`. "

"Returns the current state, 0 for disabled and 1 for enabled."

msgstr "查询垃圾回收器的状态：类似于 :func:`gc.isenabled`。 返回当前的状态，0 为禁用而 1 为启用。"

#: ../../c-api/gcsupport.rst:256

msgid "Querying Garbage Collector State"

msgstr "查询垃圾回收器状态"

#: ../../c-api/gcsupport.rst:258

msgid ""

"The C-API provides the following interface for querying information about "

"the garbage collector."

msgstr "该 C-API 提供了以下接口用于查询有关垃圾回收器的信息。"

#: ../../c-api/gcsupport.rst:263

msgid ""

"Run supplied *callback* on all live GC-capable objects. *arg* is passed "

"through to all invocations of *callback*."

msgstr "在全部活动的支持 GC 的对象上运行所提供的 *callback*。 *arg* 会被传递给所有 *callback* 的唤起操作。"

#: ../../c-api/gcsupport.rst:267

msgid ""

"If new objects are (de)allocated by the callback it is undefined if they "

"will be visited."

msgstr "如果新对象被回调（取消）分配后再被访问其行为是未定义的。"

#: ../../c-api/gcsupport.rst:270

msgid ""

"Garbage collection is disabled during operation. Explicitly running a "

"collection in the callback may lead to undefined behaviour e.g. visiting the"

" same objects multiple times or not at all."

msgstr "垃圾回收在运行期间被禁用。 在回调中显式地运行回收可能导致未定义的行为，例如多次访问同一对象或完全不访问。"

#: ../../c-api/gcsupport.rst:278

msgid ""

"Type of the visitor function to be passed to "

":c:func:`PyUnstable_GC_VisitObjects`. *arg* is the same as the *arg* passed "

"to ``PyUnstable_GC_VisitObjects``. Return ``0`` to continue iteration, "

"return ``1`` to stop iteration. Other return values are reserved for now so "

"behavior on returning anything else is undefined."

msgstr ""

"要传给 :c:func:`PyUnstable_GC_VisitObjects` 的访问者函数的类型。 *arg* 与传给 "

"``PyUnstable_GC_VisitObjects`` 的 *arg* 相同。 返回 ``0`` 以继续迭代，返回 ``1`` 以停止迭代。 "

"其他返回值目前被保留因此返回任何其他值的行为都是未定义的。"