12.7. פונקציות callback של ערוצים¶

אובייקט ה-backend המועבר אל protocol.register() הוא מחלקת Python. ספריית הפרוטוקול אינה שואלת את המחלקה אילו מתודות היא ממשת; היא בוחנת את המופע ומחברת את אלו שהיא מוצאת. אינטרוספקציה זו היא מה שמקנה לממשק ה-backend את גמישותו: ה-backend השימושי הקטן ביותר מורכב משתי מתודות, המורכב ביותר משתים-עשרה, והאפליקציה מצטרפת לכל יכולת בנפרד, מתודה אחת בכל פעם.

12.7.1. כללי האינטרוספקציה¶

כאשר protocol.register() רץ, הספרייה עוברת על רשימה קבועה של שמות הניתנים לקריאה ומקשרת כל אחד שהיא מוצאת על מופע ה-backend:

הוספת read למחלקה מדליקה את CHANNEL_FLAG_READ. קריאה מהמארח אל channel_read() מגיעה אל ה-backend רק אם דגל זה מוגדר.
הוספת write מדליקה את CHANNEL_FLAG_WRITE, ומאפשרת את channel_write().
הוספת lock ו-unlock מדליקה את CHANNEL_FLAG_LOCK, ומאפשרת למארח לנעול את הערוץ לצורך קריאה אטומית מרובת מנות (packets).
הוספת poll מאפשרת למארח לשאול ”האם משהו מוכן?“ בזול, בלי לכפות קריאה מלאה.

מתודות חסרות אינן שגיאות – ספריית הפרוטוקול פשוט משאירה את היכולת המתאימה מושבתת. backend עם size ו-read בלבד הוא תקין לחלוטין; זהו ערוץ נתונים לקריאה בלבד.

12.7.2. ערוץ חיישן לקריאה בלבד¶

ערוץ חיישן המפרסם קריאה טרייה בכל פעם שהמארח מבקש, ומסרב לכתיבות מהמארח, עושה שימוש בארבע מפונקציות ה-callback:

import protocol
import struct

class TempChannel:
    def __init__(self, read_sensor):
        self._read_sensor = read_sensor
        self._buf = b''
        self._fresh = False

    def poll(self):
        # Tell the host whether a reading is waiting.
        return self._fresh

    def size(self):
        # Sample fresh data on every host-side size query.
        value = self._read_sensor()
        self._buf = struct.pack('<f', value)
        self._fresh = True
        return len(self._buf)

    def read(self, offset, size):
        end = offset + size
        if end >= len(self._buf):
            self._fresh = False
        return self._buf[offset:end]

protocol.register(name='temp', backend=TempChannel(read_temperature))

מעבר על מה שכל מתודה עושה:

poll מחזירה את דגל הטריות. המארח קורא לה לפני קריאה ומדלג על הקריאה לחלוטין כאשר היא מחזירה False. זה חוסך את עלות ההלוך-ושוב במקרה של ”אין נתונים חדשים עדיין“.
size מייצרת מחדש את החוצץ (buffer) לפי דרישה ומדווחת על אורכו. ביצוע הדגימה כאן משמעו שה-backend אינו זקוק למשימת רקע – קריאה מהמארח מניעה כל מדידה.
read מחזירה פלח של החוצץ (buffer). ספריית הפרוטוקול עשויה לקרוא לה יותר מפעם אחת כאשר החוצץ גדול מהמטען המרבי שסוכם; הארגומנט offset עובר דרך הקטעים.
היעדר write משמעו שכתיבות מהמארח נדחות בשכבת המסגור (framing), לפני שה-backend מעורב.

12.7.3. ערכת ה-callback המלאה¶

לעיון, כל מתודה שהספרייה מחפשת על backend:

מתודה	מחזירה	מטרה
`init(self)`	object	אתחול חד-פעמי אופציונלי כאשר הערוץ נקשר לראשונה למארח. החזר כל ערך שאינו `None` בעת הצלחה.
`poll(self)`	bool	החזר `True` כאשר נתונים זמינים.
`lock(self)`	bool	תפוס את הערוץ לצורך העברה אטומית מרובת מנות (packets).
`unlock(self)`	bool	שחרר `lock` קודם.
`size(self)`	int	מספר הבייטים הניתנים כעת לקריאה מהערוץ.
`shape(self)`	tuple	עד ארבעה מספרים שלמים המתארים את מבנה הנתונים (למשל גובה התמונה, רוחב, מספר בייטים). משמש את המארח כדי לפרוס חוצצים מטופסים.
`read(self, offset, size)`	bytes	החזר עד size בייטים החל מ-offset. נקרא פעם אחת לכל קטע כאשר המטען חורג מהמרבי שסוכם.
`readp(self, offset, size)`	bytes	וריאנט ללא העתקה (zero-copy) של `read`: זיכרון החוצץ חייב להישאר תקף למשך כל ההעברה.
`write(self, offset, data)`	int	המארח כתב data ב-offset. `data` הוא תצוגת `bytearray` לתוך חוצץ הקבלה של שכבת הפרוטוקול – העתק החוצה את מה שברצונך לשמור לפני החזרה.
`ioctl(self, cmd, length, arg)`	int	אופקוד מוגדר-אפליקציה מחוץ למודל הקריאה/כתיבה. ערך החזרה שלילי הוא שגיאה.
`flush(self)`	object	השלך כל נתון מאוחסן בחוצץ. נקרא כאשר המארח רוצה לאפס את הערוץ.
`is_active(self)`	bool	משמעותי רק על backends המייצגים תעבורה (transport) פיזית (ערוצי ה-USB המובנים). ערוצי אפליקציה אינם זקוקים לכך.

זהו ממשק ה-backend בשלמותו. שנים-עשר שמות מתודות, כולם אופציונליים, וספריית הפרוטוקול מחליטה מה כל ערוץ יכול לעשות על סמך אילו מהם נוכחים.