12.7. Channel callbacks¶

Het backend-object dat aan protocol.register() wordt doorgegeven, is een Python-klasse. De protocolbibliotheek vraagt de klasse niet welke methoden ze implementeert; ze inspecteert de instantie en koppelt de methoden die ze aantreft. Die introspectie is wat de backend-interface flexibel maakt: de kleinste bruikbare backend bestaat uit twee methoden, de meest uitgebreide uit twaalf, en de applicatie kiest per methode één voor één voor elke mogelijkheid.

12.7.1. De introspectieregels¶

Wanneer protocol.register() wordt uitgevoerd, loopt de bibliotheek een vaste lijst met aanroepbare namen af en bindt elke naam die ze op de backend-instantie aantreft:

Het toevoegen van read aan de klasse zet CHANNEL_FLAG_READ aan. Een host-aanroep van channel_read() bereikt de backend alleen als deze vlag is ingesteld.
Het toevoegen van write zet CHANNEL_FLAG_WRITE aan en maakt channel_write() mogelijk.
Het toevoegen van lock en unlock zet CHANNEL_FLAG_LOCK aan, waardoor de host het channel kan vergrendelen voor een atomaire lees-actie over meerdere pakketten.
Het toevoegen van poll laat de host goedkoop vragen “is er iets klaar?”, zonder een volledige lees-actie af te dwingen.

Ontbrekende methoden zijn geen fouten – de protocolbibliotheek laat de bijbehorende mogelijkheid simpelweg uitgeschakeld. Een backend met alleen size en read is volkomen geldig; het is een alleen-lezen datachannel.

12.7.2. Een alleen-lezen sensor-channel¶

Een sensor-channel dat elke keer dat de host erom vraagt een verse meting publiceert en host-schrijfacties weigert, gebruikt vier van de callbacks:

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))

Wat elke methode doet, stap voor stap:

poll retourneert de versheidsvlag. De host roept deze aan vóór het lezen en slaat de lees-actie helemaal over wanneer ze False retourneert. Dat bespaart de heen-en-weerkosten voor “nog geen nieuwe data.”
size genereert de buffer op verzoek opnieuw en rapporteert de lengte ervan. Door hier de bemonstering te doen, heeft de backend geen achtergrondtaak nodig – elke host-aanroep stuurt elke meting aan.
read retourneert een deel van de buffer. De protocolbibliotheek kan deze meer dan eens aanroepen wanneer de buffer groter is dan de onderhandelde maximale payload; het argument offset loopt door de fragmenten heen.
Geen write betekent dat host-schrijfacties worden geweigerd in de framinglaag, voordat de backend erbij betrokken wordt.

12.7.3. De volledige set callbacks¶

Ter referentie, elke methode waar de bibliotheek naar zoekt op een backend:

Methode	Retourneert	Doel
`init(self)`	object	Optionele eenmalige initialisatie wanneer het channel voor het eerst aan een host wordt gebonden. Retourneer bij succes een willekeurige waarde die niet `None` is.
`poll(self)`	bool	Retourneer `True` wanneer er data beschikbaar is.
`lock(self)`	bool	Reserveer het channel voor een atomaire overdracht over meerdere pakketten.
`unlock(self)`	bool	Geef een eerdere `lock` vrij.
`size(self)`	int	Aantal bytes dat momenteel uit het channel kan worden gelezen.
`shape(self)`	tuple	Tot vier gehele getallen die de datastructuur beschrijven (bijv. hoogte van de afbeelding, breedte, aantal bytes). Wordt door de host gebruikt om getypeerde buffers uit te pakken.
`read(self, offset, size)`	bytes	Retourneer tot size bytes vanaf offset. Wordt eenmaal per fragment aangeroepen wanneer de payload de onderhandelde maximumwaarde overschrijdt.
`readp(self, offset, size)`	bytes	Zero-copy-variant van `read`: het geheugen van de buffer moet geldig blijven voor de duur van de overdracht.
`write(self, offset, data)`	int	De host heeft data geschreven op offset. `data` is een `bytearray`-view in de ontvangstbuffer van de protocollaag – kopieer wat je wilt bewaren naar buiten voordat je terugkeert.
`ioctl(self, cmd, length, arg)`	int	Door de applicatie gedefinieerde opcode buiten het lees-/schrijfmodel. Een negatieve retourwaarde is een fout.
`flush(self)`	object	Verwijder alle gebufferde data. Wordt aangeroepen wanneer de host het channel wil resetten.
`is_active(self)`	bool	Alleen zinvol op backends die een fysiek transport vertegenwoordigen (de ingebouwde USB-channels). Applicatie-channels hebben dit niet nodig.

Dat is de volledige backend-interface. Twaalf methodenamen, allemaal optioneel, en de protocolbibliotheek bepaalt op basis van welke aanwezig zijn wat elk channel kan doen.