We arrange for (non-Rust) callers of our function to uphold the safety guarantees by asking them to uphold a few properties:
We only hand out pointers to our structs that follow the rules above (aligned, initialized, etc).
We document the lifetime requirements of those pointers.
We provide *const pointers for things that may have aliases.
We expect callers to never cast between types or cast away const.
We provide *mut pointers for things that may be mutated. This is actually an area we should tighten up. The rules for what you can do with a *mut pointer are very slightly looser than the rules for what you can do with an &mut reference. For instance, the rules are triggered on dereference of raw pointers, while the rules are triggered on mere existence for references. But because we almost always have to convert a *mut pointer to an &mut reference to call methods, we have to ask our callers to uphold the more stringent &mut rules.
I believe it's okay for a *mut pointer to coexist with an &mut reference. It's just that an &mut reference can't coexist with an &mut reference. So it's possible our documented lifetime requirements are already fine.
(Copied from https://github.com/rustls/rustls-ffi/pull/291#issuecomment-1481711750)
We arrange for (non-Rust) callers of our function to uphold the safety guarantees by asking them to uphold a few properties:
*constpointers for things that may have aliases.*mutpointers for things that may be mutated. This is actually an area we should tighten up. The rules for what you can do with a*mutpointer are very slightly looser than the rules for what you can do with an&mutreference. For instance, the rules are triggered on dereference of raw pointers, while the rules are triggered on mere existence for references. But because we almost always have to convert a*mutpointer to an&mutreference to call methods, we have to ask our callers to uphold the more stringent&mutrules.https://doc.rust-lang.org/nomicon/aliasing.html
I believe it's okay for a
*mutpointer to coexist with an&mutreference. It's just that an&mutreference can't coexist with an&mutreference. So it's possible our documented lifetime requirements are already fine.