Hồ sơ và truy tìm

Trình thông dịch Python cung cấp một số hỗ trợ cấp thấp để đính kèm các phương tiện theo dõi thực thi và lập hồ sơ. Chúng được sử dụng cho các công cụ phân tích hồ sơ, gỡ lỗi và phân tích phạm vi bảo hiểm.

Giao diện C này cho phép mã định hình hoặc theo dõi tránh được chi phí gọi thông qua các đối tượng có thể gọi được ở cấp độ Python, thay vào đó thực hiện lệnh gọi hàm C trực tiếp. Các thuộc tính thiết yếu của cơ sở không thay đổi; giao diện cho phép cài đặt các hàm theo dõi trên mỗi luồng và các sự kiện cơ bản được báo cáo cho hàm theo dõi cũng giống như đã được báo cáo cho các hàm theo dõi cấp độ Python trong các phiên bản trước.

typedef int (*Py_tracefunc)(PyObject *obj, PyFrameObject *frame, int what, PyObject *arg)

Loại hàm theo dõi được đăng ký bằng PyEval_SetProfile() và PyEval_SetTrace(). Tham số đầu tiên là đối tượng được truyền cho hàm đăng ký dưới dạng obj, frame là đối tượng khung mà sự kiện liên quan đến, what là một trong các hằng số PyTrace_CALL, PyTrace_EXCEPTION, PyTrace_LINE, PyTrace_RETURN, PyTrace_C_CALL, PyTrace_C_EXCEPTION, PyTrace_C_RETURN hoặc PyTrace_OPCODE và arg tùy thuộc vào giá trị của what:

Giá trị của what	Ý nghĩa của arg
PyTrace_CALL	Luôn luôn Py_None.
PyTrace_EXCEPTION	Thông tin ngoại lệ được trả về bởi sys.exc_info().
PyTrace_LINE	Luôn luôn Py_None.
PyTrace_RETURN	Giá trị được trả về cho người gọi hoặc NULL nếu do ngoại lệ gây ra.
PyTrace_C_CALL	Đối tượng chức năng đang được gọi.
PyTrace_C_EXCEPTION	Đối tượng chức năng đang được gọi.
PyTrace_C_RETURN	Đối tượng chức năng đang được gọi.
PyTrace_OPCODE	Luôn luôn Py_None.

int PyTrace_CALL

Giá trị của tham số what đối với hàm Py_tracefunc khi một lệnh gọi mới đến một hàm hoặc phương thức đang được báo cáo hoặc một mục nhập mới vào trình tạo. Lưu ý rằng việc tạo trình vòng lặp cho hàm tạo không được báo cáo vì không có chuyển điều khiển sang mã byte Python trong khung tương ứng.

int PyTrace_EXCEPTION

Giá trị của tham số what cho hàm Py_tracefunc khi có ngoại lệ được đưa ra. Hàm gọi lại được gọi với giá trị này cho what khi sau khi bất kỳ mã byte nào được xử lý, sau đó ngoại lệ sẽ được đặt trong khung đang được thực thi. Tác dụng của việc này là khi việc truyền bá ngoại lệ làm cho ngăn xếp Python bị giãn ra, lệnh gọi lại sẽ được gọi khi quay trở lại từng khung khi ngoại lệ lan truyền. Chỉ các chức năng theo dõi mới nhận được những sự kiện này; người lập hồ sơ không cần chúng.

int PyTrace_LINE

Giá trị được truyền dưới dạng tham số what cho hàm Py_tracefunc (nhưng không phải là hàm lược tả) khi sự kiện số dòng được báo cáo. Nó có thể bị vô hiệu hóa đối với một khung bằng cách đặt f_trace_lines thành 0 trên khung đó.

int PyTrace_RETURN

Giá trị của tham số what cho Py_tracefunc hoạt động khi có cuộc gọi sắp quay trở lại.

int PyTrace_C_CALL

Giá trị của tham số what cho các hàm Py_tracefunc khi hàm C sắp được gọi.

int PyTrace_C_EXCEPTION

Giá trị của tham số what cho các hàm Py_tracefunc khi hàm C đưa ra một ngoại lệ.

int PyTrace_C_RETURN

Giá trị của tham số what cho các hàm Py_tracefunc khi hàm C trả về.

int PyTrace_OPCODE

Giá trị của tham số what cho các hàm Py_tracefunc (nhưng không phải các hàm lược tả) khi một opcode mới sắp được thực thi. Sự kiện này không được phát ra theo mặc định: nó phải được yêu cầu rõ ràng bằng cách đặt f_trace_opcodes thành 1 trên khung.

void PyEval_SetProfile(Py_tracefunc func, PyObject *obj)

Đặt chức năng hồ sơ thành func. Tham số obj được truyền cho hàm làm tham số đầu tiên và có thể là bất kỳ đối tượng Python nào hoặc NULL. Nếu hàm hồ sơ cần duy trì trạng thái, việc sử dụng một giá trị khác cho obj cho mỗi luồng sẽ cung cấp một nơi thuận tiện và an toàn cho luồng để lưu trữ nó. Chức năng hồ sơ được gọi cho tất cả các sự kiện được giám sát ngoại trừ PyTrace_LINE PyTrace_OPCODE và PyTrace_EXCEPTION.

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

Người gọi phải có attached thread state.

void PyEval_SetProfileAllThreads(Py_tracefunc func, PyObject *obj)

Giống như PyEval_SetProfile() nhưng đặt chức năng cấu hình trong tất cả các luồng đang chạy thuộc trình thông dịch hiện tại thay vì chỉ cài đặt nó trên luồng hiện tại.

Người gọi phải có attached thread state.

Giống như PyEval_SetProfile(), chức năng này bỏ qua mọi trường hợp ngoại lệ được đưa ra trong khi thiết lập các chức năng cấu hình trong tất cả các luồng.

Added in version 3.12.

void PyEval_SetTrace(Py_tracefunc func, PyObject *obj)

Đặt chức năng theo dõi thành func. Điều này tương tự như PyEval_SetProfile(), ngoại trừ chức năng theo dõi nhận các sự kiện số dòng và sự kiện trên mỗi mã opcode, nhưng không nhận bất kỳ sự kiện nào liên quan đến đối tượng hàm C đang được gọi. Bất kỳ hàm theo dõi nào được đăng ký bằng PyEval_SetTrace() sẽ không nhận được PyTrace_C_CALL, PyTrace_C_EXCEPTION hoặc PyTrace_C_RETURN làm giá trị cho tham số what.

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

Người gọi phải có attached thread state.

void PyEval_SetTraceAllThreads(Py_tracefunc func, PyObject *obj)

Giống như PyEval_SetTrace() nhưng đặt chức năng theo dõi trong tất cả các luồng đang chạy thuộc trình thông dịch hiện tại thay vì chỉ cài đặt nó trên luồng hiện tại.

Người gọi phải có attached thread state.

Giống như PyEval_SetTrace(), hàm này bỏ qua mọi ngoại lệ được nêu ra trong khi thiết lập các hàm theo dõi trong tất cả các luồng.

Added in version 3.12.

Truy tìm tham chiếu

Added in version 3.13.

typedef int (*PyRefTracer)(PyObject*, int event, void *data)

Loại hàm theo dõi được đăng ký bằng PyRefTracer_SetTracer(). Tham số đầu tiên là một đối tượng Python vừa được tạo (khi event được đặt thành PyRefTracer_CREATE) hoặc sắp bị hủy (khi event được đặt thành PyRefTracer_DESTROY). Đối số data là con trỏ mờ được cung cấp khi PyRefTracer_SetTracer() được gọi.

Nếu một chức năng theo dõi mới được đăng ký thay thế chức năng theo dõi hiện tại, lệnh gọi hàm theo dõi sẽ được thực hiện với đối tượng được đặt thành NULL và event được đặt thành PyRefTracer_TRACKER_REMOVED. Điều này sẽ xảy ra ngay trước khi chức năng mới được đăng ký.

Added in version 3.13.

int PyRefTracer_CREATE

Giá trị của tham số event cho hàm PyRefTracer khi đối tượng Python được tạo.

int PyRefTracer_DESTROY

Giá trị của tham số event cho PyRefTracer hoạt động khi một đối tượng Python đã bị hủy.

int PyRefTracer_TRACKER_REMOVED

Giá trị của tham số event cho PyRefTracer hoạt động khi bộ theo dõi hiện tại sắp được thay thế bằng một bộ theo dõi mới.

Added in version 3.14.

int PyRefTracer_SetTracer(PyRefTracer tracer, void *data)

Đăng ký chức năng theo dõi tham chiếu. Hàm sẽ được gọi khi một đối tượng Python mới được tạo hoặc khi một đối tượng sắp bị hủy. Nếu data được cung cấp thì nó phải là một con trỏ mờ sẽ được cung cấp khi hàm theo dõi được gọi. Trả về 0 khi thành công. Đặt một ngoại lệ và trả về -1 khi có lỗi.

Lưu ý rằng các hàm theo dõi must not tạo các đối tượng Python bên trong nếu không lệnh gọi sẽ được thực hiện lại. Trình theo dõi cũng must not xóa mọi ngoại lệ hiện có hoặc đặt ngoại lệ. Một thread state sẽ hoạt động mỗi khi chức năng theo dõi được gọi.

Phải có attached thread state khi gọi hàm này.

Nếu một hàm theo dõi khác đã được đăng ký thì hàm cũ sẽ được gọi với event được đặt thành PyRefTracer_TRACKER_REMOVED ngay trước khi hàm mới được đăng ký.

Added in version 3.13.

PyRefTracer PyRefTracer_GetTracer(void **data)

Nhận hàm theo dõi tham chiếu đã đăng ký và giá trị của con trỏ dữ liệu mờ đã được đăng ký khi PyRefTracer_SetTracer() được gọi. Nếu không có dấu vết nào được đăng ký, hàm này sẽ trả về NULL và sẽ đặt con trỏ data thành NULL.

Phải có attached thread state khi gọi hàm này.

Added in version 3.13.