Propriedade de recursos em FFI com Rust: associe o construtor externo ao seu destrutor real

O que é

O Rustonomicon explica que bibliotecas externas podem transferir a propriedade de recursos para quem as chama e que os wrappers devem usar destrutores para liberar esses recursos. Ele também alerta que callbacks assíncronos precisam parar antes que o objeto Rust de destino seja destruído. Um ponteiro bruto, sozinho, não expressa o contrato completo do ciclo de vida. Rustonomicon: FFI

Por que importa

Um agente pode tomar uma chamada externa bem-sucedida como prova de que seu wrapper é seguro. Os caminhos difíceis costumam surgir depois: uma falha de inicialização, um callback concorrendo com o encerramento ou dois objetos que acreditam ser donos do mesmo handle. O método proposto consiste em escrever o ciclo de vida antes de projetar métodos convenientes.

Como aplicar

• Para cada função externa, registre se ela empresta, transfere ou devolve a propriedade. Identifique a função de liberação exata indicada na documentação e se as chamadas têm requisitos de afinidade com threads.
• Crie um único dono para cada handle adquirido. Mantenha o acesso emprestado visivelmente separado e evite adicionar comportamento de clonagem enquanto a semântica de propriedade da biblioteca externa não o justificar.
• Descreva a inicialização parcial como uma sequência de recursos adquiridos. Para cada falha possível, especifique quais recursos já existem e qual dono deve liberá-los.
• Para callbacks, defina o registro, o cancelamento do registro e o ponto a partir do qual nenhum callback permanece em execução. Mantenha vivo o estado Rust de destino até que o contrato externo garanta esse ponto.
• Proponha fixtures para criação bem-sucedida, criação com falha, operações repetidas, entrega de callback durante o encerramento e liberação normal. Observe as chamadas de liberação por meio de um shim de teste controlado, em vez de confiar apenas nos totais de memória do processo.

Armadilhas

Um destrutor não consegue criar uma garantia de quiescência dos callbacks que a API externa não oferece. Não presuma que uma alocação externa possa ser liberada com um alocador não relacionado. A afirmação pública de segurança do wrapper deve corresponder ao contrato externo e a todos os caminhos de erro. Este procedimento não estabelece a segurança de nenhuma biblioteca em particular; regras de propriedade ou de threads que continuem indefinidas exigem consultar a documentação dessa biblioteca.