HYPERFINE(1)

General Commands Manual

HYPERFINE(1)

نام (NAME)

hyperfine - ابزار محک‌زنی خط فرمان

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

hyperfine [-ihVN] [--warmup NUM] [--min-runs NUM] [--max-runs NUM] [--runs NUM] [--setup CMD] [--prepare CMD] [--conclude CMD] [--cleanup CMD] [--parameter-scan VAR MIN MAX] [--parameter-step-size DELTA] [--parameter-list VAR VALUES] [--shell SHELL] [--style TYPE] [--sort METHOD] [--time-unit UNIT] [--export-asciidoc FILE] [--export-csv FILE] [--export-json FILE] [--export-markdown FILE] [--export-orgmode FILE] [--output WHERE] [--input WHERE] [--command-name NAME] [COMMAND...]

توضیحات (DESCRIPTION)

ابزاری برای محک‌زنی (بنچمارک) در خط فرمان که شامل موارد زیر است:

* تحلیل آماری در چندین اجرای مختلف

* پشتیبانی از دستورهای دلخواه پوسته (shell)

* بازخورد پیوسته دربارهٔ پیشرفت محک‌زنی و برآوردهای فعلی

* امکان اجرای مراحل گرم‌کردن (warmup) پیش از محک‌زنی اصلی

* قابلیت تنظیم دستورهای پاک‌سازی کَش پیش از هر دور زمان‌سنجی

* تشخیص آماری داده‌های پرت جهت شناسایی اثرات تداخل برنامه‌های دیگر و کَش

* برون‌ریزی نتایج به قالب‌های گوناگون: CSV، JSON، Markdown، AsciiDoc

* محک‌زنی با پارامترهای متغیر (برای مثال تغییر تعداد ریسه‌ها)

-w, --warmup NUM

: اجرای NUM بار گرم‌کردن پیش از بنچمارک اصلی. این گزینه می‌تواند برای پر کردن حافظه‌های موقت (دیسک) برای برنامه‌های سنگین از نظر ورودی/خروجی (I/O) استفاده شود.

-m, --min-runs NUM

: اجرای دست‌کم NUM بار برای هر دستور. پیش‌فرض: 10.

-M, --max-runs NUM

: اجرای حداکثر NUM بار برای هر دستور. به‌طور پیش‌فرض هیچ محدودیتی وجود ندارد.

-r, --runs NUM

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

-s, --setup CMD...

: اجرای CMD یک بار پیش از هر مجموعه از اجراهای زمان‌سنجی. این گزینه برای کامپایل کردن نرم‌افزار شما یا با پارامترهای ارائه‌شده مفید است، یا برای انجام هر کار دیگری که باید یک بار پیش از یک سری از اجراهای بنچمارک انجام شود، نه هر بار مانند آنچه با گزینهٔ --prepare رخ می‌دهد.

-p, --prepare CMD...

: اجرای CMD پیش از هر اجرای زمان‌سنجی. این گزینه برای نمونه جهت پاک‌سازی حافظه‌های موقت دیسک مفید است. گزینهٔ --prepare می‌تواند یک بار برای همهٔ دستورها یا چند بار، یک بار برای هر دستور مشخص شود. در حالت دوم، هر دستور آماده‌سازی پیش از دستور بنچمارک متناظر با آن اجرا خواهد شد.

--conclude CMD...

: اجرای CMD پس از هر اجرای زمان‌سنجی. این گزینه برای نمونه جهت پاک‌سازی حافظه‌های موقت دیسک مفید است. گزینهٔ --conclude می‌تواند یک بار برای همهٔ دستورها یا چند بار، یک بار برای هر دستور مشخص شود. در حالت دوم، هر دستور پایانی پس از دستور بنچمارک متناظر با آن اجرا خواهد شد.

-c, --cleanup CMD...

: اجرای CMD پس از اتمام تمامی اجراهای بنچمارک برای هر دستور جداگانهٔ تحت بنچمارک. این گزینه زمانی مفید است که دستورهای تحت بنچمارک آثاری ایجاد کنند که نیاز به پاک‌سازی داشته باشند. این دستور برخلاف گزینهٔ --conclude که پس از هر بار اجرا اجرا می‌شود، تنها یک بار برای هر سری از اجراهای بنچمارک اجرا خواهد شد.

-P, --parameter-scan VAR MIN MAX

: اجرای بنچمارک برای هر مقدار در بازهٔ MIN..MAX. رشتهٔ '{VAR}' در هر دستور با مقدار کنونی پارامتر جایگزین می‌شود.

مثال:

hyperfine -P threads 1 8 'make -j {threads}'

: این دستور بنچمارک‌ها را برای 'make -j 1'، 'make -j 2'، ...، 'make -j 8' اجرا می‌کند.
: برای افزایش مقدار بر اساس الگوهای مختلف، از محاسبات حسابی پوسته استفاده کنید.

مثال:

hyperfine -P size 0 3 'sleep $((2**{size}))'

: این دستور بنچمارک‌ها را با افزایش‌های توان ۲ اجرا می‌کند: 'sleep 1'، 'sleep 2'، 'sleep 4'، ...
: نحو دقیق ممکن است بسته به پوسته و سیستم‌عامل شما متفاوت باشد.

-D, --parameter-step-size DELTA

: این آرگومان نیازمند این است که --parameter-scan نیز مشخص شده باشد. پیمایش بازهٔ MIN..MAX با گام‌های DELTA.

مثال:

hyperfine -P delay 0.3 0.7 -D 0.2 'sleep {delay}'

: این دستور بنچمارک‌ها را برای 'sleep 0.3'، 'sleep 0.5' و 'sleep 0.7' اجرا می‌کند.

-L, --parameter-list VAR VALUES

: اجرای بنچمارک برای هر مقدار در فهرست جداشده با کامای VALUES. رشتهٔ '{VAR}' در هر دستور با مقدار کنونی پارامتر جایگزین می‌شود.

مثال:

hyperfine -L compiler gcc,clang '{compiler} -O2 main.cpp'

: این دستور بنچمارک‌ها را برای 'gcc -O2 main.cpp' و 'clang -O2 main.cpp' اجرا می‌کند.
: این گزینه می‌تواند چندین بار مشخص شود تا بنچمارک‌ها برای تمام ترکیب‌های ممکن پارامتر اجرا شوند.

-S, --shell SHELL

: تنظیم پوستهٔ مورد استفاده برای اجرای دستورهای تحت بنچمارک. این مقدار می‌تواند نام یا مسیر فایل اجرایی پوسته باشد، یا یک خط فرمان کامل مانند "bash --norc". همچنین می‌تواند روی "default" تنظیم شود تا پوستهٔ پیش‌فرض روی این پلتفرم به‌طور صریح انتخاب گردد. در نهایت، می‌تواند روی "none" نیز تنظیم شود تا پوسته غیرفعال شود. در این حالت، دستورها مستقیماً اجرا خواهند شد. آن‌ها همچنان می‌توانند آرگومان داشته باشند، اما کارهای پیچیده‌تر مانند "sleep 0.1; sleep 0.2" بدون پوسته امکان‌پذیر نیستند.

-N

: یک نام مستعار برای '--shell=none'.

-i, --ignore-failure

: نادیده گرفتن کدهای خروج غیرصفر برنامه‌های تحت بنچمارک.

--style TYPE

: تنظیم سبک خروجی TYPE (پیش‌فرض: auto). این گزینه را روی 'basic' تنظیم کنید تا رنگ‌بندی خروجی و عناصر تعاملی غیرفعال شوند. آن را روی 'full' تنظیم کنید تا تمام جلوه‌ها حتی در صورت شناسایی نشدن ترمینال تعاملی فعال شوند. آن را روی 'nocolor' تنظیم کنید تا خروجی تعاملی بدون هیچ رنگی باقی بماند. آن را روی 'color' تنظیم کنید تا رنگ‌ها بدون خروجی تعاملی حفظ شوند. آن را روی 'none' تنظیم کنید تا تمام خروجی‌های ابزار غیرفعال شوند.

--sort METHOD

: مشخص کردن ترتیب مرتب‌سازی خلاصهٔ مقایسهٔ سرعت و جدول‌های صادرشده برای قالب‌های نشانه‌گذاری (Markdown، AsciiDoc، org-mode):

auto (پیش‌فرض): مقایسهٔ سرعت بر اساس زمان مرتب می‌شود و جدول‌های نشانه‌گذاری بر اساس دستور (ترتیب ورودی) مرتب خواهند شد.
command: مرتب‌سازی بنچمارک‌ها به همان روشی که مشخص شده بودند
mean-time: مرتب‌سازی بنچمارک‌ها بر اساس میانگین زمان اجرا

-u, --time-unit UNIT

: تنظیم واحد زمان مورد استفاده. مقادیر ممکن: microsecond، millisecond، second. اگر این گزینه داده نشود، واحد زمان به‌طور خودکار تعیین می‌شود. این گزینه هم بر خروجی استاندارد و هم بر تمامی قالب‌های خروجی به‌جز CSV و JSON تأثیر می‌گذارد.

--export-asciidoc FILE

: صادر کردن آمار خلاصهٔ زمان‌سنجی به صورت یک جدول AsciiDoc به FILE داده‌شده. واحد زمان خروجی می‌تواند با استفاده از گزینهٔ --time-unit تغییر یابد.

--export-csv FILE

: صادر کردن آمار خلاصهٔ زمان‌سنجی در قالب CSV به FILE داده‌شده. اگر به نتایج زمان‌سنجی هر اجرای جداگانه نیاز دارید، از قالب خروجی JSON استفاده کنید. واحد زمان خروجی همواره ثانیه است.

--export-json FILE

: صادر کردن آمار خلاصهٔ زمان‌سنجی و زمان‌های اجراهای تکی در قالب JSON به FILE داده‌شده. واحد زمان خروجی همواره ثانیه است.

--export-markdown FILE

: صادر کردن آمار خلاصهٔ زمان‌سنجی به صورت یک جدول Markdown به FILE داده‌شده. واحد زمان خروجی می‌تواند با استفاده از گزینهٔ --time-unit تغییر یابد.

--export-orgmode FILE.IP صادر کردن آمار خلاصهٔ زمان‌بندی در قالب یک جدول org-mode ایمکس به FILE مشخص‌شده. یکای زمان خروجی را می‌توان با استفاده از گزینهٔ --time-unit تغییر داد.

--show-output

: چاپ stdout و stderr محک به جای سرکوب کردن آن. این کار زمان مورد نیاز برای اجرای محک‌ها را افزایش می‌دهد، بنابراین تنها باید برای اهداف اشکال‌زدایی یا هنگام ارزیابی سرعت خروجی استفاده شود.

--output WHERE

: کنترل محل بازهدایت خروجی محک. توجه داشته باشید که برخی برنامه‌ها مانند 'grep' تشخیص می‌دهند که خروجی استاندارد /dev/null است و بهینه‌سازی‌های خاصی را اعمال می‌کنند. برای جلوگیری از این موضوع، استفاده از --output=pipe را در نظر بگیرید.
: WHERE می‌تواند یکی از موارد زیر باشد:

null: بازهدایت خروجی به /dev/null (پیش‌فرض).
pipe: فرستادن خروجی به درون یک pipe پیش از دور انداختن آن.
inherit: عدم بازهدایت خروجی (مشابه '--show-output').
<FILE>: نوشتن خروجی در فایل مشخص‌شده.

: این گزینه می‌تواند یک‌بار برای همهٔ دستورها یا چندبار، یک‌بار به ازای هر دستور مشخص شود. نکته: اگر می‌خواهید خروجی تک‌تک تکرارها را ثبت کنید، می‌توانید از بازهدایت پوسته و متغیر محیطی $HYPERFINE_ITERATION استفاده کنید: 'my-command > output-${HYPERFINE_ITERATION}.log'

--input WHERE

: کنترل این‌که ورودی محک از کجا تأمین شود.
: WHERE می‌تواند یکی از موارد زیر باشد:

null: خواندن از /dev/null (پیش‌فرض).
<FILE>: خواندن ورودی از فایل مشخص‌شده.

-n, --command-name NAME

: اختصاص دادن یک NAME معنادار به یک دستور. در صورتی که چند دستور محک زده شوند، این گزینه می‌تواند چندین بار مشخص شود.

-h, --help

: چاپ راهنما

-V, --version

: چاپ نسخه

مثال‌ها (EXAMPLES)

محک پایه از 'find . -name todo.txt':

hyperfine 'find . -name todo.txt'

انجام محک‌ها برای 'sleep 0.2' و 'sleep 3.2' با حداقل ۵ بار اجرا برای هرکدام:

hyperfine --min-runs 5 'sleep 0.2' 'sleep 3.2'

انجام محک 'grep' با حافظهٔ نهان دیسک گرم‌شده از طریق ۳ بار اجرای اولیه که بخشی از سنجش نیستند:

hyperfine --warmup 3 'grep -R TODO *'

صادر کردن نتایج محک پیمایش پارامتر به یک جدول markdown:

hyperfine --export-markdown output.md --parameter-scan time 1 5 'sleep {time}'

نمایش این‌که هر کدام از --setup، --prepare، --conclude، cmd و --cleanup چه زمانی اجرا خواهند شد:

hyperfine -L n 1,2 -r 2 --show-output \
	--setup 'echo setup n={n}' \
	--prepare 'echo prepare={n}' \
	--conclude 'echo conclude={n}' \
	--cleanup 'echo cleanup n={n}' \
	'echo command n={n}'

David Peter <mail@david-peter.de>

کد منبع، سامانه پیگیری باگ و اطلاعات تکمیلی را می‌توان در GitHub یافت: https://github.com/sharkdp/hyperfine