API پایش C

در نسخه 3.13 افزوده شد.

یک ماژول توسعه‌ای ممکن است نیاز به تعامل با سامانه پایش رویدادها داشته باشد. اشتراک در رویدادها و ثبت کال‌بک‌ها را می‌توان از طریق API پایتون ارائه‌شده در sys.monitoring انجام داد.

تولید رویدادهای اجرا

توابع زیر این امکان را فراهم می‌کنند که یک ماژول توسعه‌ای بتواند هنگام شبیه‌سازی اجرای کد پایتون، رویدادهای پایش را ایجاد کند. هر یک از این توابع یک ساختار PyMonitoringState را می‌پذیرد که اطلاعات مختصری درباره‌ی وضعیت فعال‌سازی رویدادها و همچنین آرگومان‌های رویداد را در بر دارد؛ این آرگومان‌ها شامل یک PyObject* که نمایانگر شیء کد است، آفست دستورالعمل و گاهی آرگومان‌های اضافی خاص رویداد هستند (برای جزئیات درباره‌ی امضاهای کال‌بک‌های مختلف رویداد به sys.monitoring مراجعه کنید). آرگومان codelike باید نمونه‌ای از types.CodeType یا از نوعی باشد که آن را شبیه‌سازی می‌کند.

ماشین مجازی هنگام فعال‌سازی رویداد، ردگیری را غیر‌فعال می‌کند، بنابراین نیازی نیست که کد کاربر این کار را انجام دهد.

توابع نظارت نباید در حالی که استثنایی تنظیم شده است فراخوانی شوند، به‌جز مواردی که در ادامه به‌عنوان توابعی که با استثنای جاری کار می‌کنند فهرست شده‌اند.

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)

رویداد PY_THROW را با استثنای فعلی (همان‌طور که PyErr_GetRaisedException() برمی‌گرداند) فعال می‌کند.

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

رویداد RAISE به همراه استثنای فعلی (همان‌طور که توسط PyErr_GetRaisedException() برگردانده می‌شود) شلیک می‌شود.

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

رویداد C_RAISE را همراه با استثنای فعلی (همان‌طور که توسط PyErr_GetRaisedException() برگردانده می‌شود) فعال می‌کند.

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

رویداد RERAISE را با استثنای فعلی (که توسط PyErr_GetRaisedException() برگردانده می‌شود) صادر می‌کند.

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

رویداد EXCEPTION_HANDLED را همراه با استثنای فعلی (که توسط PyErr_GetRaisedException() برگردانده می‌شود) فعال می‌کند.

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

رویداد PY_UNWIND را با استثنای فعلی (همان‌طور که توسط PyErr_GetRaisedException() برگردانده می‌شود) فعال کنید.

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

رویداد STOP_ITERATION را اجرا می‌کند. اگر value نمونه‌ای از StopIteration باشد، از آن استفاده می‌شود. در غیر این صورت، نمونه‌ی جدیدی از StopIteration با value به‌عنوان آرگومان آن ایجاد می‌شود.

مدیریت وضعیت پایش

وضعیت‌های نظارت را می‌توان با کمک محدوده‌های نظارت مدیریت کرد. یک محدوده معمولاً متناظر با یک تابع پایتون است.

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

ورود به یک محدوده‌ی پایش‌شده. event_types آرایه‌ای از شناسه‌های رویداد برای رویدادهایی است که ممکن است از این محدوده رخ دهند. برای مثال، شناسه‌ی رویداد PY_START مقدار PY_MONITORING_EVENT_PY_START است که از نظر عددی با لگاریتم پایه ۲ sys.monitoring.events.PY_START برابر است. state_array آرایه‌ای است که برای هر رویداد در event_types یک ورودی وضعیت پایش دارد؛ این آرایه توسط کاربر تخصیص داده می‌شود، اما توسط PyMonitoring_EnterScope() با اطلاعاتی درباره‌ی وضعیت فعال‌سازی رویداد پر می‌شود. اندازه‌ی event_types (و در نتیجه state_array نیز) در length داده می‌شود.

آرگومان version اشاره‌گری به مقداری است که باید توسط کاربر همراه با state_array تخصیص داده شود و به 0 مقداردهی اولیه گردد، و سپس تنها توسط خودِ PyMonitoring_EnterScope() تنظیم شود. این به تابع امکان می‌دهد تشخیص دهد که آیا وضعیت‌های رویداد از فراخوانی قبلی تغییر کرده‌اند یا خیر، و در صورت عدم تغییر، به‌سرعت بازگردد.

محدوده‌هایی که در اینجا به آن‌ها اشاره می‌شود، محدوده‌های واژگانی هستند: یک تابع، کلاس یا متد. هرگاه به محدوده واژگانی وارد می‌شود، باید 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)

اگر رویداد متناظر با شناسه‌ی رویداد ev یک رویداد محلی باشد، مقدار true برمی‌گرداند.

اضافه شده در نسخه‌ی 3.13.

منسوخ‌سازی نرم <Soft deprecated> از نسخه‌ی 3.14.