نام (NAME)

gprofng-display-text - نمایش دادههای کارایی در قالب متن ساده

خلاصه دستور (SYNOPSIS)

gprofng display text [گزینه‌ها] [دستورات] [-script script-file] experiment(s)

توضیحات (DESCRIPTION)

چاپ نسخه متن ساده (Plain Text) از نماهای گوناگون پشتیبانی‌شده توسط gprofng.

ورودی شامل یک یا چند دایرکتوری آزمایش است. کاربر خروجی را از طریق دستورات کنترل می‌کند.

مجموعه کاملی از دستورات برای کنترل نحوه نمایش داده‌ها وجود دارد. بخش نکات (NOTES) رایج‌ترین آن‌ها را فهرست کرده است. راهنمای کاربری gprofng تمام دستورات پشتیبانی‌شده را فهرست می‌کند.

دستوراتی که در خط فرمان تعیین می‌شوند باید با نماد خط تیره ('-') شروع شوند.

در این مثال، یک نمای کلی از توابع نشان داده خواهد شد و به دنبال آن، فهرست کد منبع تابع my-func به همراه سنجه‌های کارایی که در حین گردآوری داده‌ها ثبت شده و در دایرکتوری آزمایش my-exp.er ذخیره شده‌اند، نمایش می‌یابد:

$ gprofng display text -functions -source my-func my-exp.er

به‌جای تعیین این دستورات در خط فرمان، یا علاوه بر آن، می‌توان دستورات را در فایلی به نام script-file قرار داد.

توجه داشته باشید که دستورات از چپ به راست پردازش و تفسیر می‌شوند، بنابراین ترتیب آن‌ها مهم است.

اگر این ابزار بدون گزینه، دستور یا فایل اسکریپت اجرا شود، در حالت مفسر (Interpreter) آغاز به کار می‌کند. در این حالت کاربر می‌تواند دستورات را به‌صورت تعاملی اجرا کند. نشست تعاملی با دستور exit در مفسر به پایان می‌رسد.

گزینه‌ها (OPTIONS)

--version: نمایش شماره نسخه برنامه و خروج.
--help: نمایش اطلاعات نحوه استفاده از دستور و خروج.
-script script-file: اجرای دستورات ذخیره‌شده در فایل اسکریپت. این قابلیت می‌تواند با دستورات مشخص‌شده در خط فرمان ترکیب شود.

نکات (NOTES)

دستورات متعددی پشتیبانی می‌شوند. در ادامه، دستورات پرکاربردتر به‌صورت تقریباً الفبایی فهرست شده‌اند، زیرا در برخی موارد جابجا کردن ترتیب دو مورد منطقی‌تر است.

دستورات بسیار بیشتری وجود دارند که در راهنمای کاربری مستند شده‌اند.

"callers-callees": در یک پانل callers-callees نشان داده می‌شود که چه تابعی یا توابعی تابع هدف را فراخوانی می‌کنند (فراخوان‌ها یا callers) و تابع هدف چه توابعی را فراخوانی می‌کند (فراخوانده‌ها یا callees). این دستور پانل callers-callees را برای هر یک از توابع، به ترتیبی که توسط سنجه مرتب‌سازی توابع تعیین شده است، چاپ می‌کند.
"calltree": نمایش گراف فراخوانی پویا (Dynamic Call Graph) از آزمایش، که سنجه‌های سلسله‌مراتبی را در هر سطح نشان می‌دهد.
"compare {on | off | delta | ratio}": به‌طور پیش‌فرض، نتایج چند آزمایش با یکدیگر تجمیع می‌شوند. این دستور این رفتار را تغییر می‌دهد تا مقایسه آزمایش‌ها برای نماهای مشخصی (مانند نمای توابع) امکان‌پذیر شود. نخستین آزمایش مشخص‌شده به عنوان مرجع (Reference) تعریف می‌شود. گزینه‌های زیر پشتیبانی می‌شوند:

"on": برای هر آزمایشی که در خط فرمان تعیین شده است، مقادیر سنجه‌هایی که برای آن آزمایش فعال شده‌اند را چاپ می‌کند.
"off": غیرفعال کردن مقایسه آزمایش‌ها. این حالت پیش‌فرض است.
"delta": چاپ مقادیر برای آزمایش مرجع. نتایج سایر آزمایش‌ها به‌صورت تفاضل نسبت به مرجع (current-reference) نشان داده می‌شوند.
"ratio": چاپ مقادیر برای آزمایش مرجع. نتایج سایر آزمایش‌ها به‌صورت نسبت در مقایسه با مرجع (current/reference) نشان داده می‌شوند.

"disasm function-name"

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

"fsingle function-name [n]"

نوشتن یک پانل خلاصه برای تابع مشخص‌شده. پارامتر اختیاری n برای مواردی لازم است که چندین تابع نام یکسانی دارند.

"fsummary"

نوشتن یک پانل خلاصه برای هر یک از توابع در فهرست توابع.

"functions"

نمایش فهرستی از تمام توابع اجراشده. برای هر تابع، سنجه‌های به‌کاررفته (مانند زمان پردازنده) نشان داده می‌شوند.

"header"

نمایش ویژگی‌های عملیاتی گوناگون از آزمایش(های) تعیین‌شده در خط فرمان.

"limit n"

محدود کردن خروجی به n خط.

"lines"

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

"metric_list"

نمایش سنجه‌های انتخاب‌شده فعلی در نمای توابع و فهرستی از تمام سنجه‌های موجود برای آزمایش(های) هدف.

"metrics metric-spec"

تعریف سنجه‌هایی که باید در نماهای کلی توابع و callers-callees نمایش داده شوند.

شناسه metric-spec می‌تواند کلیدواژه default برای بازگردانی انتخاب پیش‌فرض سنجه‌ها، یا فهرستی از سنجه‌ها که با دونقطه از هم جدا شده‌اند باشد.

یک سنجه ویژه "hwc" است. این سنجه به‌طور خودکار به مجموعه فعال شمارنده‌های رویداد سخت‌افزاری که در آزمایش(ها) استفاده شده‌اند بسط می‌یابد.

اگر هم دستورالعمل‌ها و هم چرخه‌های ساعت اندازه‌گیری شده باشند، می‌توان از سنجه‌های "CPI" و "IPC" به ترتیب برای مشاهده مقادیر چرخه‌های ساعت به ازای هر دستورالعمل (Clockcycles Per Instruction) و دستورالعمل‌ها به ازای هر چرخه ساعت (Instructions Per Clockcycle) استفاده کرد.

راهنمای کاربری gprofng جزئیات بیشتری درباره نحوه تعریف سنجه‌ها دارد.

"name {short | long | mangled}[:{soname | nosoname}]"

تعیین اینکه آیا فرم کوتاه، بلند یا درهم‌ریخته (mangled) برای نام‌های توابع استفاده شود. به‌صورت اختیاری، شیء بارگذاری‌شده‌ای که تابع بخشی از آن است می‌تواند با افزودن کلیدواژه soname در خروجی گنجانده شود. همچنین می‌توان آن را حذف کرد (nosoname) که حالت پیش‌فرض است.

اینکه آیا تفاوت واقعی میان این انواع نام وجود دارد یا خیر، به زبان برنامه‌نویسی بستگی دارد.

توجه داشته باشید که در سمت چپ و راست دونقطه (:) نباید هیچ فاصله یا نویسه خالی وجود داشته باشد.

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

"overview"

نمایش خلاصه‌ای از داده‌های کارایی ثبت‌شده برای آزمایش(های) مشخص‌شده در خط فرمان.

"pcs"

نوشتن فهرستی از شمارنده‌های برنامه (PCها) و سنجه‌های آن‌ها، مرتب‌شده بر اساس سنجه مرتب‌سازی فعلی.

"sort metric-spec"

مرتب‌سازی فهرست توابع بر اساس metric-spec داده‌شده.

@IndexSubentry{Sort, Reverse order} داده‌ها را می‌توان با افزودن یک علامت منفی (-) به ابتدای تعریف سنجه، به ترتیب معکوس مرتب کرد.

برای مثال sort -e.totalcpu.

@IndexSubentry{Sort, Reset to default} یک سنجه پیش‌فرض برای عملیات مرتب‌سازی تعریف شده است و از آنجا که این یک دستور پایدار است، این حالت پیش‌فرض را می‌توان با کلید "default" بازیابی کرد (sort default).

"source function-name"

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

"viewmode {user | expert | machine}"

این دستور فقط برای برنامه‌های جاوا کاربرد دارد. برای تمام زبان‌های پشتیبانی‌شده دیگر، تنظیمات viewmode هیچ تاثیری ندارد.

گزینه‌های زیر پشتیبانی می‌شوند:

"user": نمایش پشته‌های فراخوانی جاوا برای ریسه‌های جاوا، اما بدون نمایش ریسه‌های نگهداری سیستم (Housekeeping Threads). نمای توابع شامل تابعی به نام <JVM-System> است. این تابع نشان‌دهنده زمان تجمیع‌شده از ریسه‌های غیرجاوا است. در صورتی که نرم‌افزار JVM پشته فراخوانی جاوا را گزارش نکند، زمان برای تابع <no Java callstack recorded> گزارش می‌شود.
"expert": هنگام اجرای کد جاوای کاربر، پشته‌های فراخوانی جاوا را برای ریسه‌های جاوا نمایش می‌دهد، و هنگام اجرای کد JVM، یا در حالتی که نرم‌افزار JVM پشته فراخوانی جاوا را گزارش نمی‌کند، پشته‌های فراخوانی ماشین را نمایش می‌دهد. همچنین پشته‌های فراخوانی ماشین را برای ریسه‌های نگهداری سیستم نمایش می‌دهد.
"machine": نمایش پشته‌های فراخوانی بومی واقعی (Native Call Stacks) برای تمام ریسه‌ها. این حالت نما برای زبان‌های C، C++‎ و Fortran است.

همچنین ببینید (SEE ALSO)

gprofng(1), gprofng-archive(1), gprofng-collect-app(1), gprofng-display-html(1), gprofng-display-src(1)

راهنمای کاربری gprofng به عنوان کتابچه راهنمای Texinfo نگهداری می‌شود. اگر برنامه‌های info و gprofng به‌درستی نصب شده باشند، دستور info gprofng باید دسترسی به این سند را فراهم کند.

کپی‌رایت (COPYRIGHT)

اجازه کپی، توزیع و/یا تغییر این سند تحت شرایط «مجوز مستندات آزاد گنو» (GNU Free Documentation License)، نسخه ۱.۳ یا هر نسخه بعدی منتشرشده توسط بنیاد نرم‌افزار آزاد اعطا می‌شود؛ بدون بخش‌های تغییرناپذیر، بدون متون روی جلد، و بدون متون پشت جلد. یک نسخه از این مجوز در بخشی با عنوان «GNU Free Documentation License» گنجانده شده است.