asyncio — מתזמן קלט/פלט אסינכרוני

מודול זה מספק מתזמן ריבוי-משימות שיתופי עבור קורוטינות async/await, יחד עם פרימיטיבים לסנכרון (מנעולים, אירועים) ועבודה לא-חוסמת ברשת TCP באמצעות קוראי וכותבי זרמים. משימות רצות במקביל על לולאת אירועים יחידה; המשימה הרצה כעת מחזירה את השליטה ללולאה באמצעות await.

דוגמה:

import asyncio

async def blink(led, period_ms):
    while True:
        led.on()
        await asyncio.sleep_ms(5)
        led.off()
        await asyncio.sleep_ms(period_ms)

async def main(led1, led2):
    asyncio.create_task(blink(led1, 700))
    asyncio.create_task(blink(led2, 400))
    await asyncio.sleep_ms(10_000)

# Running on an OpenMV Cam
from machine import LED
asyncio.run(main(LED(1), LED(2)))

פונקציות ליבה

asyncio.create_task(coro: Coroutine) → Task

יצירת משימה חדשה מתוך הקורוטינה הנתונה ותזמונה לריצה.

מחזירה את אובייקט Task המתאים.

asyncio.current_task() → Task

מחזירה את אובייקט Task המשויך למשימה הרצה כעת.

asyncio.run(coro: Coroutine) → Any

יצירת משימה חדשה מתוך הקורוטינה הנתונה והרצתה עד להשלמתה.

מחזירה את הערך שהוחזר על ידי coro.

asyncio.sleep(t: float) → None

שינה למשך t שניות (יכול להיות מספר עשרוני).

זוהי קורוטינה.

asyncio.sleep_ms(t: int) → None

שינה למשך t מילישניות.

זוהי קורוטינה, והרחבה של MicroPython.

פונקציות נוספות

asyncio.wait_for(awaitable: Awaitable, timeout: float) → Any

המתנה להשלמת awaitable, אך ביטולו אם הוא נמשך יותר מ-timeout שניות. אם awaitable אינו משימה, תיווצר ממנו משימה.

אם מתרחש timeout, היא מבטלת את המשימה ומעלה asyncio.TimeoutError: על הקורא לתפוס חריגה זו. המשימה מקבלת asyncio.CancelledError אשר ניתן להתעלם ממנה או לתפוס אותה באמצעות try...except או try...finally כדי להריץ קוד ניקוי.

מחזירה את ערך ההחזרה של awaitable.

זוהי קורוטינה.

asyncio.wait_for_ms(awaitable: Awaitable, timeout: int) → Any

דומה ל-wait_for() אך timeout הוא מספר שלם במילישניות.

זוהי קורוטינה, והרחבה של MicroPython.

asyncio.gather(*awaitables, return_exceptions: bool = False) → List

הרצת כל ה-awaitables במקביל. כל awaitables שאינם משימות מקודמים למשימות.

מחזירה רשימה של ערכי ההחזרה של כל ה-awaitables.

זוהי קורוטינה.

class Task

class asyncio.Task

אובייקט זה עוטף קורוטינה למשימה רצה. ניתן להמתין למשימות באמצעות await task, מה שימתין להשלמת המשימה ויחזיר את ערך ההחזרה שלה.

אין ליצור משימות באופן ישיר, אלא יש להשתמש ב-create_task() כדי ליצור אותן.

cancel() → None

ביטול המשימה על ידי הזרקת asyncio.CancelledError לתוכה. המשימה עשויה להתעלם מחריגה זו. ניתן להריץ קוד ניקוי על ידי תפיסתה, או באמצעות try ... finally.

class Event

class asyncio.Event

יצירת אירוע חדש שניתן להשתמש בו לסנכרון משימות. אירועים מתחילים במצב מנוקה.

is_set() → bool

מחזירה True אם האירוע מוגדר, False אחרת.

set() → None

הגדרת האירוע. כל המשימות הממתינות לאירוע יתוזמנו לריצה.

הערה: יש לקרוא לזה מתוך משימה. אין זה בטוח לקרוא לזה מתוך IRQ, פונקציית callback של המתזמן, או חוט אחר. ראו ThreadSafeFlag.

clear() → None

ניקוי האירוע.

wait() → None

המתנה להגדרת האירוע. אם האירוע כבר מוגדר, היא חוזרת מיד.

זוהי קורוטינה.

class ThreadSafeFlag

class asyncio.ThreadSafeFlag

יצירת דגל חדש שניתן להשתמש בו לסנכרון משימה עם קוד הרץ מחוץ ללולאת asyncio, כגון חוטים אחרים, IRQs, או פונקציות callback של המתזמן. דגלים מתחילים במצב מנוקה.

set() → None

הגדרת הדגל. אם קיימת משימה הממתינה לדגל, היא תתוזמן לריצה.

clear() → None

ניקוי הדגל. ניתן להשתמש בזה כדי לוודא שדגל שאולי הוגדר קודם לכן מנוקה לפני ההמתנה לו.

wait() → None

המתנה להגדרת הדגל. אם הדגל כבר מוגדר, היא חוזרת מיד. הדגל מאופס אוטומטית עם החזרה מ-wait.

דגל יכול להיות מומתן על ידי משימה אחת בלבד בכל זמן נתון.

זוהי קורוטינה.

class Lock

class asyncio.Lock

יצירת מנעול חדש שניתן להשתמש בו לתיאום משימות. מנעולים מתחילים במצב לא-נעול.

בנוסף למתודות שלהלן, ניתן להשתמש במנעולים במשפט async with.

locked() → bool

מחזירה True אם המנעול נעול, אחרת False.

acquire() → bool

המתנה לכך שהמנעול יהיה במצב לא-נעול ואז נעילתו באופן אטומי. רק משימה אחת יכולה לרכוש את המנעול בכל זמן נתון.

זוהי קורוטינה.

release() → None

שחרור המנעול. אם משימות כלשהן ממתינות למנעול, הבאה בתור מתוזמנת לריצה והמנעול נשאר נעול. אחרת, אין משימות ממתינות והמנעול הופך ללא-נעול.

חיבורי זרם TCP

asyncio.open_connection(host: str, port: int, ssl: ssl.SSLContext | bool | None = None) → Tuple[Stream, Stream]

פתיחת חיבור TCP אל ה-host וה-port הנתונים. כתובת ה-host תיפתר באמצעות socket.getaddrinfo(), שהיא כרגע קריאה חוסמת. אם ssl הוא אובייקט ssl.SSLContext, הקשר הזה משמש ליצירת ערוץ התעבורה; אם ssl הוא True, נעשה שימוש בקשר ברירת מחדל.

מחזירה זוג זרמים: זרם קורא וזרם כותב. תעלה OSError ייחודי ל-socket אם לא ניתן היה לפתור את ה-host או אם לא ניתן היה ליצור את החיבור.

זוהי קורוטינה.

asyncio.start_server(callback: Callable, host: str, port: int, backlog: int = 5, ssl: ssl.SSLContext | None = None) → Server

הפעלת שרת TCP על ה-host וה-port הנתונים. תתבצע קריאה ל-callback עבור חיבורים נכנסים שהתקבלו, ויועברו לה 2 ארגומנטים: זרם קורא וזרם כותב עבור החיבור.

אם ssl הוא אובייקט ssl.SSLContext, הקשר הזה משמש ליצירת ערוץ התעבורה.

מחזירה אובייקט Server.

זוהי קורוטינה.

class asyncio.Stream

זה מייצג חיבור זרם TCP. כדי למזער קוד, מחלקה זו מממשת גם קורא וגם כותב, וגם StreamReader וגם StreamWriter הם כינויים למחלקה זו.

get_extra_info(v: str) → Any

קבלת מידע נוסף על הזרם, הנתון על ידי v. הערכים החוקיים עבור v הם: peername.

close() → None

סגירת הזרם.

wait_closed() → None

המתנה לסגירת הזרם.

זוהי קורוטינה.

read(n: int = -1) → bytes

קריאת עד n בתים והחזרתם. אם n אינו מסופק או הוא -1, קריאת כל הבתים עד EOF. הערך המוחזר יהיה אובייקט bytes ריק אם נתקלים ב-EOF לפני שנקראים בתים כלשהם.

זוהי קורוטינה.

readinto(buf: bytearray | memoryview) → int

קריאת עד n בתים לתוך buf, כאשר n שווה לאורך של buf.

מחזירה את מספר הבתים שנקראו לתוך buf.

זוהי קורוטינה, והרחבה של MicroPython.

readexactly(n: int) → bytes

קריאת בדיוק n בתים והחזרתם כאובייקט bytes.

מעלה חריגת EOFError אם הזרם מסתיים לפני קריאת n בתים.

זוהי קורוטינה.

readline() → bytes

קריאת שורה והחזרתה.

זוהי קורוטינה.

write(buf: bytes) → None

צבירת buf לחוצץ הפלט. הנתונים נשטפים רק כאשר נקראת Stream.drain(). מומלץ לקרוא ל-Stream.drain() מיד לאחר קריאה לפונקציה זו.

drain() → None

שטיפה (כתיבה) של כל נתוני הפלט שבחוצץ אל הזרם.

זוהי קורוטינה.

class asyncio.Server

זה מייצג את מחלקת השרת המוחזרת מ-start_server(). ניתן להשתמש בה במשפט async with כדי לסגור את השרת ביציאה.

close() → None

סגירת השרת.

wait_closed() → None

המתנה לסגירת השרת.

זוהי קורוטינה.

לולאת אירועים

asyncio.get_event_loop() → Loop

מחזירה את לולאת האירועים המשמשת לתזמון והרצת משימות. ראו Loop.

asyncio.new_event_loop() → Loop

איפוס לולאת האירועים והחזרתה.

הערה: מאחר של-MicroPython יש לולאת אירועים יחידה בלבד, פונקציה זו רק מאפסת את מצב הלולאה, היא אינה יוצרת לולאה חדשה.

class asyncio.Loop

זה מייצג את האובייקט המתזמן ומריץ משימות. לא ניתן ליצור אותו, השתמשו ב-get_event_loop() במקום זאת.

create_task(coro: Coroutine) → Task

יצירת משימה מתוך ה-coro הנתון והחזרת אובייקט Task החדש.

run_forever() → None

הרצת לולאת האירועים עד שנקראת stop().

run_until_complete(awaitable: Awaitable) → Any

הרצת ה-awaitable הנתון עד להשלמתו. אם awaitable אינו משימה, הוא יקודם למשימה.

stop() → None

עצירת לולאת האירועים.

close() → None

סגירת לולאת האירועים.

set_exception_handler(handler: Callable) → None

הגדרת מטפל החריגות שייקרא כאשר משימה מעלה חריגה שאינה נתפסת. על ה-handler לקבל שני ארגומנטים: (loop, context).

get_exception_handler() → Callable | None

קבלת מטפל החריגות הנוכחי. מחזירה את המטפל, או None אם לא הוגדר מטפל מותאם אישית.

default_exception_handler(context: dict) → None

מטפל החריגות שבברירת מחדל נקרא.

call_exception_handler(context: dict) → None

קריאה למטפל החריגות הנוכחי. הארגומנט context מועבר כפי שהוא והוא מילון המכיל את המפתחות: 'message', 'exception', 'future'.