Владение ресурсами в Rust FFI: сопоставьте внешний конструктор с соответствующим ему деструктором

Что это такое

Rustonomicon объясняет, что внешние библиотеки могут передавать владение ресурсами вызывающей стороне и что обёрткам следует освобождать эти ресурсы с помощью деструкторов. Он также предупреждает, что асинхронные обратные вызовы должны прекратиться до уничтожения объекта Rust, к которому они обращаются. Один сырой указатель не кодирует полный контракт жизненного цикла. Rustonomicon: FFI

Почему это важно

Агент может счесть успешный внешний вызов доказательством безопасности своей обёртки. Сложные пути часто начинаются позже: сбой инициализации, обратный вызов, конкурирующий с завершением работы, или два объекта, считающих себя владельцами одного дескриптора. Предлагаемый метод описывает жизненный цикл до проектирования удобных методов.

Как применять

• Для каждой внешней функции запишите, заимствует ли она ресурс, передаёт ли владение им или возвращает владение. Определите точную документированную функцию освобождения и наличие требований к привязке вызовов к потоку.
• Создайте одного владельца для полученного дескриптора. Явно отделяйте заимствованный доступ и не добавляйте клонирование без обоснования в семантике владения внешней библиотеки.
• Опишите частичную инициализацию как последовательность полученных ресурсов. Для каждого возможного сбоя укажите, какие ресурсы уже существуют и какой владелец обязан их освободить.
• Для обратных вызовов определите регистрацию, отмену регистрации и момент, когда не остаётся ни одного выполняющегося обратного вызова. Поддерживайте существование целевого состояния Rust до тех пор, пока внешний контракт не гарантирует, что этот момент наступил.
• Предложите тестовые примеры для успешного и неудачного создания, повторных операций, доставки обратного вызова при завершении работы и обычного освобождения. Наблюдайте вызовы освобождения через контролируемую тестовую прослойку, а не полагайтесь только на суммарный объём памяти процесса.

Подводные камни

Деструктор не может создать гарантию отсутствия выполняющихся обратных вызовов, которой не предоставляет внешний API. Не предполагайте, что внешнее выделение памяти можно освободить посторонним аллокатором. Публичное утверждение о безопасности обёртки должно соответствовать внешнему контракту и всем путям ошибок. Эта процедура не устанавливает безопасность какой-либо конкретной библиотеки; невыясненные правила владения или работы с потоками требуют обращения к документации этой библиотеки.