Giám sát C API

Đã thêm vào phiên bản 3.13.

Tiện ích mở rộng có thể cần tương tác với hệ thống giám sát sự kiện. Việc đăng ký sự kiện và đăng ký lệnh gọi lại có thể được thực hiện thông qua API Python được hiển thị trong sys.monitoring.

Tạo sự kiện thực thi

Các hàm bên dưới giúp tiện ích mở rộng có thể kích hoạt các sự kiện giám sát khi nó mô phỏng quá trình thực thi mã Python. Mỗi hàm này chấp nhận một cấu trúc PyMonitoringState chứa thông tin ngắn gọn về trạng thái kích hoạt của các sự kiện, cũng như các đối số sự kiện, bao gồm một PyObject* đại diện cho đối tượng mã, offset lệnh và đôi khi là các đối số bổ sung, dành riêng cho sự kiện (xem sys.monitoring để biết chi tiết về chữ ký của các lệnh gọi lại sự kiện khác nhau). Đối số codelike phải là một phiên bản của types.CodeType hoặc thuộc loại mô phỏng nó.

VM vô hiệu hóa việc theo dõi khi kích hoạt một sự kiện, do đó không cần mã người dùng để thực hiện việc đó.

Không nên gọi các chức năng giám sát với một bộ ngoại lệ, ngoại trừ những chức năng được liệt kê bên dưới hoạt động với ngoại lệ hiện tại.

type PyMonitoringState

Biểu diễn trạng thái của một loại sự kiện. Nó được người dùng phân bổ trong khi nội dung của nó được duy trì bởi các chức năng giám sát API được mô tả bên dưới.

Tất cả các hàm bên dưới trả về 0 nếu thành công và -1 (với một bộ ngoại lệ) nếu có lỗi.

Xem sys.monitoring để biết mô tả về các sự kiện.

int PyMonitoring_FirePyStartEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset)

Kích hoạt sự kiện PY_START.

int PyMonitoring_FirePyResumeEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset)

Kích hoạt sự kiện PY_RESUME.

int PyMonitoring_FirePyReturnEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset, PyObject *retval)

Kích hoạt sự kiện PY_RETURN.

int PyMonitoring_FirePyYieldEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset, PyObject *retval)

Kích hoạt sự kiện PY_YIELD.

int PyMonitoring_FireCallEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset, PyObject *callable, PyObject *arg0)

Kích hoạt sự kiện CALL.

int PyMonitoring_FireLineEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset, int lineno)

Kích hoạt sự kiện LINE.

int PyMonitoring_FireJumpEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset, PyObject *target_offset)

Kích hoạt sự kiện JUMP.

int PyMonitoring_FireBranchLeftEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset, PyObject *target_offset)

Kích hoạt sự kiện BRANCH_LEFT.

int PyMonitoring_FireBranchRightEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset, PyObject *target_offset)

Kích hoạt sự kiện BRANCH_RIGHT.

int PyMonitoring_FireCReturnEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset, PyObject *retval)

Kích hoạt sự kiện C_RETURN.

int PyMonitoring_FirePyThrowEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset)

Kích hoạt sự kiện PY_THROW với ngoại lệ hiện tại (được trả về bởi PyErr_GetRaisedException()).

int PyMonitoring_FireRaiseEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset)

Kích hoạt sự kiện RAISE với ngoại lệ hiện tại (được trả về bởi PyErr_GetRaisedException()).

int PyMonitoring_FireCRaiseEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset)

Kích hoạt sự kiện C_RAISE với ngoại lệ hiện tại (được trả về bởi PyErr_GetRaisedException()).

int PyMonitoring_FireReraiseEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset)

Kích hoạt sự kiện RERAISE với ngoại lệ hiện tại (được trả về bởi PyErr_GetRaisedException()).

int PyMonitoring_FireExceptionHandledEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset)

Kích hoạt một sự kiện EXCEPTION_HANDLED với ngoại lệ hiện tại (được trả về bởi PyErr_GetRaisedException()).

int PyMonitoring_FirePyUnwindEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset)

Kích hoạt sự kiện PY_UNWIND với ngoại lệ hiện tại (được trả về bởi PyErr_GetRaisedException()).

int PyMonitoring_FireStopIterationEvent(PyMonitoringState *state, PyObject *codelike, int32_t offset, PyObject *value)

Kích hoạt sự kiện STOP_ITERATION. Nếu value là một phiên bản của StopIteration thì nó sẽ được sử dụng. Nếu không, một phiên bản StopIteration mới sẽ được tạo với value làm đối số.

Quản lý trạng thái giám sát

Các trạng thái giám sát có thể được quản lý với sự trợ giúp của phạm vi giám sát. Một phạm vi thường tương ứng với một hàm Python.

int PyMonitoring_EnterScope(PyMonitoringState *state_array, uint64_t *version, const uint8_t *event_types, Py_ssize_t length)

Nhập phạm vi được giám sát. event_types là một mảng ID sự kiện cho các sự kiện có thể được kích hoạt từ phạm vi. Ví dụ: ID của sự kiện PY_START là giá trị PY_MONITORING_EVENT_PY_START, bằng số với logarit cơ số 2 của sys.monitoring.events.PY_START. state_array là một mảng có mục nhập trạng thái giám sát cho từng sự kiện trong event_types. Nó được người dùng phân bổ nhưng được PyMonitoring_EnterScope() cung cấp thông tin về trạng thái kích hoạt của sự kiện. Kích thước của event_types (và do đó cũng là state_array) được đưa ra trong length.

Đối số version là một con trỏ tới một giá trị sẽ được người dùng phân bổ cùng với state_array và được khởi tạo thành 0, sau đó chỉ được đặt bởi chính PyMonitoring_EnterScope(). Nó cho phép hàm này xác định xem trạng thái sự kiện có thay đổi kể từ lệnh gọi trước hay không và nhanh chóng quay lại nếu không.

Các phạm vi được đề cập ở đây là phạm vi từ vựng: một hàm, lớp hoặc phương thức. PyMonitoring_EnterScope() nên được gọi bất cứ khi nào phạm vi từ vựng được nhập. Các phạm vi có thể được nhập lại, sử dụng lại cùng một state_array và version, trong các tình huống như khi mô phỏng hàm Python đệ quy. Khi quá trình thực thi của mã giống bị tạm dừng, chẳng hạn như khi mô phỏng trình tạo, phạm vi cần phải được thoát và nhập lại.

Các macro cho event_types là:

Vĩ mô	Sự kiện
PY_MONITORING_EVENT_BRANCH_LEFT	BRANCH_LEFT
PY_MONITORING_EVENT_BRANCH_RIGHT	BRANCH_RIGHT
PY_MONITORING_EVENT_CALL	CALL
PY_MONITORING_EVENT_C_RAISE	C_RAISE
PY_MONITORING_EVENT_C_RETURN	C_RETURN
PY_MONITORING_EVENT_EXCEPTION_HANDLED	EXCEPTION_HANDLED
PY_MONITORING_EVENT_INSTRUCTION	INSTRUCTION
PY_MONITORING_EVENT_JUMP	JUMP
PY_MONITORING_EVENT_LINE	LINE
PY_MONITORING_EVENT_PY_RESUME	PY_RESUME
PY_MONITORING_EVENT_PY_RETURN	PY_RETURN
PY_MONITORING_EVENT_PY_START	PY_START
PY_MONITORING_EVENT_PY_THROW	PY_THROW
PY_MONITORING_EVENT_PY_UNWIND	PY_UNWIND
PY_MONITORING_EVENT_PY_YIELD	PY_YIELD
PY_MONITORING_EVENT_RAISE	RAISE
PY_MONITORING_EVENT_RERAISE	RERAISE
PY_MONITORING_EVENT_STOP_ITERATION	STOP_ITERATION

int PyMonitoring_ExitScope(void)

Thoát khỏi phạm vi cuối cùng được nhập bằng PyMonitoring_EnterScope().

int PY_MONITORING_IS_INSTRUMENTED_EVENT(uint8_t ev)

Trả về true nếu sự kiện tương ứng với ID sự kiện ev là local event.

Added in version 3.13.

Sắp loại bỏ từ phiên bản 3.14: Chức năng này là soft deprecated.