12.7. Callback dei canali¶

L’oggetto backend passato a protocol.register() è una classe Python. La libreria del protocollo non chiede alla classe quali metodi implementa; ispeziona l’istanza e collega quelli che trova. Questa introspezione è ciò che rende flessibile l’interfaccia del backend: il backend utile più piccolo ha due metodi, quello più elaborato ne ha dodici, e l’applicazione aderisce a ciascuna funzionalità un metodo alla volta.

12.7.1. Le regole di introspezione¶

Quando protocol.register() viene eseguito, la libreria scorre un elenco fisso di nomi richiamabili e collega ciascuno di quelli che trova nell’istanza del backend:

Aggiungere read alla classe attiva CHANNEL_FLAG_READ. Una chiamata dell’host a channel_read() raggiunge il backend solo se questo flag è impostato.
Aggiungere write attiva CHANNEL_FLAG_WRITE, abilitando channel_write().
Aggiungere lock e unlock attiva CHANNEL_FLAG_LOCK, consentendo all’host di bloccare il canale per una lettura atomica multi-pacchetto.
Aggiungere poll consente all’host di chiedere «c’è qualcosa di pronto?» a basso costo, senza forzare una lettura completa.

I metodi mancanti non sono errori: la libreria del protocollo lascia semplicemente disabilitata la funzionalità corrispondente. Un backend con solo size e read è perfettamente valido; è un canale dati di sola lettura.

12.7.2. Un canale sensore di sola lettura¶

Un canale sensore che pubblica una lettura aggiornata ogni volta che l’host la richiede, rifiutando le scritture dell’host, utilizza quattro dei 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))

Esaminiamo cosa fa ciascun metodo:

poll restituisce il flag di freschezza. L’host lo chiama prima di leggere e salta del tutto la lettura quando restituisce False. Questo evita il costo del round-trip per «nessun dato nuovo ancora».
size rigenera il buffer su richiesta e ne riporta la lunghezza. Eseguire qui il campionamento significa che il backend non ha bisogno di un task in background: ogni chiamata dell’host guida ogni misurazione.
read restituisce una porzione del buffer. La libreria del protocollo può chiamarlo più di una volta quando il buffer è più grande del payload massimo negoziato; l’argomento offset scorre i frammenti.
L’assenza di write significa che le scritture dell’host vengono rifiutate a livello di framing, prima che il backend sia coinvolto.

12.7.3. L’insieme completo dei callback¶

Per riferimento, ogni metodo che la libreria cerca su un backend:

Metodo	Restituisce	Scopo
`init(self)`	object	Inizializzazione opzionale una tantum quando il canale si collega per la prima volta a un host. Restituisce qualsiasi valore non `None` in caso di successo.
`poll(self)`	bool	Restituisce `True` quando i dati sono disponibili.
`lock(self)`	bool	Acquisisce il canale per un trasferimento atomico multi-pacchetto.
`unlock(self)`	bool	Rilascia un `lock` precedente.
`size(self)`	int	Numero di byte attualmente leggibili dal canale.
`shape(self)`	tuple	Fino a quattro interi che descrivono la struttura dei dati (ad es. altezza, larghezza, numero di byte dell’immagine). Usato dall’host per spacchettare buffer tipizzati.
`read(self, offset, size)`	bytes	Restituisce fino a size byte a partire da offset. Chiamato una volta per frammento quando il payload supera il massimo negoziato.
`readp(self, offset, size)`	bytes	Variante zero-copy di `read`: la memoria del buffer deve rimanere valida per tutta la durata del trasferimento.
`write(self, offset, data)`	int	L’host ha scritto data a offset. `data` è una vista `bytearray` nel buffer di ricezione del livello del protocollo: copia ciò che vuoi conservare prima di restituire il controllo.
`ioctl(self, cmd, length, arg)`	int	Opcode definito dall’applicazione al di fuori del modello read/write. Un valore di ritorno negativo è un errore.
`flush(self)`	object	Scarta qualsiasi dato bufferizzato. Chiamato quando l’host vuole reimpostare il canale.
`is_active(self)`	bool	Significativo solo sui backend che rappresentano un trasporto fisico (i canali USB integrati). I canali applicativi non ne hanno bisogno.

Questa è l’intera interfaccia del backend. Dodici nomi di metodi, tutti opzionali, e la libreria del protocollo decide cosa può fare ciascun canale in base a quali sono presenti.