پشتیبانی از Perf Maps

On supported platforms (Linux and macOS), the runtime can take advantage of perf map files to make Python functions visible to an external profiling tool (such as perf or samply). A running process may create a file in the /tmp directory, which contains entries that can map a section of executable code to a name. This interface is described in the documentation of the Linux Perf tool.

در پایتون، کتابخانه‌ها و قابلیت‌هایی که به تولید کد ماشین در لحظه وابسته‌اند، می‌توانند از این APIهای کمکی استفاده کنند.

توجه داشته باشید که نگه‌داشتن attached thread state برای این API‌ها الزامی نیست.

int PyUnstable_PerfMapState_Init(void)

این است API ناپایداراین ممکن است بدون هشدار در نسخه‌های جزئی تغییر کند.

پرونده‌ی /tmp/perf-$pid.map را باز کنید، مگر اینکه از قبل باز شده باشد، و یک قفل ایجاد کنید تا نوشتن در پرونده به‌صورت نخ‌ایمن تضمین شود (به شرطی که نوشتن‌ها از طریق PyUnstable_WritePerfMapEntry() انجام شوند). معمولاً نیازی به فراخوانی صریح آن نیست؛ کافی است از PyUnstable_WritePerfMapEntry() استفاده کنید و این تابع وضعیت را در نخستین فراخوانی مقداردهی اولیه می‌کند.

در صورت موفقیت مقدار 0، در صورت شکست در ایجاد/باز کردن پرونده‌ی perf map مقدار -1 و در صورت شکست در ایجاد قفل مقدار -2 را برمی‌گرداند. برای کسب اطلاعات بیشتر درباره‌ی علت شکست، errno را بررسی کنید.

int PyUnstable_WritePerfMapEntry(const void *code_addr, size_t code_size, const char *entry_name)

این است API ناپایداراین ممکن است بدون هشدار در نسخه‌های جزئی تغییر کند.

یک ورودی واحد را در پرونده‌ی /tmp/perf-$pid.map می‌نویسد. این تابع نخ‌ایمن است. نمونه‌ای از یک ورودی به شکل زیر است:

# address      size  name
7f3529fcf759 b     py::bar:/run/t.py

اگر پرونده‌ی perf map از قبل باز نشده باشد، پیش از نوشتن ورودی، PyUnstable_PerfMapState_Init() فراخوانی می‌شود. در صورت موفقیت 0 و در صورت شکست، همان کدهای خطای PyUnstable_PerfMapState_Init() را برمی‌گرداند.

void PyUnstable_PerfMapState_Fini(void)

این است API ناپایداراین ممکن است بدون هشدار در نسخه‌های جزئی تغییر کند.

پرونده‌ی نقشه‌ی perf (perf map) باز‌شده توسط PyUnstable_PerfMapState_Init() را می‌بندد. این تابع توسط خودِ ران‌تایم در زمان خاموشی مفسر فراخوانی می‌شود. به‌طور کلی، نباید دلیلی برای فراخوانی صریح آن وجود داشته باشد، مگر برای مدیریت سناریوهای خاص مانند انشعاب.

int PyUnstable_CopyPerfMapFile(const char *parent_filename)

این است API ناپایداراین ممکن است بدون هشدار در نسخه‌های جزئی تغییر کند.

پرونده‌ی /tmp/perf-$pid.map را باز کنید و محتوای parent_filename را به آن الحاق کنید.

این تابع در همه‌ی پلتفرم‌ها دسترس‌پذیر است، اما تنها در پلتفرم‌هایی که از نقشه‌های perf (perf maps) پشتیبانی می‌کنند (در حال حاضر فقط لینوکس) خروجی تولید می‌کند. در پلتفرم‌های دیگر، هیچ کاری انجام نمی‌دهد.

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

int PyUnstable_PerfTrampoline_CompileCode(PyCodeObject *code)

این است API ناپایداراین ممکن است بدون هشدار در نسخه‌های جزئی تغییر کند.

شیء کد داده‌شده را با استفاده از ترامپولین فعلی perf کامپایل کنید.

ترامپولین «جاری» همان ترامپولینی است که توسط ران‌تایم یا جدیدترین فراخوانی PyUnstable_PerfTrampoline_SetPersistAfterFork() تنظیم‌شده است.

اگر هیچ ترامپولینی تنظیم‌نشده باشد، به کامپایل عادی بازمی‌گردد (بدون ورودی در نقشه‌ی perf).

پارامترها:

• code -- شیء کدی که باید کامپایل شود.

بازگشت ها:

0 در صورت موفقیت، -1 در صورت شکست.

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

int PyUnstable_PerfTrampoline_SetPersistAfterFork(int enable)

این است API ناپایداراین ممکن است بدون هشدار در نسخه‌های جزئی تغییر کند.

تعیین می‌کند که آیا ترامپولین perf باید پس از فورک پایا بماند یا خیر.

• اگر enable درست (ناصفر) باشد: پرونده‌ی perf map پس از انشعاب باز/معتبر باقی می‌ماند. فرایند فرزند تمام ورودی‌های موجود perf map را به ارث می‌برد.

• اگر enable نادرست (صفر) باشد: نقشه perf (perf map) پس از انشعاب بسته می‌شود. فرایند فرزند نقشه perf خالی دریافت می‌کند.

پیش‌فرض: false (هنگام انشعاب پاک می‌شود).

پارامترها:

• enable -- ۱ برای فعال‌سازی، ۰ برای غیرفعال‌سازی.

بازگشت ها:

0 در صورت موفقیت، -1 در صورت شکست.

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