داده‌های محلی نخ¶

داده محلی به نخ، داده‌ای است که مقادیر آن مختص نخ است. اگر داده‌ای دارید که می‌خواهید محلی به یک نخ باشد، یک شیء local ایجاد کنید و از ویژگی‌های آن استفاده کنید:

>>> mydata = local()
>>> mydata.number = 42
>>> mydata.number
42

همچنین می‌توانید به دیکشنری شیء local دسترسی پیدا کنید:

>>> mydata.__dict__
{'number': 42}
>>> mydata.__dict__.setdefault('widgets', [])
[]
>>> mydata.widgets
[]

اگر به داده‌ها در یک نخ دیگر دسترسی داشته باشیم:

>>> log = []
>>> def f():
...     items = sorted(mydata.__dict__.items())
...     log.append(items)
...     mydata.number = 11
...     log.append(mydata.number)

>>> import threading
>>> thread = threading.Thread(target=f)
>>> thread.start()
>>> thread.join()
>>> log
[[], 11]

ما داده‌های متفاوتی دریافت می‌کنیم. علاوه بر این، تغییرات اعمال‌شده در نخ دیگر بر داده‌های دیده‌شده در این نخ تأثیر نمی‌گذارند:

>>> mydata.number
42

البته، مقدارهایی که از یک شیء local به دست می‌آورید، از جمله ویژگی __dict__ آن‌ها، مربوط به هر نخی هستند که در زمان خوانده شدن ویژگی جاری بوده است. به همین دلیل، معمولاً نباید این مقدارها را بین نخ‌ها ذخیره کنید، زیرا آن‌ها فقط به نخی که از آن آمده‌اند اعمال می‌شوند.

شما می‌توانید با زیرکلاس‌سازی از کلاس local، اشیای سفارشی local ایجاد کنید:

>>> class MyLocal(local):
...     number = 2
...     def __init__(self, /, **kw):
...         self.__dict__.update(kw)
...     def squared(self):
...         return self.number ** 2

این می‌تواند برای پشتیبانی از مقادیر پیش‌فرض، متدها و مقداردهی اولیه مفید باشد. توجه داشته باشید که اگر متد __init__() را تعریف کنید، هر بار که از شیء local در یک نخ جداگانه استفاده شود، فراخوانی می‌شود. این برای مقداردهی اولیه دیکشنری هر نخ ضروری است.

اکنون اگر یک شیء local ایجاد کنیم:

>>> mydata = MyLocal(color='red')

یک عدد پیش‌فرض داریم:

>>> mydata.number
2

یک رنگ اولیه:

>>> mydata.color
'red'
>>> del mydata.color

و متدی که روی داده‌ها عمل می‌کند:

>>> mydata.squared()
4

مانند قبل، می‌توانیم به داده‌ها در یک نخ جداگانه دسترسی داشته باشیم:

>>> log = []
>>> thread = threading.Thread(target=f)
>>> thread.start()
>>> thread.join()
>>> log
[[('color', 'red')], 11]

بدون تأثیر بر داده‌های این نخ:

>>> mydata.number
2
>>> mydata.color
Traceback (most recent call last):
...
AttributeError: 'MyLocal' object has no attribute 'color'

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

>>> class MyLocal(local):
...     __slots__ = 'number'

>>> mydata = MyLocal()
>>> mydata.number = 42
>>> mydata.color = 'red'

بنابراین، نخ جداگانه:

>>> thread = threading.Thread(target=f)
>>> thread.start()
>>> thread.join()

بر آنچه می‌بینیم تأثیر می‌گذارد:

>>> mydata.number
11

class threading.local¶

کلاسی که داده‌های محلی نخ (thread-local) را نشان می‌دهد.

اشیای نخ¶

کلاس Thread نشان‌دهنده‌ی فعالیتی است که در یک نخ کنترلی جداگانه اجرا می‌شود. دو راه برای مشخص کردن فعالیت وجود دارد: با ارسال یک شیء فراخوانی‌پذیر به سازنده، یا با بازنویسی متد run() در یک زیرکلاس. هیچ متد دیگری (به‌جز سازنده) نباید در یک زیرکلاس بازنویسی شود. به عبارت دیگر، فقط متدهای __init__() و run() این کلاس را بازنویسی کنید.

پس از ایجاد یک شیء نخ، فعالیت آن باید با فراخوانی متد start() نخ آغاز شود. این کار متد run() را در یک نخ کنترلی جداگانه فراخوانی می‌کند.

هنگامی که فعالیت نخ آغاز می‌شود، نخ «زنده» در نظر گرفته می‌شود. هنگامی که متد run() آن پایان می‌یابد، دیگر زنده نیست — چه به‌طور عادی و چه با پرتاب یک استثنای مدیریت‌نشده. متد is_alive() زنده بودن نخ را بررسی می‌کند.

نخ‌های دیگر می‌توانند متد join() یک نخ را فراخوانی کنند. این کار نخ فراخواننده را مسدود می‌کند تا زمانی که نخی که متد join() آن فراخوانی شده است، خاتمه یابد.

هر نخ دارای یک نام است. این نام را می‌توان به سازنده ارسال کرد و از طریق ویژگی name خواند یا تغییر داد.

اگر متد run() استثنایی پرتاب کند، برای رسیدگی به آن، threading.excepthook() فراخوانی می‌شود. به‌طور پیش‌فرض، threading.excepthook() از SystemExit به‌صورت بی‌صدا چشم‌پوشی می‌کند.

یک نخ می‌تواند به‌عنوان «نخ daemon (daemon thread)» علامت‌گذاری شود. اهمیت این پرچم در این است که وقتی فقط نخ‌های daemon باقی مانده باشند، کل برنامه‌ی Python خارج می‌شود. مقدار اولیه از نخ ایجادکننده به ارث برده می‌شود. این پرچم را می‌توان از طریق ویژگی daemon یا آرگومان daemon در سازنده تنظیم کرد.

یک شیء «نخ اصلی» وجود دارد؛ این شیء متناظر با نخ آغازین کنترل در برنامه پایتون است. این یک نخ daemon نیست.

این احتمال وجود دارد که «اشیاء نخ ساختگی (dummy thread objects)» ایجاد شوند. این‌ها اشیاء نخ هستند که با «نخ‌های بیگانه (alien threads)» متناظرند؛ نخ‌های کنترلی که خارج از ماژول threading، مثلاً مستقیماً از کد C، آغاز شده‌اند. اشیاء نخ ساختگی قابلیت محدودی دارند؛ آن‌ها همیشه زنده و daemon (daemonic) در نظر گرفته می‌شوند و نمی‌توان آن‌ها را الحاق کرد. آن‌ها هرگز حذف نمی‌شوند، زیرا تشخیص پایان نخ‌های بیگانه غیرممکن است.

class threading.Thread(group=None, target=None, name=None, args=(), kwargs={}, *, daemon=None, context=None)¶

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

group باید None باشد، زیرا برای گسترش آینده در زمانی که یک کلاس ThreadGroup پیاده‌سازی شود، رزرو شده است.

target شیء فراخوانی‌پذیری است که توسط متد run() فراخوانی می‌شود. مقدار پیش‌فرض آن None است، یعنی هیچ چیزی فراخوانی نمی‌شود.

name نام نخ است. به‌طور پیش‌فرض، یک نام یکتا در قالب «Thread-N» ساخته می‌شود که در آن N یک عدد دهدهی کوچک است، یا «Thread-N (target)» که در آن «target» برابر target.__name__ است، در صورتی که آرگومان target مشخص شده باشد.

args یک فهرست یا تاپل از آرگومان‌ها برای فراخوانی هدف است. مقدار پیش‌فرض آن () است.

kwargs یک دیکشنری از آرگومان‌های کلیدواژه‌ای برای فراخوانی هدف است. پیش‌فرض آن {} است.

اگر None نباشد، daemon به‌صراحت تعیین می‌کند که آیا نخ daemon است یا خیر. اگر None باشد (پیش‌فرض)، ویژگی daemon از نخ جاری به ارث می‌رسد.

context مقدار Context است که هنگام آغاز نخ استفاده می‌شود. مقدار پیش‌فرض None است، که نشان می‌دهد پرچم sys.flags.thread_inherit_context رفتار را کنترل می‌کند. اگر پرچم true باشد، نخ‌ها با یک کپی از زمینه‌ی فراخواننده‌ی start() آغاز می‌شوند. اگر false باشد، آن‌ها با یک زمینه‌ی خالی آغاز می‌شوند. برای آغاز به‌طور صریح با یک زمینه‌ی خالی، یک نمونه‌ی جدید از Context() را ارسال کنید. برای آغاز به‌طور صریح با یک کپی از زمینه‌ی جاری، مقدار حاصل از copy_context() را ارسال کنید. مقدار پیش‌فرض این پرچم در ساخت‌های نخ‌آزاد برابر true و در غیر این صورت false است.

اگر زیرکلاس سازنده را بازنویسی کند، باید پیش از انجام هر کار دیگری روی نخ، از فراخوانی سازنده‌ی کلاس پایه (Thread.__init__()) اطمینان حاصل کند.

تغییر یافته در نسخه‌ی 3.3: پارامتر daemon اضافه شد.

تغییر یافته در نسخه‌ی 3.10: اگر آرگومان name حذف شده باشد، از نام target استفاده کنید.

تغییر یافته در نسخه‌ی 3.14: پارامتر context افزوده شد.

start()¶

فعالیت نخ را آغاز می‌کند.

این باید حداکثر یک‌بار به ازای هر شیء نخ فراخوانی شود. این ترتیبی می‌دهد که متد run() آن شیء در یک نخ کنترل جداگانه فراخوانی شود.

این متد در صورت فراخوانی بیش از یک بار روی همان شیء نخ، RuntimeError را پرتاب خواهد کرد.

در صورت پشتیبانی، نام نخ سیستم‌عامل برابر با threading.Thread.name تنظیم می‌شود. ممکن است نام، بسته به محدودیت‌های نام نخ سیستم‌عامل، کوتاه شود.

تغییر یافته در نسخه‌ی 3.14: نام نخ سیستم‌عامل را تنظیم می‌کند.

run()¶

متدی که فعالیت نخ را نشان می‌دهد.

شما می‌توانید این متد را در یک زیرکلاس بازنویسی کنید. متد استاندارد run() شیء فراخوانی‌پذیری را که به سازنده‌ی شیء به‌عنوان آرگومان target ارسال‌شده است، در صورت وجود، با آرگومان‌های جایگاهی و کلیدواژه‌ای که به‌ترتیب از آرگومان‌های args و kwargs گرفته می‌شوند، فراخوانی می‌کند.

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

مثال:

>>> from threading import Thread
>>> t = Thread(target=print, args=[1])
>>> t.run()
1
>>> t = Thread(target=print, args=(1,))
>>> t.run()
1

join(timeout=None)¶

صبر کنید تا نخ پایان یابد. این عمل نخ فراخوان را مسدود می‌کند تا زمانی که نخی که متد join() آن فراخوانی شده است پایان یابد -- چه به‌صورت عادی و چه از طریق استثنای مدیریت‌نشده -- یا تا زمانی که مهلت زمانی اختیاری رخ دهد.

هنگامی که آرگومان timeout موجود باشد و برابر با None نباشد، باید یک عدد حقیقی باشد که مهلت زمانی عملی را برحسب ثانیه (یا کسری از آن) مشخص می‌کند. از آنجا که join() همواره None را برمی‌گرداند، باید پس از join() متد is_alive() را فراخوانی کنید تا تصمیم بگیرید آیا مهلت زمانی به پایان رسیده است یا خیر — اگر نخ همچنان زنده باشد، فراخوانی join() با پایان مهلت زمانی مواجه شده است.

هنگامی که آرگومان timeout وجود ندارد یا None است، عملیات تا زمانی که نخ پایان یابد مسدود می‌شود.

یک نخ را می‌توان چندین بار الحاق کرد.

join() در صورتی که تلاشی برای فراخوانی آن روی نخ جاری انجام شود، یک RuntimeError پرتاب می‌کند، زیرا این کار باعث بن‌بست می‌شود. فراخوانی join() روی یک نخ پیش از آنکه شروع شده باشد نیز خطا است و تلاش‌ها برای این کار همان استثنا را پرتاب می‌کنند.

اگر برای join کردن یک نخ daemon در حال اجرا در مراحل پایانی نهایی‌سازی پایتون تلاشی صورت گیرد، join() یک PythonFinalizationError پرتاب می‌کند.

تغییر یافته در نسخه‌ی 3.14: ممکن است PythonFinalizationError را پرتاب کند.

تغییر یافته در نسخه‌ی 3.15: هر عدد حقیقی را به عنوان timeout می‌پذیرد، و محدود به عدد صحیح یا اعشاری نیست.

name¶

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

در برخی پلتفرم‌ها، نام نخ در زمان شروع نخ در سطح سیستم‌عامل تنظیم می‌شود تا در مدیران وظیفه قابل مشاهده باشد. این نام ممکن است برای جا شدن در محدودیت خاص سیستم کوتاه شود (برای مثال، ۱۵ بایت در لینوکس یا ۶۳ بایت در macOS).

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

getName()¶

setName()¶

API منسوخ برای getter/setter مربوط به name؛ به‌جای آن، مستقیماً از آن به‌عنوان یک ویژگی استفاده کنید.

منسوخ شده از نسخه‌ی 3.10.

ident¶

«شناسه‌ی نخ» برای این نخ یا None اگر نخ شروع نشده باشد. این یک عدد صحیح غیرصفر است. تابع get_ident() را ببینید. ممکن است شناسه‌های نخ زمانی که یک نخ به پایان می‌رسد و نخ دیگری ایجاد می‌شود، دوباره استفاده شوند. شناسه حتی پس از پایان یافتن نخ نیز در دسترس است.

native_id¶

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

نکته

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

دسترس‌پذیری: Windows, FreeBSD, Linux, macOS, OpenBSD, NetBSD, AIX, DragonFlyBSD.

اضافه شده در نسخه‌ی 3.8.

is_alive()¶

زنده بودن نخ را برمی‌گرداند.

این متد True را از درست پیش از آغاز متد run() تا درست پس از پایان متد run() بازمی‌گرداند. تابع ماژول enumerate() فهرستی از همه نخ‌های زنده را بازمی‌گرداند.

daemon¶

یک مقدار بولی که نشان می‌دهد این نخ یک نخ daemon است (True) یا خیر (False). این مقدار باید پیش از فراخوانی start() تنظیم شود، در غیر این صورت RuntimeError پرتاب می‌شود. مقدار اولیه آن از نخ ایجادکننده به ارث می‌رسد؛ نخ اصلی یک نخ daemon نیست و بنابراین همه نخ‌هایی که در نخ اصلی ایجاد می‌شوند، به‌طور پیش‌فرض daemon = False هستند.

کل برنامه پایتون هنگامی خارج می‌شود که دیگر هیچ نخ زنده غیر daemon (non-daemon) باقی نمانده باشد.

isDaemon()¶

setDaemon()¶

API getter/setter منسوخ‌شده برای daemon؛ به‌جای آن مستقیماً از آن به‌عنوان یک ویژگی استفاده کنید.

منسوخ شده از نسخه‌ی 3.10.

اشیای قفل¶

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

یک قفل اولیه در یکی از دو حالت «قفل‌شده» یا «باز» قرار دارد. این قفل در حالت باز ایجاد می‌شود. دو متد پایه دارد: acquire() و release(). هنگامی که حالت باز است، acquire() حالت را به قفل‌شده تغییر می‌دهد و بلافاصله بازمی‌گردد. هنگامی که حالت قفل‌شده است، acquire() مسدود می‌شود تا زمانی که فراخوانی release() در نخی دیگر آن را به حالت باز تغییر دهد، سپس فراخوانی acquire() آن را دوباره به حالت قفل‌شده تنظیم می‌کند و بازمی‌گردد. متد release() باید فقط در حالت قفل‌شده فراخوانی شود؛ این متد حالت را به باز تغییر می‌دهد و بلافاصله بازمی‌گردد. اگر تلاشی برای آزاد کردن یک قفل باز انجام شود، یک RuntimeError پرتاب خواهد شد.

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

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

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

class threading.Lock¶

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

تغییر یافته در نسخه‌ی 3.13: Lock اکنون یک کلاس است. در پایتون‌های پیشین، Lock یک تابع کارخانه (factory function) بود که نمونه‌ای از نوع قفل خصوصی زیربنایی را برمی‌گرداند.

acquire(blocking=True, timeout=-1)¶

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

هنگامی که با آرگومان blocking تنظیم‌شده روی True (پیش‌فرض) فراخوانی شود، تا آزاد شدن قفل مسدود می‌شود، سپس آن را در حالت قفل‌شده قرار می‌دهد و True را برمی‌گرداند.

هنگامی که با آرگومان blocking تنظیم‌شده روی False فراخوانی شود، مسدود نمی‌کند. اگر فراخوانی با blocking تنظیم‌شده روی True قرار باشد مسدود شود، بلافاصله False را برمی‌گرداند؛ در غیر این صورت، قفل را در وضعیت قفل‌شده قرار می‌دهد و True را برمی‌گرداند.

هنگامی که با آرگومان timeout تنظیم‌شده روی یک مقدار مثبت فراخوانی شود، حداکثر به مدت تعداد ثانیه‌های مشخص‌شده توسط timeout و تا زمانی که قفل نتواند به‌دست بیاید، مسدود می‌شود. آرگومان timeout برابر با -1 یک انتظار نامحدود را مشخص می‌کند. مشخص کردن timeout وقتی که blocking برابر با False است، ممنوع است.

مقدار بازگشتی True است اگر قفل با موفقیت گرفته شود، در غیر این صورت False است (برای مثال اگر timeout منقضی شده باشد).

تغییر یافته در نسخه‌ی 3.2: پارامتر timeout جدید است.

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

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

تغییر یافته در نسخه‌ی 3.15: هر عدد حقیقی را به عنوان timeout می‌پذیرد، و محدود به عدد صحیح یا اعشاری نیست.

release()¶

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

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

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

هیچ مقدار بازگشتی وجود ندارد.

locked()¶

اگر قفل به‌دست آمده باشد، True برمی‌گرداند.

اشیای RLock¶

قفل بازورودپذیر (reentrant lock) یک سازوکار اولیه‌ی همگام‌سازی است که یک نخ یکسان می‌تواند آن را چندین بار کسب کند. از نظر داخلی، این قفل علاوه بر وضعیت قفل‌شده/قفل‌نشده‌ی استفاده‌شده در قفل‌های اولیه، از مفاهیم «نخ مالک» و «سطح بازگشت» استفاده می‌کند. در وضعیت قفل‌شده، نخی مالک قفل است؛ در وضعیت قفل‌نشده، هیچ نخی مالک آن نیست.

نخ‌ها برای قفل کردن یک قفل، متد acquire() آن و برای باز کردن قفل آن، متد release() آن را فراخوانی می‌کنند.

جفت‌های فراخوانی acquire()/release() در RLock می‌توانند تودرتو باشند، برخلاف acquire()/release() در Lock. تنها آخرین release() (یعنی release() از بیرونی‌ترین جفت) قفل را به وضعیت قفل‌نشده بازنشانی می‌کند و به نخ دیگری که در acquire() مسدود شده است اجازه می‌دهد ادامه دهد.

acquire()/release() باید به‌صورت جفت استفاده شوند: هر فراخوانی acquire باید یک فراخوانی release در نخی که قفل را کسب کرده است داشته باشد. عدم فراخوانی release به تعداد دفعاتی که قفل کسب شده است می‌تواند منجر به بن‌بست شود.

class threading.RLock¶

این کلاس اشیای قفل بازورودپذیر (reentrant lock) را پیاده‌سازی می‌کند. یک قفل بازورودپذیر باید توسط نخی که آن را به دست آورده است آزاد شود. هنگامی که نخی یک قفل بازورودپذیر را به دست آورده باشد، همان نخ می‌تواند دوباره آن را بدون مسدود شدن به دست آورد؛ نخ باید به ازای هر باری که آن را به دست آورده است، یک‌بار آن را آزاد کند.

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

acquire(blocking=True, timeout=-1)¶

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

همچنین ببینید

استفاده از RLock به‌عنوان مدیر زمینه

هر زمان که عملی باشد، به جای فراخوانی‌های دستی acquire() و release() توصیه می‌شود.

هنگامی که با آرگومان blocking روی True (پیش‌فرض) فراخوانی شود:

• اگر هیچ نخی مالک قفل نباشد، قفل را به دست می‌آورد و بلافاصله بازمی‌گردد.

• اگر نخ دیگری مالک قفل باشد، تا زمانی که بتوانیم قفل را به‌دست آوریم مسدود بمانید، یا اگر timeout روی یک مقدار مثبت تنظیم شده باشد، تا فرا رسیدن آن.

• اگر همان نخ مالک قفل باشد، قفل را دوباره به دست می‌آورد و بلافاصله بازمی‌گردد. این تفاوت میان Lock و RLock است؛ Lock این حالت را مانند حالت قبلی مدیریت می‌کند و تا زمانی که قفل بتواند به دست آید، مسدود می‌شود.

هنگامی که با آرگومان blocking تنظیم‌شده روی False فراخوانی شود:

• اگر هیچ نخی مالک قفل نباشد، قفل را به دست می‌آورد و بلافاصله بازمی‌گردد.

• اگر نخ دیگری مالک قفل باشد، بلافاصله بازمی‌گردد.

• اگر همان نخ مالک قفل باشد، قفل را دوباره به دست می‌آورد و بلافاصله بازمی‌گردد.

در همه‌ی موارد، اگر نخ توانسته باشد قفل را به دست آورد، True برمی‌گرداند. اگر نخ نتوانسته باشد قفل را به دست آورد (یعنی اگر مسدودکننده نباشد یا مهلت به پایان رسیده باشد)، False برمی‌گرداند.

اگر چندین بار فراخوانی شود، فراخوانی نکردن release() به همان تعداد ممکن است به بن‌بست منجر شود. بهتر است به‌جای فراخوانی مستقیم acquire/release، از RLock به‌عنوان مدیر زمینه استفاده کنید.

تغییر یافته در نسخه‌ی 3.2: پارامتر timeout جدید است.

تغییر یافته در نسخه‌ی 3.15: هر عدد حقیقی را به عنوان timeout می‌پذیرد، و محدود به عدد صحیح یا اعشاری نیست.

release()¶

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

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

هیچ مقدار بازگشتی وجود ندارد.

locked()¶

یک بولی برمی‌گرداند که نشان می‌دهد آیا این شیء در حال حاضر قفل است یا خیر.

اضافه شده در نسخه‌ی 3.14.

اشیای شرط¶

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

یک متغیر شرط از پروتکل مدیریت زمینه پیروی می‌کند: استفاده از دستور with، قفل مرتبط را در طول بلوک محصورشده به دست می‌آورد. متدهای acquire() و release() نیز متدهای متناظر قفل مرتبط را فراخوانی می‌کنند.

سایر متدها باید در حالی فراخوانی شوند که قفل مرتبط نگه داشته شده باشد. متد wait() قفل را آزاد می‌کند و سپس مسدود می‌شود تا نخ دیگری با فراخوانی notify() یا notify_all() آن را بیدار کند. پس از بیدار شدن، wait() دوباره قفل را به دست می‌آورد و بازمی‌گردد. همچنین می‌توان یک مهلت زمانی مشخص کرد.

متد notify() یکی از نخ‌های در انتظار متغیر شرطی را، در صورتی که منتظری وجود داشته باشد، بیدار می‌کند. متد notify_all() همه نخ‌های در انتظار متغیر شرطی را بیدار می‌کند.

توجه: متدهای notify() و notify_all() قفل را آزاد نمی‌کنند؛ این بدان معناست که نخ یا نخ‌های بیدارشده بلافاصله از فراخوانی wait() خود بازنمی‌گردند، بلکه تنها زمانی بازمی‌گردند که نخی که notify() یا notify_all() را فراخوانی کرده باشد، سرانجام مالکیت قفل را واگذار کند.

سبک برنامه‌نویسی رایج با استفاده از متغیرهای شرطی، از قفل برای همگام‌سازی دسترسی به یک وضعیت مشترک استفاده می‌کند؛ نخ‌هایی که به تغییر خاصی در وضعیت علاقه‌مند هستند، wait() را به‌طور مکرر فراخوانی می‌کنند تا وضعیت مطلوب را مشاهده کنند، در حالی که نخ‌هایی که وضعیت را تغییر می‌دهند، هنگامی که وضعیت را به‌گونه‌ای تغییر می‌دهند که ممکن است وضعیت مطلوبی برای یکی از نخ‌های منتظر باشد، notify() یا notify_all() را فراخوانی می‌کنند. برای مثال، کد زیر یک موقعیت عام تولیدکننده-مصرف‌کننده با ظرفیت نامحدود بافر است:

# Consume one item
with cv:
    while not an_item_is_available():
        cv.wait()
    get_an_available_item()

# Produce one item
with cv:
    make_an_item_available()
    cv.notify()

حلقه‌ی while که شرط برنامه را بررسی می‌کند، ضروری است، زیرا wait() می‌تواند پس از مدت زمانی دلخواه و طولانی بازگشت کند، و ممکن است شرطی که موجب فراخوانی notify() شده است دیگر برقرار نباشد. این موضوع ذاتی برنامه‌نویسی چندنخی است. متد wait_for() می‌تواند برای خودکارسازی بررسی شرط به کار رود و محاسبه‌ی مهلت‌های زمانی را آسان‌تر کند:

# Consume an item
with cv:
    cv.wait_for(an_item_is_available)
    get_an_available_item()

برای انتخاب بین notify() و notify_all()، در نظر بگیرید که آیا یک تغییر وضعیت می‌تواند تنها برای یک یا چند نخ در انتظار مهم باشد. به‌عنوان مثال در یک موقعیت معمول تولیدکننده-مصرف‌کننده، افزودن یک آیتم به بافر تنها نیاز به بیدار کردن یک نخ مصرف‌کننده دارد.

class threading.Condition(lock=None)¶

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

اگر آرگومان lock داده شده باشد و None نباشد، باید یک شیء Lock یا RLock باشد و به‌عنوان قفل زیربنایی استفاده می‌شود. در غیر این صورت، یک شیء RLock جدید ایجاد می‌شود و به‌عنوان قفل زیربنایی استفاده می‌شود.

تغییر یافته در نسخه‌ی 3.3: از یک تابع کارخانه به یک کلاس تغییر کرده است.

acquire(*args)¶

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

release()¶

قفل زیربنایی را آزاد می‌کند. این متد، متد متناظر روی قفل زیربنایی را فراخوانی می‌کند؛ مقدار بازگشتی وجود ندارد.

locked()¶

یک بولی برمی‌گرداند که نشان می‌دهد آیا این شیء در حال حاضر قفل است یا خیر.

اضافه شده در نسخه‌ی 3.14.

wait(timeout=None)¶

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

این متد قفل زیربنایی را آزاد می‌کند و سپس مسدود می‌شود تا با فراخوانی notify() یا notify_all() برای همان متغیر شرطی در یک نخ دیگر بیدار شود، یا تا زمانی که مهلت اختیاری به پایان برسد. پس از بیدار شدن یا به پایان رسیدن مهلت، قفل را دوباره به دست می‌آورد و بازمی‌گردد.

هنگامی که آرگومان timeout موجود باشد و برابر با None نباشد، باید یک عدد حقیقی باشد که مهلت زمانی عملیات را برحسب ثانیه (یا کسری از آن) مشخص می‌کند.

هنگامی که قفل زیربنایی یک RLock باشد، با استفاده از متد release() آن آزاد نمی‌شود، زیرا اگر قفل چندین بار به‌صورت بازگشتی کسب شده باشد، این کار ممکن است واقعاً قفل را باز نکند. در عوض، از یک رابط داخلی کلاس RLock استفاده می‌شود که حتی اگر قفل چندین بار به‌صورت بازگشتی کسب شده باشد، واقعاً آن را باز می‌کند. سپس از یک رابط داخلی دیگر برای بازگرداندن سطح بازگشت، هنگامی که قفل دوباره کسب می‌شود، استفاده می‌شود.

مقدار بازگشتی True است، مگر اینکه timeout داده‌شده منقضی‌شده باشد، که در این صورت False است.

تغییر یافته در نسخه‌ی 3.2: پیش از این، این متد همیشه None را برمی‌گرداند.

wait_for(predicate, timeout=None)¶

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

این متد کاربردی ممکن است wait() را به‌طور مکرر فراخوانی کند تا محمول برقرار شود یا مهلت زمانی‌ای رخ دهد. مقدار بازگشتی، آخرین مقدار بازگشتی محمول است و اگر متد دچار مهلت زمانی شده باشد، به False ارزیابی می‌شود.

با چشم‌پوشی از قابلیت مهلت زمانی، فراخوانی این متد تقریباً معادل نوشتن این است:

while not predicate():
    cv.wait()

بنابراین، همان قواعدی که برای wait() اعمال می‌شوند، در اینجا نیز اعمال می‌شوند: هنگام فراخوانی باید قفل گرفته‌شده باشد و در زمان بازگشت دوباره گرفته می‌شود. محمول در حالی که قفل گرفته‌شده است، ارزیابی می‌شود.

اضافه شده در نسخه‌ی 3.2.

notify(n=1)¶

به‌طور پیش‌فرض، در صورت وجود، یک نخ منتظر روی این شرط را بیدار می‌کند. اگر نخ فراخواننده هنگام فراخوانی این متد قفل را کسب نکرده باشد، یک RuntimeError پرتاب می‌شود.

این متد حداکثر n نخ از نخ‌هایی که در انتظار متغیر شرطی هستند را بیدار می‌کند؛ اگر هیچ نخی در انتظار نباشد، هیچ کاری انجام نمی‌شود.

پیاده‌سازی فعلی، اگر حداقل n نخ در انتظار باشند، دقیقاً n نخ را بیدار می‌کند. با این حال، اتکا به این رفتار ایمن نیست. ممکن است یک پیاده‌سازی بهینه‌شده در آینده گاهی بیش از n نخ را بیدار کند.

توجه: یک نخ بیدارشده در واقع تا زمانی که بتواند قفل را دوباره به دست آورد، از فراخوانی wait() خود بازگشت نمی‌کند. از آن‌جا که notify() قفل را آزاد نمی‌کند، فراخواننده‌ی آن باید این کار را انجام دهد.

notify_all()¶

همه نخ‌های در انتظار این شرط را بیدار می‌کند. این متد مانند notify() عمل می‌کند، اما به جای یک نخ، همه نخ‌های در انتظار را بیدار می‌کند. اگر نخ فراخوان هنگام فراخوانی این متد قفل را به دست نیاورده باشد، یک RuntimeError پرتاب می‌شود.

متد notifyAll یک نام مستعار منسوخ برای این متد است.

اشیای سمافور¶

این یکی از قدیمی‌ترین سازوکارهای اولیه‌ی همگام‌سازی در تاریخ علوم کامپیوتر است که توسط Edsger W. Dijkstra، دانشمند پیشگام هلندی در علوم کامپیوتر، ابداع شد (او به‌جای acquire() و release() از نام‌های P() و V() استفاده می‌کرد).

سمافور یک شمارنده داخلی را مدیریت می‌کند که با هر فراخوانی acquire() کاهش می‌یابد و با هر فراخوانی release() افزایش می‌یابد. شمارنده هرگز نمی‌تواند به زیر صفر برسد؛ هرگاه acquire() مقدار آن را صفر بیابد، مسدود می‌شود و منتظر می‌ماند تا نخ دیگری release() را فراخوانی کند.

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

class threading.Semaphore(value=1)¶

این کلاس اشیای سمافور را پیاده‌سازی می‌کند. یک سمافور یک شمارنده اتمی را مدیریت می‌کند که بیانگر تعداد فراخوانی‌های release() منهای تعداد فراخوانی‌های acquire()، به‌علاوه یک مقدار اولیه است. متد acquire() در صورت لزوم مسدود می‌شود تا بتواند بدون منفی کردن شمارنده بازگشت کند. اگر داده نشود، value به‌طور پیش‌فرض ۱ است.

آرگومان اختیاری، value اولیه برای شمارنده داخلی را مشخص می‌کند؛ پیش‌فرض آن 1 است. اگر مقدار داده‌شده کمتر از ۰ باشد، ValueError پرتاب می‌شود.

تغییر یافته در نسخه‌ی 3.3: از یک تابع کارخانه به یک کلاس تغییر کرده است.

acquire(blocking=True, timeout=None)¶

یک سمافور را کسب می‌کند.

هنگام فراخوانی بدون آرگومان:

• اگر شمارنده‌ی داخلی در هنگام ورود بزرگ‌تر از صفر باشد، آن را یک واحد کاهش دهید و بلافاصله True را برگردانید.

• اگر شمارنده‌ی داخلی در زمان ورود صفر باشد، تا زمانی که با فراخوانی release() بیدار شود، مسدود می‌شود. پس از بیدار شدن (و زمانی که شمارنده بزرگ‌تر از ۰ باشد)، شمارنده را یک واحد کاهش می‌دهد و True را برمی‌گرداند. با هر فراخوانی release()، دقیقاً یک نخ بیدار خواهد شد. نباید به ترتیبی که نخ‌ها بیدار می‌شوند، اتکا کرد.

هنگامی که با blocking تنظیم‌شده روی False فراخوانی شود، مسدود نمی‌شود. اگر یک فراخوانی بدون آرگومان قرار باشد مسدود شود، بلافاصله False را برمی‌گرداند؛ در غیر این صورت، همان کاری را انجام می‌دهد که هنگام فراخوانی بدون آرگومان‌ها انجام می‌شود، و True را برمی‌گرداند.

هنگامی که با timeout غیر از None فراخوانی شود، حداکثر به مدت timeout ثانیه مسدود می‌شود. اگر acquire در این بازه با موفقیت به پایان نرسد، False را برمی‌گرداند. در غیر این صورت، True را برمی‌گرداند.

تغییر یافته در نسخه‌ی 3.2: پارامتر timeout جدید است.

تغییر یافته در نسخه‌ی 3.15: هر عدد حقیقی را به عنوان timeout می‌پذیرد، و محدود به عدد صحیح یا اعشاری نیست.

release(n=1)¶

یک سمافور را آزاد می‌کند و شمارنده داخلی را به اندازه n افزایش می‌دهد. اگر در زمان ورود ۰ بوده باشد و نخ‌های دیگری در انتظار باشند تا دوباره بزرگ‌تر از ۰ شود، n نخ از آن نخ‌ها را بیدار می‌کند.

تغییر یافته در نسخه‌ی 3.9: پارامتر n اضافه شد تا چندین نخ در انتظار به‌صورت همزمان آزاد شوند.

class threading.BoundedSemaphore(value=1)¶

کلاسی که اشیای سمافور محدود (bounded semaphore) را پیاده‌سازی می‌کند. سمافور محدود بررسی می‌کند که مقدار فعلی‌اش از مقدار اولیه‌اش بیشتر نشود. در این صورت، ValueError پرتاب می‌شود. در بیشتر موارد، از سمافورها برای محافظت از منابع با ظرفیت محدود استفاده می‌شود. اگر سمافور بیش از حد آزاد شود، نشانه‌ای از یک اشکال است. اگر داده نشود، value به‌طور پیش‌فرض ۱ است.

تغییر یافته در نسخه‌ی 3.3: از یک تابع کارخانه به یک کلاس تغییر کرده است.

مثال Semaphore¶

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

maxconnections = 5
# ...
pool_sema = BoundedSemaphore(value=maxconnections)

پس از ایجاد، نخ‌های کارگر هنگامی که نیاز به اتصال به سرور دارند، متدهای acquire و release سمافور را فراخوانی می‌کنند:

with pool_sema:
    conn = connectdb()
    try:
        # ... use connection ...
    finally:
        conn.close()

استفاده از یک سمافور محدود (bounded semaphore) احتمال بدون تشخیص ماندن یک خطای برنامه‌نویسی را، که باعث می‌شود سمافور بیش از تعداد دفعات کسب‌شده آزاد شود، کاهش می‌دهد.

اشیای رویداد¶

این یکی از ساده‌ترین سازوکارها برای ارتباط میان نخ‌ها است: یک نخ رویدادی را سیگنال می‌کند و نخ‌های دیگر منتظر آن می‌مانند.

یک شیء رویداد، یک پرچم داخلی را مدیریت می‌کند که می‌توان آن را با متد set() روی true تنظیم کرد و با متد clear() به false بازنشانی کرد. متد wait() تا زمانی که پرچم true شود، مسدود می‌شود.

class threading.Event¶

کلاسی که اشیای رویداد را پیاده‌سازی می‌کند. یک رویداد پرچمی را مدیریت می‌کند که می‌توان آن را با متد set() روی درست تنظیم کرد و با متد clear() به نادرست بازنشانی کرد. متد wait() تا زمانی که پرچم درست شود، مسدود می‌شود. پرچم در ابتدا نادرست است.

تغییر یافته در نسخه‌ی 3.3: از یک تابع کارخانه به یک کلاس تغییر کرده است.

is_set()¶

فقط و فقط در صورتی True را برمی‌گرداند که پرچم داخلی true باشد.

متد isSet یک نام مستعار منسوخ برای این متد است.

set()¶

پرچم داخلی را روی true قرار دهید. همه نخ‌هایی که منتظر true شدن آن هستند، بیدار می‌شوند. نخ‌هایی که پس از true بودن پرچم، wait() را فراخوانی کنند، به‌هیچ‌وجه مسدود نخواهند شد.

clear()¶

پرچم داخلی را روی false بازنشانی می‌کند. پس از آن، نخ‌هایی که wait() را فراخوانی می‌کنند، مسدود می‌شوند تا زمانی که set() فراخوانی شود و پرچم داخلی دوباره روی true تنظیم شود.

wait(timeout=None)¶

تا زمانی که پرچم داخلی نادرست است و مهلت، در صورت تعیین شدن، منقضی نشده باشد، مسدود می‌کند. مقدار بازگشتی، دلیل بازگشت این متد مسدودکننده را نشان می‌دهد؛ True اگر بازگشت به این دلیل باشد که پرچم داخلی روی درست تنظیم شده است، یا False اگر مهلتی تعیین شده باشد و پرچم داخلی در مهلت زمانی تعیین‌شده درست نشده باشد.

هنگامی که آرگومان timeout موجود باشد و برابر با None نباشد، باید یک عدد حقیقی باشد که مهلت زمانی عملیات را برحسب ثانیه، یا کسری از آن، مشخص می‌کند.

تغییر یافته در نسخه‌ی 3.1: پیش از این، این متد همیشه None را برمی‌گرداند.

اشیای Timer¶

این کلاس نشان‌دهنده‌ی عملیاتی است که باید تنها پس از گذشت مدت زمان معینی اجرا شود — یک زمان‌سنج. Timer یک زیرکلاس از Thread است و از این رو، به‌عنوان نمونه‌ای از ایجاد نخ‌های سفارشی نیز عمل می‌کند.

زمان‌سنج‌ها، مانند نخ‌ها، با فراخوانی متد Timer.start خود آغاز می‌شوند. می‌توان زمان‌سنج را (پیش از آغاز عملش) با فراخوانی متد cancel() متوقف کرد. ممکن است بازه زمانی که زمان‌سنج پیش از اجرای عمل خود منتظر می‌ماند، دقیقاً برابر با بازه زمانی که کاربر مشخص کرده است نباشد.

برای مثال:

def hello():
    print("hello, world")

t = Timer(30.0, hello)
t.start()  # after 30 seconds, "hello, world" will be printed

class threading.Timer(interval, function, args=None, kwargs=None)¶

یک زمان‌سنج ایجاد کنید که function را با آرگومان‌های args و آرگومان‌های کلیدواژه‌ای kwargs، پس از گذشت interval ثانیه اجرا خواهد کرد. اگر args برابر None باشد (پیش‌فرض)، از یک فهرست خالی استفاده خواهد شد. اگر kwargs برابر None باشد (پیش‌فرض)، از یک دیکشنری خالی استفاده خواهد شد.

تغییر یافته در نسخه‌ی 3.3: از یک تابع کارخانه به یک کلاس تغییر کرده است.

cancel()¶

تایمر را متوقف کنید و اجرای عمل تایمر را لغو کنید. این کار تنها زمانی کار می‌کند که تایمر هنوز در مرحله‌ی انتظار باشد.

اشیای سد (Barrier)¶

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

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

به‌عنوان مثال، در اینجا یک روش ساده برای همگام‌سازی نخ کلاینت و سرور آمده است:

b = Barrier(2, timeout=5)

def server():
    start_server()
    b.wait()
    while True:
        connection = accept_connection()
        process_server_connection(connection)

def client():
    b.wait()
    while True:
        connection = make_connection()
        process_client_connection(connection)

class threading.Barrier(parties, action=None, timeout=None)¶

یک شیء سد (barrier) برای تعداد parties نخ ایجاد کنید. اگر action ارائه شود، یک شیء فراخوانی‌پذیر است که هنگامی که نخ‌ها آزاد می‌شوند، توسط یکی از آن‌ها فراخوانی می‌شود. timeout مقدار پیش‌فرض مهلت است، اگر هیچ مقداری برای متد wait() مشخص نشده باشد.

wait(timeout=None)¶

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

مقدار بازگشتی یک عدد صحیح در بازه‌ی ۰ تا parties -- ۱ است و برای هر نخ متفاوت است. می‌توان از این مقدار برای انتخاب یک نخ جهت انجام برخی کارهای نظافتی خاص استفاده کرد، مثلاً:

i = barrier.wait()
if i == 0:
    # Only one thread needs to print this
    print("passed the barrier")

اگر action به سازنده ارائه شده باشد، یکی از نخ‌ها آن را پیش از آزاد شدن فراخوانی خواهد کرد. چنانچه این فراخوانی خطایی را پرتاب کند، سد (barrier) در وضعیت شکسته قرار می‌گیرد.

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

این متد ممکن است در صورتی که سد (barrier) در حین انتظار یک نخ شکسته یا بازنشانی شود، استثنای BrokenBarrierError را پرتاب کند.

reset()¶

سد (barrier) را به وضعیت پیش‌فرض و خالی بازمی‌گرداند. هر نخی که در انتظار آن باشد، استثنای BrokenBarrierError را دریافت خواهد کرد.

توجه داشته باشید که استفاده از این تابع ممکن است در صورت وجود نخ‌های دیگری که وضعیت آن‌ها نامشخص است، به کمی همگام‌سازی خارجی نیاز داشته باشد. اگر یک سد (barrier) شکسته شود، ممکن است بهتر باشد صرفاً آن را رها کنید و یک سد جدید ایجاد کنید.

abort()¶

سد را در وضعیت شکسته قرار دهید. این کار باعث می‌شود هر فراخوانی فعال یا آینده‌ی wait() با BrokenBarrierError شکست بخورد. برای مثال، اگر یکی از نخ‌ها نیاز به لغو شدن دارد، از این کار استفاده کنید تا از بن‌بست برنامه جلوگیری شود.

ممکن است بهتر باشد صرفاً یک سد (barrier) با مقدار معقول timeout ایجاد کنید تا به‌طور خودکار در برابر از مسیر خارج شدن یکی از نخ‌ها محافظت شود.

parties¶

تعداد نخ‌های لازم برای عبور از سد.

n_waiting¶

تعداد نخ‌هایی که در حال حاضر در سد منتظر هستند.

broken¶

یک بولی که اگر سد در وضعیت شکسته باشد، True است.

exception threading.BrokenBarrierError¶

این استثنا، که زیرکلاسی از RuntimeError است، زمانی پرتاب می‌شود که شیء Barrier بازنشانی یا شکسته شود.