12.7. Callbacky kanálu#

Backend objekt předaný funkci protocol.register() je třída v Pythonu. Knihovna protokolu se třídy neptá, které metody implementuje; prozkoumá instanci a propojí ty, které najde. Právě tato introspekce činí rozhraní backendu flexibilním: nejmenší užitečný backend má dvě metody, ten nejpropracovanější dvanáct, a aplikace si jednotlivé schopnosti zapíná metodu po metodě.

12.7.1. Pravidla introspekce#

Když se spustí protocol.register(), knihovna projde pevný seznam názvů volatelných metod a každou z nich, kterou na instanci backendu najde, naváže:

Přidání metody read do třídy zapne příznak CHANNEL_FLAG_READ. Volání channel_read() ze strany hostitele dosáhne backendu pouze tehdy, je-li tento příznak nastaven.
Přidání metody write zapne příznak CHANNEL_FLAG_WRITE a umožní tak channel_write().
Přidání metod lock a unlock zapne příznak CHANNEL_FLAG_LOCK a umožní hostiteli uzamknout kanál pro atomické čtení napříč více pakety.
Přidání metody poll umožní hostiteli levně se zeptat „je něco připraveno?“ bez nutnosti vynucovat plné čtení.

Chybějící metody nejsou chyby – knihovna protokolu jednoduše ponechá odpovídající schopnost vypnutou. Backend pouze s metodami size a read je naprosto platný; jde o datový kanál určený jen ke čtení.

12.7.2. Senzorový kanál určený jen ke čtení#

Senzorový kanál, který při každém dotazu hostitele publikuje čerstvé měření a odmítá zápisy ze strany hostitele, využívá čtyři z 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))

Projděme si, co každá metoda dělá:

poll vrací příznak čerstvosti dat. Hostitel ji volá před čtením a čtení zcela přeskočí, když vrátí False. To šetří náklady na obousměrný přenos při „zatím žádná nová data“.
size na vyžádání znovu vygeneruje buffer a oznámí jeho délku. Provádění odběru vzorků právě zde znamená, že backend nepotřebuje úlohu běžící na pozadí – každé měření řídí volání hostitele.
read vrací výřez bufferu. Knihovna protokolu ji může zavolat vícekrát, pokud je buffer větší než vyjednaná maximální užitečná zátěž; argument offset prochází jednotlivými fragmenty.
Absence metody write znamená, že zápisy ze strany hostitele jsou odmítnuty již na úrovni rámcování, dříve než se zapojí backend.

12.7.3. Kompletní sada callbacků#

Pro referenci uvádíme každou metodu, kterou knihovna na backendu hledá:

Metoda	Vrací	Účel
`init(self)`	object	Volitelná jednorázová inicializace, když se kanál poprvé naváže na hostitele. Při úspěchu vraťte libovolnou hodnotu různou od `None`.
`poll(self)`	bool	Vrací `True`, když jsou data k dispozici.
`lock(self)`	bool	Získá kanál pro atomický přenos napříč více pakety.
`unlock(self)`	bool	Uvolní předchozí `lock`.
`size(self)`	int	Počet bajtů aktuálně čitelných z kanálu.
`shape(self)`	tuple	Až čtyři celá čísla popisující datovou strukturu (např. výšku obrazu, šířku, počet bajtů). Hostitel je používá k rozbalení typovaných bufferů.
`read(self, offset, size)`	bytes	Vrací až size bajtů počínaje pozicí offset. Voláno jednou na fragment, když užitečná zátěž překračuje vyjednané maximum.
`readp(self, offset, size)`	bytes	Varianta metody `read` bez kopírování (zero-copy): paměť bufferu musí zůstat platná po celou dobu přenosu.
`write(self, offset, data)`	int	Hostitel zapsal data na pozici offset. `data` je pohled typu `bytearray` do přijímacího bufferu vrstvy protokolu – před návratem zkopírujte ven to, co si chcete ponechat.
`ioctl(self, cmd, length, arg)`	int	Aplikací definovaný operační kód mimo model čtení/zápisu. Záporná návratová hodnota značí chybu.
`flush(self)`	object	Zahodí veškerá data uložená v bufferu. Voláno, když chce hostitel kanál resetovat.
`is_active(self)`	bool	Smysluplné pouze na backendech, které představují fyzický přenosový kanál (vestavěné USB kanály). Aplikační kanály toto nepotřebují.

To je celé rozhraní backendu. Dvanáct názvů metod, všechny volitelné, a knihovna protokolu na základě toho, které z nich jsou přítomny, rozhodne, co může každý kanál dělat.