sched --- زمان‌بند رویداد

کد منبع: Lib/sched.py

---

ماژول sched کلاسی را تعریف می‌کند که یک زمان‌بند رویداد همه‌منظوره را پیاده‌سازی می‌کند:

class sched.scheduler(timefunc=time.monotonic, delayfunc=time.sleep)

کلاس scheduler یک رابط عام برای زمان‌بندی رویدادها تعریف می‌کند. این کلاس برای تعامل واقعی با «دنیای بیرون» به دو تابع نیاز دارد --- timefunc باید بدون آرگومان فراخوانی‌پذیر باشد و یک عدد برگرداند (عدد «زمان»، در هر واحدی که باشد). تابع delayfunc باید با یک آرگومان قابل فراخوانی باشد، با خروجی timefunc سازگار باشد و به همان تعداد واحد زمان تأخیر ایجاد کند. delayfunc همچنین پس از اجرای هر رویداد با آرگومان 0 فراخوانی می‌شود تا در برنامه‌های چندنخی، به سایر نخ‌ها فرصتی برای اجرا داده شود.

تغییر یافته در نسخه‌ی 3.3: پارامترهای timefunc و delayfunc اختیاری هستند.

تغییر یافته در نسخه‌ی 3.3: می‌توان از کلاس scheduler به‌صورت ایمن در محیط‌های چندنخی استفاده کرد.

مثال:

>>> import sched, time
>>> s = sched.scheduler(time.time, time.sleep)
>>> def print_time(a='default'):
...     print("From print_time", time.time(), a)
...
>>> def print_some_times():
...     print(time.time())
...     s.enter(10, 1, print_time)
...     s.enter(5, 2, print_time, argument=('positional',))
...     # despite having higher priority, 'keyword' runs after 'positional' as enter() is relative
...     s.enter(5, 1, print_time, kwargs={'a': 'keyword'})
...     s.enterabs(1_650_000_000, 10, print_time, argument=("first enterabs",))
...     s.enterabs(1_650_000_000, 5, print_time, argument=("second enterabs",))
...     s.run()
...     print(time.time())
...
>>> print_some_times()
1652342830.3640375
From print_time 1652342830.3642538 second enterabs
From print_time 1652342830.3643398 first enterabs
From print_time 1652342835.3694863 positional
From print_time 1652342835.3696074 keyword
From print_time 1652342840.369612 default
1652342840.3697174

اشیای زمان‌بند

نمونه‌های scheduler دارای متدها و ویژگی‌های زیر هستند:

scheduler.enterabs(time, priority, action, argument=(), kwargs={})

یک رویداد جدید را زمان‌بندی کنید. آرگومان time باید یک نوع عددی سازگار با مقدار بازگشتی تابع timefunc باشد که به سازنده ارسال شده است. رویدادهای زمان‌بندی‌شده برای time یکسان، به ترتیب priority آن‌ها اجرا می‌شوند. عدد کوچک‌تر نشان‌دهنده اولویت بالاتر است.

اجرای رویداد به معنای اجرای action(*argument, **kwargs) است. argument یک دنباله است که آرگومان‌های جایگاهی برای action را نگه می‌دارد. kwargs یک دیکشنری است که آرگومان‌های کلیدواژه‌ای برای action را نگه می‌دارد.

مقدار بازگشتی یک رویداد است که می‌توان از آن برای لغو بعدی رویداد استفاده کرد (به cancel() مراجعه کنید).

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

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

scheduler.enter(delay, priority, action, argument=(), kwargs={})

رویدادی را برای delay واحد زمانی بیشتر زمان‌بندی می‌کند. به جز زمان نسبی، سایر آرگومان‌ها، اثر و مقدار بازگشتی همانند موارد enterabs() هستند.

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

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

scheduler.cancel(event)

رویداد را از صف حذف می‌کند. اگر event رویدادی نباشد که در حال حاضر در صف قرار دارد، این متد یک ValueError پرتاب می‌کند.

scheduler.empty()

اگر صف رویداد خالی باشد، True را برمی‌گرداند.

scheduler.run(blocking=True)

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

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

هر یک از action یا delayfunc می‌توانند یک استثنا پرتاب کنند. در هر صورت، زمان‌بند وضعیت سازگار را حفظ می‌کند و استثنا را منتشر می‌کند. اگر استثنایی توسط action پرتاب شود، برای اجرای رویداد در فراخوانی‌های آینده‌ی run() تلاشی نخواهد شد.

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

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

scheduler.queue

ویژگی فقط‌خواندنی که فهرستی از رویدادهای پیش‌رو را به ترتیبی که اجرا خواهند شد بازمی‌گرداند. هر رویداد به‌صورت یک named tuple با فیلدهای زیر نمایش داده می‌شود: time، priority، action، argument، kwargs.