☰ Menu Python

☰ Menu

모니터링 C API

버전 3.13에서 추가되었습니다.

확장 모듈은 이벤트 모니터링 시스템과 상호작용해야 할 수도 있습니다. sys.monitoring 에 노출된 파이썬 API를 통해 이벤트 구독 및 콜백 등록을 수행할 수 있습니다.

실행 이벤트 생성

아래 함수들은 확장 모듈이 파이썬 코드의 실행을 에뮬레이트할 때 모니터링 이벤트를 발생시킬 수 있게 합니다. 이 함수들은 각각 이벤트의 활성화 상태에 대한 간결한 정보와 이벤트 인자(코드 객체를 나타내는 PyObject*, 명령 오프셋 및 때로는 특정 이벤트 전용 추가 인자를 포함)를 포함하는 PyMonitoringState 구조체를 인자로 받습니다 (다양한 이벤트 콜백의 시그니처에 대한 자세한 내용은 sys.monitoring`을 참조하십시오). ``codelike` 인자는 types.CodeType 인스턴스 또는 이를 에뮬레이트하는 타입이어야 합니다.

VM은 이벤트를 발생시킬 때 추적을 비활성화하므로, 사용자 코드가 이를 수행할 필요가 없습니다.

현재 예외와 함께 작동하는 것으로 아래에 나열된 함수들을 제외하고는 모니터링 함수를 호출할 때 예외가 설정되어 있어서는 안 됩니다.

type PyMonitoringState

이벤트 유형의 상태를 나타내는 표현입니다. 사용자가 할당하며, 그 내용은 아래 설명된 모니터링 API 함수들에 의해 유지됩니다.

아래의 모든 함수는 성공 시 0을 반환하고, 오류 시 예외를 설정하며 -1을 반환합니다.

이벤트에 대한 설명은 sys.monitoring 을 참조하십시오.

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

PY_START 이벤트를 발생시킵니다.

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

PY_RESUME 이벤트를 발생시킵니다.

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

PY_RETURN 이벤트를 발생시킵니다.

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

PY_YIELD 이벤트를 발생시킵니다.

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

CALL 이벤트를 발생시킵니다.

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

LINE 이벤트를 발생시킵니다.

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

JUMP 이벤트를 발생시킵니다.

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

BRANCH_LEFT 이벤트를 발생시킵니다.

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

BRANCH_RIGHT 이벤트를 발생시킵니다.

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

C_RETURN 이벤트를 발생시킵니다.

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

현재 예외( PyErr_GetRaisedException() 이 반환하는 값)와 함께 PY_THROW 이벤트를 발생시킵니다.

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

현재 예상( PyErr_GetRaisedException() 이 반환하는 값)와 함께 RAISE 이벤트를 발생시킵니다.

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

현재 예상( PyErr_GetRaisedException() 이 반환하는 값)와 함께 C_RAISE 이벤트를 발생시킵니다.

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

현재 예상( PyErr_GetRaisedException() 이 반환하는 값)와 함께 RERAISE 이벤트를 발생시킵니다.

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

현재 예상( PyErr_GetRaisedException() 이 반환하는 값)와 함께 EXCEPTION_HANDLED 이벤트를 발생시킵니다.

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

현재 예상( PyErr_GetRaisedException() 이 반환하는 값)와 함께 PY_UNWIND 이벤트를 발생시킵니다.

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

STOP_ITERATION 이벤트를 발생시킵니다. value 가 StopIteration 인스턴스인 경우 이를 사용하며, 그렇지 않은 경우에는 value 를 인자로 하여 새로운 StopIteration 인스턴스를 생성합니다.

모니터링 상태 관리

모니터링 상태는 모니터링 범위를 통해 관리할 수 있습니다. 범위(scope)는 일반적으로 파이썬 함수에 대응됩니다.

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

모니터링 범위에 진입합니다. event_types 는 해당 범위에서 발생할 수 있는 이벤트들의 ID 배열입니다. 예를 들어, PY_START 이벤트의 ID는 PY_MONITORING_EVENT_PY_START 값이며, 이는 sys.monitoring.events.PY_START 의 밑이 2인 로그 값과 수치적으로 동일합니다. state_array 는 event_types 에 포함된 각 이벤트에 대한 모니터링 상태 항목을 가진 배열로, 사용자가 할당하며 PyMonitoring_EnterScope() 가 해당 이벤트의 활성화 상태 정보를 채웁니다. event_types (및 결과적으로 state_array)의 크기는 length 에 명시됩니다.

version 인자는 사용자가 state_array 와 함께 할당하고 0으로 초기화해야 하는 값에 대한 포인터이며, 이후 PyMonitoring_EnterScope() 자체에 의해서만 설정됩니다. 이를 통해 이 함수는 이전 호출 이후 이벤트 상태가 변경되었는지 판단하고, 변경되지 않았다면 빠르게 반환할 수 있습니다.

여기에서 언급하는 범위는 어휘적 범위(lexical scopes)인 함수, 클래스 또는 메서드를 의미합니다. 해당 어휘적 범위에 진입할 때마다 PyMonitoring_EnterScope() 를 호출해야 합니다. 재귀적인 파이썬 함수를 에뮬레이션하는 경우와 같이 동일한 state_array 및 version 을 재사용하며 같은 범위에 다시 진입할 수 있습니다. 제너레이터를 에뮬레이션하는 경우처럼 코드 유사(code-like)의 실행이 일시 중지될 때는 범위를 나가고 다시 들어와야 합니다.

event_types 에 대한 매크로는 다음과 같습니다:

매크로	이벤트
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)

PyMonitoring_EnterScope() 로 진입했던 마지막 범위를 나갑니다.

int PY_MONITORING_IS_INSTRUMENTED_EVENT(uint8_t ev)

이벤트 ID ev 에 해당하는 이벤트가 로컬 이벤트 인 경우 True를 반환합니다.

Added in version 3.13.

버전 3.14부터 약하게 폐지 <Soft deprecated>.