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

در پلتفرم‌های پشتیبانی‌شده (در زمان نگارش این متن، تنها لینوکس)، ران‌تایم می‌تواند از پرونده‌های نگاشت perf بهره بگیرد تا توابع پایتون برای یک ابزار پروفایل‌گیری خارجی (مانند perf) قابل مشاهده شوند. یک فرایند در حال اجرا ممکن است پرونده‌ای در پوشه‌ی /tmp ایجاد کند که حاوی ورودی‌هایی است که می‌توانند بخشی از کد اجرایی را به یک نام نگاشت کنند. این رابط در مستندات ابزار Linux Perf شرح داده شده است.

در پایتون، کتابخانه‌ها و قابلیت‌هایی که به تولید کد ماشین در لحظه وابسته‌اند، می‌توانند از این 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, unsigned int 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.