From c8187cf32762070a858677e8091cca5be6a6f41c Mon Sep 17 00:00:00 2001 From: Bruno Deferrari Date: Wed, 27 Dec 2023 11:11:57 -0300 Subject: [PATCH] Add `Safety` sections to `ToOCaml` and `FromOCaml` trait docs --- src/conv/from_ocaml.rs | 17 +++++++++++++++++ src/conv/to_ocaml.rs | 16 ++++++++++++++++ 2 files changed, 33 insertions(+) diff --git a/src/conv/from_ocaml.rs b/src/conv/from_ocaml.rs index eceadff..cb64485 100644 --- a/src/conv/from_ocaml.rs +++ b/src/conv/from_ocaml.rs @@ -7,6 +7,23 @@ use crate::{ }; /// Implements conversion from OCaml values into Rust values. +/// +/// # Safety +/// +/// Implementing this trait involves unsafe code that interacts with the OCaml runtime. +/// Implementors must adhere to the following safety guidelines: +/// +/// - **Valid OCaml Values**: The OCaml value passed to the `from_ocaml` function must be valid. +/// The implementor is responsible for ensuring that the value is a correct and valid representation +/// of the type `T` in OCaml. Passing an invalid or unrelated value may lead to undefined behavior. +/// +/// - **Handling of OCaml Exceptions**: If the OCaml code can raise exceptions, the implementor +/// must ensure these are appropriately handled. Uncaught OCaml exceptions should not be allowed +/// to propagate into the Rust code, as they are not compatible with Rust's error handling mechanisms. +/// +/// Implementors of this trait need to have a thorough understanding of the OCaml runtime, especially +/// regarding value representation and memory management, to ensure safe and correct conversions +/// from OCaml to Rust. pub unsafe trait FromOCaml { /// Convert from OCaml value. fn from_ocaml(v: OCaml) -> Self; diff --git a/src/conv/to_ocaml.rs b/src/conv/to_ocaml.rs index 92d769c..cf95abd 100644 --- a/src/conv/to_ocaml.rs +++ b/src/conv/to_ocaml.rs @@ -19,6 +19,22 @@ use crate::{ }; /// Implements conversion from Rust values into OCaml values. +/// +/// # Safety +/// +/// Implementing this trait involves unsafe code that interacts with the OCaml runtime. +/// Implementors must ensure the following to uphold Rust's safety guarantees: +/// +/// - **Memory Safety**: Returned OCaml values must be valid and correctly represent +/// the memory layout expected by the OCaml runtime. Any misrepresentation can lead +/// to undefined behavior, potentially causing segmentation faults or data corruption. +/// +/// - **Handling of OCaml Exceptions**: If the OCaml code can raise exceptions, the implementor +/// must ensure these are appropriately handled. Uncaught OCaml exceptions should not be allowed +/// to propagate into the Rust code, as they are not compatible with Rust's error handling mechanisms. +/// +/// Implementors of this trait must have a deep understanding of both Rust's and OCaml's +/// memory models, garbage collection, and runtime behaviors to ensure safe interoperability. pub unsafe trait ToOCaml { /// Convert to OCaml value. Return an already rooted value as [`BoxRoot`]``. fn to_boxroot(&self, cr: &mut OCamlRuntime) -> BoxRoot {