کتابخانه‌ی استاندارد · زمان و همروندی

زمینه ctx

زمینه برای لغو کار و مهلت، که از کار اصلی به کارهای فرعی می‌رسد.

واردسازی زمینه

نام آرگومان‌ها شناسه‌ی خود کد است و معادل فارسی ندارد؛ گونه‌ها، کلیدواژه‌ها و نام بسته‌ها با معادل فارسی نوشته می‌شوند.

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

لغو یک زمینه همه‌ی فرزندانش را هم تمام می‌کند، ولی پدرش را نه. کار فرعی باید گاه‌به‌گاه تمام شده را بررسی کند یا با انتظار منتظر بماند. هر زمینه را پس از کار با آزادسازی آزاد کنید، فرزندها پیش از پدر.

زمینه را وقتی به کار ببرید که کاری که ممکن است طول بکشد باید زودتر بایستد: درخواستی که کارخواهش رفته، کار دسته‌ای با بودجه‌ی زمانی، یا نخی در پس‌زمینه هنگام خاموش شدن برنامه. روی همگام سازی ساخته شده و میان نخ‌ها کار می‌کند. اگر فقط یک پرچم توقف لازم دارید، اتمی.پرچم کافی است؛ برای برگرداندن نتیجه‌ها، کانال را به کار ببرید.

اشتباه‌های رایج:

  • انتظار این‌که زمینه یک فراخوانی را قطع کند. هیچ تابعی در کتابخانه‌ی استاندارد زمینه نمی‌گیرد: درخواست شبکه، خواندن پرونده یا همگام سازی.خواب میلی ثانیه تا آخر اجرا می‌شود. میان گام‌ها تمام شده را بررسی کنید، با انتظار بخوابید و برای فراخوانی‌های شبکه گزینه‌های مهلت خودشان را تنظیم کنید.
  • آزاد کردن به ترتیب نادرست. هر فرزند رونوشتی از والدش نگه می‌دارد که به حافظه‌ی والد اشاره می‌کند، و آزاد کردن ریشه قفلی را که کل درخت در آن شریک است نابود می‌کند. اول فرزندها، ریشه در آخر، و هر کدام دقیقاً یک بار.
  • فرض این‌که مهلت‌ها با ساعتی یکنواخت سنجیده می‌شوند. آن‌ها با همگام سازی.اکنون میلی ثانیه سنجیده می‌شوند که روی لینوکس و مک ساعت دیواری است، پس تنظیم ساعت سیستم جابه‌جایشان می‌کند.

راهنما: یک زمینه برای هر درخواست

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

ctx-guide-tree.salam
واردسازی زمینه

تابع نمایش(نام: رشته، ز: زمینه.زمینه):
    اگر زمینه.تمام شده(ز):
        سرچاپ نام، "متوقف شد:"، زمینه.خطا(ز)
    وگرنه:
        سرچاپ نام، "در حال اجرا"
    پایان
پایان

تابع ریشه:
    پایه := زمینه.پس زمینه()
    درخواست := زمینه.با لغو(پایه)
    پرس‌وجو := زمینه.با لغو(درخواست)
    حافظه نهان := زمینه.با لغو(درخواست)
    ممیزی := زمینه.با لغو(پایه)

    زمینه.لغو(درخواست)

    نمایش("درخواست"، درخواست)
    نمایش("پرس‌وجوی پایگاه داده"، پرس‌وجو)
    نمایش("حافظه‌ی نهان"، حافظه نهان)
    نمایش("ممیزی"، ممیزی)
    نمایش("ریشه"، پایه)

    زمینه.آزادسازی(ممیزی)
    زمینه.آزادسازی(حافظه نهان)
    زمینه.آزادسازی(پرس‌وجو)
    زمینه.آزادسازی(درخواست)
    زمینه.آزادسازی(پایه)
پایان
خروجیدرخواست متوقف شد: cancelled پرس‌وجوی پایگاه داده متوقف شد: cancelled حافظه‌ی نهان متوقف شد: cancelled ممیزی در حال اجرا ریشه در حال اجرا

لغو رو به پایین درخت می‌رود و هیچ‌وقت رو به بالا نمی‌رود: ریشه و ممیزی دست‌نخورده می‌مانند. به همین دلیل بهتر است هر کار فرزند خودش را داشته باشد و زمینه‌ی پدر را مستقیم به کار نبرد: با لغو فرزند فقط همان کار را نگه می‌دارید و با لغو پدر همه را.

راهنما: بررسی میان گام‌ها

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

ctx-guide-steps.salam
واردسازی زمینه

تابع رونوشت پرونده‌ها(ز: زمینه.زمینه، پرونده‌ها: وکتور<رشته>): صحیح:
    ناپایا شمار := ۰
    هر نام در پرونده‌ها:
        اگر زمینه.تمام شده(ز):
            سرچاپ "  پیش از"، نام، "متوقف شد (" + زمینه.خطا(ز) + ")"
            برگشت شمار
        پایان
        سرچاپ "  رونوشت شد:"، نام
        شمار++
    پایان
    برگشت شمار
پایان

تابع ریشه:
    ناپایا پرونده‌ها := وکتور {} برگردان وکتور<رشته>
    پرونده‌ها.بیفزا("a.txt")
    پرونده‌ها.بیفزا("b.txt")
    پرونده‌ها.بیفزا("c.txt")
    پایه := زمینه.پس زمینه()

    سرچاپ "اجرای عادی:"
    زنده := زمینه.با لغو(پایه)
    سرچاپ "  جمع"، رونوشت پرونده‌ها(زنده، پرونده‌ها)

    سرچاپ "لغو به دست کاربر:"
    لغو شده := زمینه.با لغو(پایه)
    زمینه.لغو(لغو شده)
    سرچاپ "  جمع"، رونوشت پرونده‌ها(لغو شده، پرونده‌ها)

    سرچاپ "مهلت از پیش گذشته:"
    دیرکرد := زمینه.با موعد(پایه، ۱)
    سرچاپ "  جمع"، رونوشت پرونده‌ها(دیرکرد، پرونده‌ها)

    زمینه.آزادسازی(دیرکرد)
    زمینه.آزادسازی(لغو شده)
    زمینه.آزادسازی(زنده)
    زمینه.آزادسازی(پایه)
    پرونده‌ها.آزادکن()
پایان
خروجیاجرای عادی: رونوشت شد: a.txt رونوشت شد: b.txt رونوشت شد: c.txt جمع 3 لغو به دست کاربر: پیش از a.txt متوقف شد (cancelled) جمع 0 مهلت از پیش گذشته: پیش از a.txt متوقف شد (deadline exceeded) جمع 0

یک تابع هر سه حالت را پوشش می‌دهد و فراخواننده تعیین می‌کند کدام پیش بیاید. خطا دو دلیل را از هم جدا می‌کند: cancelled وقتی کسی لغو را صدا زده و deadline exceeded وقتی وقت تمام شده است. با موعد(پایه، ۱) لحظه‌ای در گذشته‌ی دور است، پس این زمینه از همان آغاز تمام شده است.

راهنما: بودجه‌ی زمانی

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

ctx-guide-budget.salam
واردسازی زمینه

تابع ریشه:
    پایه := زمینه.پس زمینه()
    درخواست := زمینه.با مهلت(پایه، ۲۰۰۰)
    جستجو := زمینه.با مهلت(درخواست، ۶۰۰۰۰)
    سریع := زمینه.با مهلت(درخواست، ۵۰)

    سرچاپ "ریشه موعد دارد:"، زمینه.موعد(پایه) != ۰
    سرچاپ "جستجو همان بودجه‌ی درخواست را دارد:"، زمینه.موعد(جستجو) == زمینه.موعد(درخواست)
    سرچاپ "سریع تنگ‌تر است:"، زمینه.موعد(سریع) < زمینه.موعد(درخواست)

    سرچاپ "سریع در یک ثانیه تمام شد:"، زمینه.انتظار(سریع، ۱۰۰۰)، زمینه.خطا(سریع)
    سرچاپ "درخواست هنوز در حال اجراست:"، وارونه زمینه.تمام شده(درخواست)

    زمینه.آزادسازی(سریع)
    زمینه.آزادسازی(جستجو)
    زمینه.آزادسازی(درخواست)
    زمینه.آزادسازی(پایه)
پایان
خروجیریشه موعد دارد: false جستجو همان بودجه‌ی درخواست را دارد: true سریع تنگ‌تر است: true سریع در یک ثانیه تمام شد: true deadline exceeded درخواست هنوز در حال اجراست: true

پس می‌توان در بالای کار به یک درخواست دو ثانیه بودجه داد و گامی در عمق آن یک دقیقه بخواهد، بی‌آنکه بودجه‌ی کل شکسته شود. انتظار به محض تمام شدن زمینه درست برمی‌گرداند، اینجا پس از حدود ۵۰ میلی‌ثانیه، و اگر سقف زمانی خودش زودتر برسد نادرست.

راهنما: متوقف کردن یک نخ

زمینه را می‌توان بی‌خطر میان نخ‌ها به اشتراک گذاشت، پس راه تمیزی است برای اینکه به نخی در پس‌زمینه بگویید دست بکشد. نخ تا وقتی تمام شده نادرست است می‌چرخد و میان دورها با انتظار می‌خوابد، پس لغو از نخ اصلی آن را همان لحظه بیدار می‌کند، نه پس از پایان خوابش.

ctx-guide-worker.salam
واردسازی زمینه
واردسازی همگام سازی

ناپایا پایه := زمینه.پس زمینه()
ناپایا کار := زمینه.با لغو(پایه)
ناپایا گروه := همگام سازی.گروه انتظار جدید()
ناپایا کار تمام شد := نادرست

تابع کارگر():
    تا وارونه زمینه.تمام شده(کار):
        _ := زمینه.انتظار(کار، ۱۰۰)
    پایان
    کار تمام شد = درست
    همگام سازی.اتمام(گروه)
پایان

تابع ریشه:
    همگام سازی.افزودن(گروه، ۱)
    ن := نخ‌ساز(کارگر)
    همگام سازی.خواب میلی ثانیه(۵۰)
    سرچاپ "از کارگر می‌خواهیم دست بکشد"
    زمینه.لغو(کار)
    همگام سازی.انتظار(گروه)
    نخ‌پیوند(ن)
    سرچاپ "کارگر تمام کرد:"، کار تمام شد، "دلیل:"، زمینه.خطا(کار)

    همگام سازی.نابودسازی گروه انتظار(گروه)
    زمینه.آزادسازی(کار)
    زمینه.آزادسازی(پایه)
پایان
خروجیاز کارگر می‌خواهیم دست بکشد کارگر تمام کرد: true دلیل: cancelled

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

کدام تابع برای کدام کار

می‌خواهیدبه کار ببرید
ریشه‌ی یک درخت تازهپس زمینه، که خودبه‌خود تمام نمی‌شود
کاری که دستی متوقفش می‌کنیدبا لغو و سپس لغو
کاری با سقف زمانیبا مهلت(پدر، میلی‌ثانیه)
کاری که باید در لحظه‌ی مشخصی تمام شودبا موعد(پدر، لحظه) با لحظه‌ای از همگام سازی.اکنون میلی ثانیه
بررسی بدون ماندنتمام شده، و خطا برای دلیل
خوابیدن با بیدار شدن هنگام لغوانتظار(ز، میلی‌ثانیه)

دو اشتباه رایج است. آزاد کردن پدر در حالی که فرزندانش هنوز به کار می‌روند آن‌ها را به حافظه‌ی آزادشده می‌سپارد، پس اول فرزندها را آزاد کنید. و زمینه فقط وقتی سودمند است که کار به آن نگاه کند: فراخوانی بلندی که هرگز تمام شده را بررسی نمی‌کند تا آخر اجرا می‌شود، هر قدر هم زود لغوش کنید.

گونه‌ها

زمینه Context

ساختار زمینه
یک زمینه.
نامانگلیسیگونهتوضیح
وضعیتstateصحیح۶۴*وضعیت درونی: لغو شده، موعد و داشتن موعد.
والدparentزمینه*زمینه‌ی پدر؛ برای ریشه پوچ.
قفلmuهمگام سازی.قفلقفلی که همه‌ی زمینه‌های یک درخت شریک‌اند.
متغیر شرطیcvهمگام سازی.متغیر شرطمتغیر شرطی که با لغو بیدار می‌شود.
ریشه استis_rootمنطقی = نادرستآیا این زمینه ریشه است.
ctx-Context.salam
واردسازی زمینه

تابع ریشه:
    پایه := زمینه.پس زمینه()
    ک := زمینه.با لغو(پایه)
    م := زمینه.با مهلت(ک، ۳۰)
    سرچاپ زمینه.تمام شده(م)، "[" + زمینه.خطا(م) + "]"، زمینه.موعد(م) > ۰، زمینه.موعد(پایه)
    سرچاپ زمینه.انتظار(م، ۱۰)
    سرچاپ زمینه.انتظار(م، ۱۰۰۰)، زمینه.خطا(م)
    زمینه.لغو(ک)
    سرچاپ زمینه.تمام شده(ک)، زمینه.خطا(ک)، زمینه.تمام شده(پایه)
    گذشته := زمینه.با موعد(پایه، ۱)
    سرچاپ زمینه.تمام شده(گذشته)، زمینه.خطا(گذشته)
    زمینه.آزادسازی(گذشته)
    زمینه.آزادسازی(م)
    زمینه.آزادسازی(ک)
    زمینه.آزادسازی(پایه)
پایان
خروجیfalse [] true 0 false true deadline exceeded true cancelled false true deadline exceeded

تابع‌ها

پس زمینه Background

تابع پس زمینه(): زمینه
زمینه‌ی ریشه که هیچ‌وقت خودبه‌خود تمام نمی‌شود.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: ctx-Context.salam

با لغو WithCancel

تابع با لغو(parent: زمینه): زمینه
فرزندی که با لغو تمام می‌شود.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: ctx-Context.salam

با مهلت WithTimeout

تابع با مهلت(parent: زمینه، ms: صحیح۶۴): زمینه
فرزندی که ms میلی‌ثانیه‌ی دیگر تمام می‌شود.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: ctx-Context.salam

با موعد WithDeadline

تابع با موعد(parent: زمینه، at_ms: صحیح۶۴): زمینه
فرزندی که در لحظه‌ی at_ms تمام می‌شود؛ زمان بر حسب میلی‌ثانیه، مثل همگام سازی.اکنون میلی ثانیه.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: ctx-Context.salam

لغو Cancel

تابع لغو(c: زمینه)
زمینه و همه‌ی فرزندانش را تمام می‌کند و منتظرها را بیدار می‌کند.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: ctx-Context.salam

تمام شده IsDone

تابع تمام شده(c: زمینه): منطقی
اگر زمینه یا یکی از پدرانش لغو شده یا مهلتش گذشته باشد، درست برمی‌گرداند.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: ctx-Context.salam

خطا Err

تابع خطا(c: زمینه): رشته
دلیل تمام شدن: cancelled یا deadline exceeded؛ اگر هنوز تمام نشده، رشته‌ی خالی.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: ctx-Context.salam

موعد Deadline

تابع موعد(c: زمینه): صحیح۶۴
نزدیک‌ترین موعد در زمینه و پدرانش، بر حسب میلی‌ثانیه؛ اگر موعدی نباشد، صفر.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: ctx-Context.salam

انتظار Wait

تابع انتظار(c: زمینه، ms: صحیح۶۴): منطقی
حداکثر ms میلی‌ثانیه صبر می‌کند تا زمینه تمام شود و می‌گوید تمام شده یا نه.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: ctx-Context.salam

آزادسازی Free

تابع آزادسازی(c: زمینه)
حافظه‌ی زمینه را آزاد می‌کند.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: ctx-Context.salam