12.7. Зворотні виклики каналу#

Об’єкт бекенду, переданий до protocol.register(), є класом Python. Бібліотека протоколу не запитує клас про те, які методи він реалізує; вона перевіряє екземпляр і підключає ті, які знаходить. Саме ця інтроспекція робить інтерфейс бекенду гнучким: найменший корисний бекенд складається з двох методів, найбільш розгорнутий – з дванадцяти, а застосунок підключається до кожної можливості по одному методу за раз.

12.7.1. Правила інтроспекції#

Коли protocol.register() виконується, бібліотека проходить фіксований список викликуваних імен і прив’язує кожне, яке знаходить на екземплярі бекенду:

Додавання read до класу вмикає CHANNEL_FLAG_READ. Виклик хоста до channel_read() досягає бекенду лише якщо цей прапор встановлено.
Додавання write вмикає CHANNEL_FLAG_WRITE, дозволяючи channel_write().
Додавання lock та unlock вмикає CHANNEL_FLAG_LOCK, дозволяючи хосту заблокувати канал для атомарного зчитування з кількох пакетів.
Додавання poll дозволяє хосту дешево запитати «чи є щось готове?», без необхідності виконувати повне зчитування.

Відсутні методи не є помилками – бібліотека протоколу просто залишає відповідну можливість вимкненою. Бекенд лише з size та read є цілком допустимим; це канал даних лише для читання.

12.7.2. Канал датчика лише для читання#

Канал датчика, який публікує нові показники кожного разу, коли хост запитує, відхиляючи запити на запис від хоста, задіює чотири зворотні виклики:

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 регенерує буфер на вимогу і повідомляє його довжину. Виконання вимірювання тут означає, що бекенду не потрібне фонове завдання – кожен виклик хоста ініціює нове вимірювання.
read повертає зріз буфера. Бібліотека протоколу може викликати його кілька разів, якщо буфер більший за узгоджений максимальний розмір корисного навантаження; аргумент offset проходить по фрагментах.
Відсутність write означає, що запис від хоста відхиляється на рівні кадрування, до залучення бекенду.

12.7.3. Повний набір зворотних викликів#

Для довідки – кожен метод, який бібліотека шукає на бекенді:

Метод	Повертає	Призначення
`init(self)`	object	Необов’язкова одноразова ініціалізація, коли канал вперше прив’язується до хоста. Поверніть будь-яке значення, відмінне від `None`, у разі успіху.
`poll(self)`	bool	Повертає `True`, коли дані доступні.
`lock(self)`	bool	Захоплює канал для атомарного багатопакетного передавання.
`unlock(self)`	bool	Звільняє попередньо встановлений `lock`.
`size(self)`	int	Кількість байтів, доступних для зчитування з каналу на поточний момент.
`shape(self)`	tuple	До чотирьох цілих чисел, що описують структуру даних (наприклад, висота зображення, ширина, кількість байтів). Використовується хостом для розпакування типізованих буферів.
`read(self, offset, size)`	bytes	Повертає до size байтів починаючи з offset. Викликається по одному разу на фрагмент, коли корисне навантаження перевищує узгоджений максимум.
`readp(self, offset, size)`	bytes	Варіант `read` без копіювання: пам’ять буфера повинна залишатися дійсною протягом усього передавання.
`write(self, offset, data)`	int	Хост записав data за адресою offset. `data` – це представлення `bytearray` у буфері прийому рівня протоколу – скопіюйте те, що хочете зберегти, до повернення.
`ioctl(self, cmd, length, arg)`	int	Код операції, визначений застосунком, поза моделлю читання/запису. Від’ємне повернене значення є помилкою.
`flush(self)`	object	Скидає всі буферизовані дані. Викликається, коли хост хоче скинути канал.
`is_active(self)`	bool	Має значення лише для бекендів, що представляють фізичний транспорт (вбудовані USB-канали). Канали застосунку у цьому не потребують.

Це повний інтерфейс бекенду. Дванадцять імен методів, усі необов’язкові, і бібліотека протоколу вирішує, що може робити кожен канал, на основі присутніх методів.