.\" Hey, EMACS: -*- nroff -*-
.\" First parameter, NAME, should be all caps
.\" Second parameter, SECTION, should be 1-8, maybe w/ subsection
.\" other parameters are allowed: see man(7), man(1)
.\" Please adjust this date whenever revising the manpage.
.\" 
.\" Some roff macros, for reference:
.\" .nh        disable hyphenation
.\" .hy        enable hyphenation
.\" .ad l      left justify
.\" .ad b      justify to both left and right margins
.\" .nf        disable filling
.\" .fi        enable filling
.\" .br        insert line break
.\" .sp <n>    insert n+1 empty lines
.\" for manpage-specific macros, see man(7)
.TH "DMTCP" "1" "June 17, 2008" "DMTCP team" "Distributed MultiThreaded CheckPointing"
.SH "نام (NAME)"
dmtcp \- وارسی‌گذاری توزیع‌شده چندنخی (Distributed MultiThreaded Checkpointing)
.SH "خلاصه دستور (SYNOPSIS)"
.B dmtcp_coordinator
.RI [port]
.br 

.B dmtcp_launch 
.RI command
.RI [args...]
.br 

.B dmtcp_restart
.RI ckpt_FILE1.dmtcp
.RI [ckpt_FILE2.dmtcp...]

.B dmtcp_command
.RI coordinatorCommand

.SH "توضیحات (DESCRIPTION)"
ابزار \fBDMTCP\fP ابزاری برای وارسی‌گذاری (ثبت شفاف نقطه بازرسی) از وضعیت گروهی دلخواه از برنامه‌ها است که در چندین ماشین مختلف پخش شده و از طریق سوکت به یکدیگر متصل هستند. این ابزار نه برنامه کاربر را تغییر می‌دهد و نه سیستم‌عامل را.
بخش \fBMTCP\fP یک جزء مستقل از DMTCP است که به عنوان یک کتابخانه وارسی‌گذاری برای یک فرایند واحد در دسترس است.
.SH "گزینه‌ها (OPTIONS)"
برای هر دستور، پرچم \-\-help یا \-h گزینه‌های خط فرمان را نشان می‌دهد.
اکثر گزینه‌های خط فرمان را می‌توان از طریق متغیرهای محیطی نیز کنترل کرد.
این متغیرها را می‌توان در bash با "export NAME=value"
یا در tcsh با "setenv NAME value" تنظیم کرد.

.IP  DMTCP_CHECKPOINT_INTERVAL=integer
زمان بر حسب ثانیه بین نقاط بازرسی خودکار. نقاط بازرسی را می‌توان به صورت دستی نیز با تایپ 'c' در هماهنگ‌کننده آغاز کرد. (پیش‌فرض: 0، غیرفعال؛ فقط برای dmtcp_coordinator)

.IP  DMTCP_HOST=string
نام میزبانی که هماهنگ‌کننده سراسری خوشه روی آن در حال اجرا است. (پیش‌فرض: localhost؛ فقط برای dmtcp_launch و dmtcp_restart)

.IP  DMTCP_PORT=integer
درگاهی که هماهنگ‌کننده سراسری خوشه روی آن گوش می‌دهد. (پیش‌فرض: 7779)

.IP  DMTCP_GZIP=(1|0)
برای غیرفعال کردن فشرده‌سازی تصویرهای نقاط بازرسی، مقدار را روی "0" قرار دهید.
(پیش‌فرض: 1، فشرده‌سازی فعال؛ فقط برای dmtcp_launch)
هشدار: gzip چند ثانیه به زمان اضافه می‌کند. بدون gzip، ذخیره و بازنشانی (ckpt/restart) اغلب کمتر از ۱ ثانیه طول می‌کشد.

.IP  DMTCP_CHECKPOINT_DIR=path
دایرکتوری برای ذخیره تصویرهای نقطه بازرسی. (پیش‌فرض: ./)

.IP  DMTCP_SIGCKPT=integer
شماره سیگنال داخلی برای استفاده در فرایند وارسی‌گذاری. این شماره نباید توسط برنامه کاربر استفاده شود.
(پیش‌فرض: SIGUSR2؛ فقط برای dmtcp_launch)
.SH "هماهنگ‌کننده DMTCP (DMTCP_COORDINATOR)"
هر محاسباتی که قرار است از آن نقطه بازرسی گرفته شود باید شامل یک فرایند هماهنگ‌کننده DMTCP باشد.
می‌توان یک هماهنگ‌کننده را به صراحت از طریق dmtcp_coordinator راه‌اندازی کرد،
یا اجازه داد به طور ضمنی در پس‌زمینه توسط dmtcp_launch یا dmtcp_restart آغاز به کار کند.
نشانی هماهنگ‌کننده یکتا باید برای dmtcp_launch، dmtcp_restart و dmtcp_command یا از طریق
پرچم‌های خط فرمان \-\-host و \-\-port یا از طریق
متغیرهای محیطی DMTCP_HOST و DMTCP_PORT مشخص شود. اگر هیچ‌کدام داده نشود، جفت میزبان-درگاه به صورت پیش‌فرض localhost-7779 در نظر گرفته می‌شود.
جفت میزبان-درگاه مرتبط با یک هماهنگ‌کننده خاص توسط پرچم‌های خط فرمان استفاده‌شده در دستور dmtcp_coordinator،
یا متغیرهای محیطی فعال در آن زمان، یا مقدار پیش‌فرض localhost-7779 تعیین می‌شود.

هماهنگ‌کننده بی‌وضعیت (stateless) است و از خود آن نقطه بازرسی گرفته \fBنمی‌شود\fR.
در هنگام شروع مجدد (restart)، می‌توان از یک هماهنگ‌کننده موجود یا یک هماهنگ‌کننده جدید استفاده کرد.
چندین محاسبه تحت کنترل DMTCP می‌توانند با ارائه یک هماهنگ‌کننده یکتا (با یک جفت میزبان-درگاه یکتا) برای هر یک از این محاسبات همزیستی داشته باشند.

هماهنگ‌کننده یک فرایند وارسی‌گذاری را برای تمام فرایندهای موجود در گروه محاسباتی خود آغاز می‌کند. نقاط بازرسی می‌توانند: به طور خودکار در یک بازه زمانی معین انجام شوند (بخش DMTCP_CHECKPOINT_INTERVAL در بالا را ببینید)؛ یا به طور دستی در ورودی استاندارد هماهنگ‌کننده آغاز شوند (پاراگراف بعدی را ببینید)؛
یا مستقیماً تحت کنترل برنامه توسط خود محاسبه از طریق رابط برنامه‌نویسی افزونه‌ها (plugin API) آغاز شوند (بخش زیر را ببینید).

هماهنگ‌کننده دستورهای زیر را در ورودی استاندارد خود می‌پذیرد.
هر دستور باید با کلید <return> دنبال شود. این دستورها عبارتند از:
.br 
  l : فهرست کردن گره‌های متصل
.br 
  s : چاپ پیام وضعیت
.br 
  c : وارسی‌گذاری (ثبت نقطه بازرسی) تمام گره‌ها
.br 
  f : اجبار به شروع مجدد حتی در صورت مفقود بودن گره‌ها (اشکال‌زدایی)
.br 
  k : خاتمه دادن (kill) به تمام گره‌ها
.br 
  q : خاتمه دادن به تمام گره‌ها و خروج
.br 
  ? : نمایش این پیام

دستورهای هماهنگ‌کننده را می‌توان از راه دور با استفاده از \fBdmtcp_command\fR نیز صادر کرد.

.SH "مثال‌های کاربردی (EXAMPLE USAGE)"
.TP  
1. در یک پنجره ترمینال جداگانه، dmtcp_coordinator را راه‌اندازی کنید.
(بخش قبل را ببینید.)

 dmtcp_coordinator

.TP 
2. در ترمینال‌های جداگانه، هر دستور را با "dmtcp_launch [command]" جایگزین کنید. برنامه وارسی‌شده به هماهنگ‌کننده‌ای که با DMTCP_HOST و DMTCP_PORT مشخص شده متصل خواهد شد. ریسمان‌های جدید به عنوان بخشی از فرایند وارسی‌گذاری می‌شوند. فرایندهای فرزند به طور خودکار وارسی‌گذاری می‌شوند. فرایندهای از راه دور که از طریق \fIssh\fR آغاز شده‌اند نیز به طور خودکار وارسی‌گذاری خواهند شد. (درون سیستم، DMTCP خط فرمان \fIssh\fR را تغییر می‌دهد تا dmtcp_launch را روی میزبان راه دور فراخوانی کند.)

 dmtcp_launch ./myprogram

.TP 
3. برای شروع دستی یک نقطه بازرسی، یا دستور زیر را اجرا کنید یا در هماهنگ‌کننده حرف "c" و سپس <return> را وارد کنید. فایل‌های نقطه بازرسی برای هر فرایند در DMTCP_CHECKPOINT_DIR نوشته خواهند شد. برنامه dmtcp_coordinator اسکریپت "dmtcp_restart_script.sh" را در دایرکتوری کاری خود می‌نویسد. این اسکریپت حاوی فراخوانی‌های لازم به dmtcp_restart است تا کل محاسبات، از جمله فرایندهای از راه دور ایجادشده از طریق \fIssh\fR را مجدداً راه‌اندازی کند.

     dmtcp_command \-c
.br 
یا:  dmtcp_command \-\-checkpoint

.TP 
4. برای شروع مجدد، باید dmtcp_restart_script.sh اجرا شود که در زمان وارسی‌گذاری توسط dmtcp_coordinator در دایرکتوری کاری آن ایجاد شده است. در صورت تمایل می‌توان این اسکریپت را برای انتقال فرایندها به میزبان‌های مختلف ویرایش کرد. به طور پیش‌فرض، تنها یکی از فرایندهای بازنشانی‌شده در پیش‌زمینه راه‌اندازی می‌شود و ورودی استاندارد را دریافت می‌کند. این اسکریپت را می‌توان ویرایش کرد تا مشخص شود کدام فرایند در پیش‌زمینه مجدداً راه‌اندازی شود.

 ./dmtcp_restart_script.sh

.SH "افزونه‌های DMTCP (DMTCP PLUGIN)"

توزیع کد منبع شامل یک دایرکتوری سطح بالا به نام \fIplugin\fR است
که مثال‌هایی از نحوه نوشتن افزونه برای DMTCP را در بر دارد. افزونه‌ها به یک برنامه وارسی‌شده اجازه می‌دهند تا اتصال خود را از یک منبع خارجی قطع کرده و سپس در زمان شروع مجدد، دوباره به آن متصل شود. مثال‌های بیشتر در دایرکتوری \fItest/plugin\fR قرار دارند. به ویژه، بخش
\fItest/plugin/applic-initiated\fR نشان می‌دهد که چگونه یک برنامه می‌تواند تحت کنترل خود درخواست ثبت نقطه بازرسی را ثبت کند.

قابلیت افزونه‌ها سه امکان جدید قابل برنامه‌ریزی توسط کاربر را اضافه می‌کند.
یک افزونه می‌تواند: پوسته‌هایی (wrappers) در اطراف فراخوانی‌های سیستمی ایجاد کند؛ در طول رویدادهای خاص اقدامات ویژه‌ای انجام دهد (مانند پیش از نقطه بازرسی، از سرگیری/پس از نقطه بازرسی، شروع مجدد)؛ و می‌تواند در زمان شروع مجدد جفت‌های کلید-مقدار را در یک پایگاه‌داده درج کند که سپس فرایندهای مجدداً راه‌اندازی‌شده یک محاسبه بتوانند آن را پرس‌وجو کنند.
(رویدادهای موجود برای قابلیت افزونه، ابرمجموعه‌ای از رویدادهای ارائه‌شده توسط واسط dmtcpaware هستند.)
یک یا چند افزونه از طریق فهرستی از مسیرهای مطلق که با دونقطه از هم جدا شده‌اند، فراخوانی می‌شوند:

  dmtcp_launch \-\-with\-plugin PLUGIN1[:PLUGIN2]...

.SH "رابط برنامه‌نویسی DMTCPAWARE (DMTCPAWARE API)"
این رابط برنامه‌نویسی اکنون منسوخ شده و افزونه‌های DMTCP جایگزین آن شده‌اند (بخش بالا را ببینید).
ابزار DMTCP یک واسط برنامه‌نویسی ارائه می‌دهد تا برنامه‌های وارسی‌شده بتوانند با dmtcp تعامل داشته باشند. در توزیع کد منبع، برای مشاهده توابع موجود به dmtcpaware/dmtcpaware.h مراجعه کنید.
برای مشاهده سه نمونه کاربردی، به فایل‌های test/dmtcpaware[123].c مراجعه فرمایید.
برای دیدن مثالی از کاربرد آن، دستور زیر را امتحان کنید:

 cd test; rm dmtcpaware1; make dmtcpaware1; ./autotest \-v dmtcpaware1

برنامه کاربر باید با libdmtcpaware.so پیوند داده شود (\-ldmtcpaware)
و از فایل هدر dmtcp/dmtcpaware.h استفاده کند.

.SH "کد بازگشتی (RETURN CODE)"
یک برنامه هدف تحت کنترل DMTCP به طور عادی همان کد بازگشتی را برمی‌گرداند که گویی بدون DMTCP اجرا شده است. با این حال، اگر DMTCP شکست بخورد (در مقایسه با شکست برنامه هدف)، DMTCP یک کد بازگشتی مختص به خود یعنی rc (یا در دو حالت خاص rc+1 یا rc+2) برمی‌گرداند؛ که در آن rc مقدار عدد صحیح متغیر محیطی DMTCP_FAIL_RC در صورت تنظیم بودن، یا در غیر این صورت مقدار پیش‌فرض یعنی 99 است.
.SH "همچنین ببینید (SEE ALSO)"
مستندات کامل در صفحه خانگی DMTCP موجود است:
 http://dmtcp.sourceforge.net
.br
پرسش‌های متداول (FAQ): http://dmtcp.sourceforge.net/FAQ.html
.br
افزونه‌ها: https://github.com/dmtcp/dmtcp/blob/master/doc/plugin-tutorial.pdf
	(DMTCP-2.x)
.br
  نمونه‌ها: https://github.com/dmtcp/dmtcp/tree/master/test/plugin
.SH "نویسندگان (AUTHORS)"
ابزار DMTCP و جزء تک‌فرایندی مستقل آن یعنی MTCP (MultiThreaded CheckPointing) توسط مشارکت‌کنندگان بلندمدت آن یعنی Jason Ansel، Kapil Arya، Gene Cooperman، Rohan Garg، Artem Y. Polyakov، Mike Rieker و مجموعه‌ای از مشارکت‌کنندگان دیگر شامل Alex Brick، Tyler Denniston، William Enright، Gregory Kerr، Ana-Maria Visan و دیگران ایجاد شده است.
برای پشتیبانی، به صفحه اصلی DMTCP مراجعه کنید.