Đếm tham chiếu

Các hàm và macro trong phần này được sử dụng để quản lý số lượng tham chiếu của các đối tượng Python.

Py_ssize_t Py_REFCNT(PyObject *o)

Một phần của ABI ổn định kể từ phiên bản 3.14.

Lấy số tham chiếu của đối tượng Python o.

Lưu ý rằng giá trị trả về có thể không thực sự phản ánh số lượng tham chiếu đến đối tượng thực sự được giữ. Ví dụ: một số đối tượng là immortal và có số lần truy cập rất cao không phản ánh số lượng tham chiếu thực tế. Do đó, không dựa vào giá trị trả về là chính xác, ngoại trừ giá trị 0 hoặc 1.

Sử dụng hàm Py_SET_REFCNT() để đặt số lượng tham chiếu đối tượng.

Ghi chú

Trên free-threaded builds của Python, việc trả về 1 là không đủ để xác định xem liệu có an toàn khi coi o là không có quyền truy cập bởi các luồng khác hay không. Thay vào đó hãy sử dụng PyUnstable_Object_IsUniquelyReferenced().

Xem thêm chức năng PyUnstable_Object_IsUniqueReferencedTemporary().

Thay đổi trong phiên bản 3.10: Py_REFCNT() được thay đổi thành hàm tĩnh nội tuyến.

Thay đổi trong phiên bản 3.11: Loại tham số không còn là const PyObject* nữa.

void Py_SET_REFCNT(PyObject *o, Py_ssize_t refcnt)

Đặt bộ đếm tham chiếu đối tượng o thành refcnt.

Trên Python build with Free Threading, nếu refcnt lớn hơn UINT32_MAX, đối tượng sẽ được tạo thành immortal.

Chức năng này không có tác dụng đối với các đối tượng immortal.

Added in version 3.9.

Thay đổi trong phiên bản 3.12: Các vật thể bất tử không bị sửa đổi.

void Py_INCREF(PyObject *o)

Cho biết việc lấy một strong reference mới để đối tượng o, cho biết nó đang được sử dụng và không nên phá hủy.

Chức năng này không có tác dụng đối với các đối tượng immortal.

Hàm này thường được sử dụng để chuyển đổi borrowed reference thành strong reference tại chỗ. Chức năng Py_NewRef() có thể được sử dụng để tạo strong reference mới.

Khi sử dụng xong đối tượng, hãy giải phóng bằng cách gọi Py_DECREF().

Đối tượng không được là NULL; nếu bạn không chắc chắn đó không phải là NULL, hãy sử dụng Py_XINCREF().

Đừng mong đợi chức năng này thực sự sửa đổi o theo bất kỳ cách nào. Đối với ít nhất some objects, chức năng này không có hiệu lực.

Thay đổi trong phiên bản 3.12: Các vật thể bất tử không bị sửa đổi.

void Py_XINCREF(PyObject *o)

Tương tự như Py_INCREF(), nhưng đối tượng o có thể là NULL, trong trường hợp này điều này không có hiệu lực.

Xem thêm Py_XNewRef().

PyObject *Py_NewRef(PyObject *o)

Một phần của ABI ổn định kể từ phiên bản 3.10.

Tạo một strong reference mới cho một đối tượng: gọi Py_INCREF() trên o và trả về đối tượng o.

Khi strong reference không còn cần thiết nữa, Py_DECREF() sẽ được gọi để giải phóng tham chiếu.

Đối tượng o không được là NULL; sử dụng Py_XNewRef() nếu o có thể là NULL.

Ví dụ:

Py_INCREF(obj);
self->attr = obj;

có thể được viết là:

self->attr = Py_NewRef(obj);

Xem thêm Py_INCREF().

Added in version 3.10.

PyObject *Py_XNewRef(PyObject *o)

Một phần của ABI ổn định kể từ phiên bản 3.10.

Tương tự như Py_NewRef() nhưng đối tượng o có thể là NULL.

Nếu đối tượng o là NULL thì hàm chỉ trả về NULL.

Added in version 3.10.

void Py_DECREF(PyObject *o)

Giải phóng strong reference cho đối tượng o, cho biết tham chiếu không còn được sử dụng.

Chức năng này không có tác dụng đối với các đối tượng immortal.

Khi strong reference cuối cùng được giải phóng (tức là số tham chiếu của đối tượng đạt đến 0), hàm phân bổ loại của đối tượng (không được là NULL) sẽ được gọi.

Chức năng này thường được sử dụng để xóa strong reference trước khi thoát khỏi phạm vi của nó.

Đối tượng không được là NULL; nếu bạn không chắc chắn đó không phải là NULL, hãy sử dụng Py_XDECREF().

Đừng mong đợi chức năng này thực sự sửa đổi o theo bất kỳ cách nào. Đối với ít nhất some objects, chức năng này không có hiệu lực.

Cảnh báo

Hàm giải phóng có thể khiến mã Python tùy ý được gọi (ví dụ: khi một thể hiện của lớp có phương thức __del__() bị hủy phân bổ). Mặc dù các ngoại lệ trong mã như vậy không được truyền bá, nhưng mã được thực thi có quyền truy cập miễn phí vào tất cả các biến toàn cục của Python. Điều này có nghĩa là bất kỳ đối tượng nào có thể truy cập được từ biến toàn cục đều phải ở trạng thái nhất quán trước khi Py_DECREF() được gọi. Ví dụ: mã để xóa một đối tượng khỏi danh sách phải sao chép tham chiếu đến đối tượng đã xóa trong một biến tạm thời, cập nhật cấu trúc dữ liệu danh sách, sau đó gọi Py_DECREF() cho biến tạm thời.

Thay đổi trong phiên bản 3.12: Các vật thể bất tử không bị sửa đổi.

void Py_XDECREF(PyObject *o)

Tương tự như Py_DECREF(), nhưng đối tượng o có thể là NULL, trong trường hợp này điều này không có hiệu lực. Cảnh báo tương tự từ Py_DECREF() cũng được áp dụng ở đây.

void Py_CLEAR(PyObject *o)

Phát hành strong reference cho đối tượng o. Đối tượng có thể là NULL, trong trường hợp đó macro không có hiệu lực; mặt khác, hiệu ứng tương tự như đối với Py_DECREF(), ngoại trừ đối số cũng được đặt thành NULL. Cảnh báo cho Py_DECREF() không áp dụng đối với đối tượng được truyền vì macro sử dụng cẩn thận một biến tạm thời và đặt đối số thành NULL trước khi giải phóng tham chiếu.

Bạn nên sử dụng macro này bất cứ khi nào giải phóng một tham chiếu đến một đối tượng có thể được duyệt qua trong quá trình thu gom rác.

Thay đổi trong phiên bản 3.12: Đối số macro hiện chỉ được đánh giá một lần. Nếu đối số có tác dụng phụ thì những đối số này sẽ không còn bị trùng lặp nữa.

void Py_IncRef(PyObject *o)

Một phần của ABI ổn định.

Cho biết việc lấy một strong reference mới để đối tượng o. Một phiên bản chức năng của Py_XINCREF(). Nó có thể được sử dụng để nhúng động trong thời gian chạy của Python.

void Py_DecRef(PyObject *o)

Một phần của ABI ổn định.

Phát hành strong reference để đối tượng o. Một phiên bản chức năng của Py_XDECREF(). Nó có thể được sử dụng để nhúng động trong thời gian chạy của Python.

Py_SETREF(dst, src)

Macro giải phóng strong reference một cách an toàn để phản đối dst và đặt dst thành src.

Như trong trường hợp của Py_CLEAR(), mã "rõ ràng" có thể gây chết người:

Py_DECREF(dst);
dst = src;

Cách an toàn là:

Py_SETREF(dst, src);

Điều đó sắp xếp để đặt dst thành src before giải phóng tham chiếu đến giá trị cũ của dst, để bất kỳ mã nào được kích hoạt dưới dạng tác dụng phụ của việc dst bị phá bỏ sẽ không còn tin rằng dst trỏ đến một đối tượng hợp lệ.

Added in version 3.6.

Thay đổi trong phiên bản 3.12: Các đối số macro hiện chỉ được đánh giá một lần. Nếu một đối số có tác dụng phụ thì chúng sẽ không còn bị trùng lặp nữa.

Py_XSETREF(dst, src)

Biến thể của macro Py_SETREF sử dụng Py_XDECREF() thay vì Py_DECREF().

Added in version 3.6.

Thay đổi trong phiên bản 3.12: Các đối số macro hiện chỉ được đánh giá một lần. Nếu một đối số có tác dụng phụ thì chúng sẽ không còn bị trùng lặp nữa.