Squashed 'third_party/autocxx/' changes from 629e8fa53..c35090b75
c35090b75 Merge pull request #1131 from google/rev-0.22.3
94f20d716 Revise to 0.22.3.
b4776fdd5 Merge pull request #1070 from google/reference-wrapper
25f08f567 Better encapsulate TypeConversionPolicy. No functional changes.
b389afdeb Add reference wrapper safety policy.
cd169853b Merge pull request #1126 from google/issue-1125
92f48fa30 Merge pull request #1123 from google/segfault-detection
ca60bacca Add comment
724a4971d Add test for issue 1125.
d8a9a8ca7 Detect segfaults in reduction
e147efc7c Merge pull request #1122 from google/rev-0.22.2
dfa9b99a4 Revise to 0.22.2.
4cb1da848 Merge pull request #1120 from chbaker0/main
79afb97d9 Replace lingering tempdir usages with tempfile
f945331a3 Merge pull request #1118 from google/fix-test-fixed-num
5a8b28751 Merge pull request #1117 from google/docs-tweaks
b5486faa1 Merge pull request #1109 from bsilver8192/bindgen-skip-rustfmt
f62c17273 Fix faulty test_fixed_num test.
ad954fa72 Minor doc updates.
eaa1f8737 Leave bindgen enabled when logging is
bdff5db56 Merge pull request #1110 from bsilver8192/subclass-std
922f98be4 Merge pull request #1111 from bsilver8192/subclass-unsafe
bfbcc6b94 Merge pull request #1114 from google/rev-0.22.1
4f68a2e59 Merge pull request #1112 from bsilver8192/subclass-upcast-uniqueptr
993c5705b Revise to 0.22.1.
7bf667bbf Add a function to upcast UniquePtr
733d751a2 Fix clippy and docs
8023cee43 Fix and test subclass without `safety!(unsafe)`
4ae4d47e4 Fix and test subclasses with C++ std in scope
c50b1ee7e Tell bindgen to skip rustfmt
f9b24b90e Merge pull request #1107 from google/reject-anon-namespace-typedefs
070c9755d Merge pull request #1093 from google/always-output-rs
8eb71c5e7 Merge pull request #1095 from google/issue-1094
c86f1ce7e Reject forward declared nested types.
c118dba64 Merge branch 'main' into reject-anon-namespace-typedefs
243079997 Merge pull request #1108 from google/reject-type-param-typedefs
f803c3ba5 Reject type params - fixes #1098
f3381ba52 Reject typedefs to anon namespaces.
669d932a7 Merge pull request #1106 from google/lotsa-failing-tests
f0e8487fe Marking tests as ignored.
524c2bbfc Add tests for multiple issues.
67e16ac2a Merge branch 'main' of github.com:google/autocxx into always-output-rs
5f62daf3f Merge pull request #1104 from google/roll-cxx
43ee55ca2 Further upgrade from 1.0.67 to 1.0.68
e29e3c899 Merge pull request #1100 from bsilver8192/extern_cpp_type-namespace
d2c8edef4 Merge pull request #1101 from google/fix-1081
094dbd957 Roll cxx minimal version.
94c39f35b Merge pull request #1102 from google/fix-book-build
8764f1218 Alter mdbook-mermaid installation.
85543656f Test for issue 1081
b170df056 Fix and test extern_cpp_type with type in a C++ namespace
e4b56dd49 Fix gen tests.
5457e615d Fix #1092.
git-subtree-dir: third_party/autocxx
git-subtree-split: c35090b754619531b4eebdf4d8b583db72349943
Signed-off-by: Brian Silverman <bsilver16384@gmail.com>
Change-Id: Ia34285bc1c30f7e3c71fa9e7b677a58902648843
diff --git a/src/lib.rs b/src/lib.rs
index 6592011..4b9f26b 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -14,10 +14,13 @@
// do anything - all the magic is handled entirely by
// autocxx_macro::include_cpp_impl.
+mod reference_wrapper;
mod rvalue_param;
pub mod subclass;
mod value_param;
+pub use reference_wrapper::{CppMutRef, CppPin, CppRef};
+
#[cfg_attr(doc, aquamarine::aquamarine)]
/// Include some C++ headers in your Rust project.
///
@@ -257,6 +260,14 @@
///
/// Generated C++ APIs which use raw pointers remain `unsafe`
/// no matter what policy you choose.
+///
+/// There's an additional possible experimental safety
+/// policy available here:
+/// `safety!(unsafe_references_wrapped)`
+/// This policy treats C++ references as scary and requires
+/// them to be wrapped in a `CppRef` type. This `CppRef`
+/// type is implemented within the generated bindings but
+/// follows the contract of [`CppRef`].
#[macro_export]
macro_rules! safety {
($($tt:tt)*) => { $crate::usage!{$($tt)*} };
@@ -613,6 +624,9 @@
pub use crate::c_void;
pub use crate::cpp_semantics;
pub use crate::include_cpp;
+ pub use crate::CppMutRef;
+ pub use crate::CppPin;
+ pub use crate::CppRef;
pub use crate::PinMut;
pub use crate::RValueParam;
pub use crate::ValueParam;
diff --git a/src/reference_wrapper.rs b/src/reference_wrapper.rs
new file mode 100644
index 0000000..ed943d3
--- /dev/null
+++ b/src/reference_wrapper.rs
@@ -0,0 +1,109 @@
+// Copyright 2022 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
+// https://www.apache.org/licenses/LICENSE-2.0> or the MIT license
+// <LICENSE-MIT or https://opensource.org/licenses/MIT>, at your
+// option. This file may not be copied, modified, or distributed
+// except according to those terms.
+
+/// A C++ const reference. These are different from Rust's `&T` in that
+/// these may exist even while the object is mutated elsewhere.
+///
+/// This is a trait not a struct due to the nuances of Rust's orphan rule
+/// - implemntations of this trait are found in each set of generated bindings
+/// but they are essentially the same.
+pub trait CppRef<'a, T> {
+ /// Retrieve the underlying C++ pointer.
+ fn as_ptr(&self) -> *const T;
+
+ /// Get a regular Rust reference out of this C++ reference.
+ ///
+ /// # Safety
+ ///
+ /// Callers must guarantee that the referent is not modified by any other
+ /// C++ or Rust code while the returned reference exists. Callers must
+ /// also guarantee that no mutable Rust reference is created to the
+ /// referent while the returned reference exists.
+ unsafe fn as_ref(&self) -> &T {
+ &*self.as_ptr()
+ }
+}
+
+/// A C++ non-const reference. These are different from Rust's `&mut T` in that
+/// several C++ references can exist to the same underlying data ("aliasing")
+/// and that's not permitted in Rust.
+///
+/// This is a trait not a struct due to the nuances of Rust's orphan rule
+/// - implemntations of this trait are found in each set of generated bindings
+/// but they are essentially the same.
+pub trait CppMutRef<'a, T>: CppRef<'a, T> {
+ /// Retrieve the underlying C++ pointer.
+ fn as_mut_ptr(&self) -> *mut T;
+
+ /// Get a regular Rust mutable reference out of this C++ reference.
+ ///
+ /// # Safety
+ ///
+ /// Callers must guarantee that the referent is not modified by any other
+ /// C++ or Rust code while the returned reference exists. Callers must
+ /// also guarantee that no other Rust reference is created to the referent
+ /// while the returned reference exists.
+ unsafe fn as_mut(&mut self) -> &mut T {
+ &mut *self.as_mut_ptr()
+ }
+}
+
+/// Any newtype wrapper which causes the contained object to obey C++ reference
+/// semantics rather than Rust reference semantics.
+///
+/// The complex generics here are working around the orphan rule - the only
+/// important generic is `T` which is the underlying stored type.
+///
+/// C++ references are permitted to alias one another, and commonly do.
+/// Rust references must alias according only to the narrow rules of the
+/// borrow checker.
+///
+/// If you need C++ to access your Rust object, first imprison it in one of these
+/// objects, then use [`Self::as_cpp_ref`] to obtain C++ references to it.
+pub trait CppPin<'a, T: 'a> {
+ /// The type of C++ reference created to the contained object.
+ type CppRef: CppRef<'a, T>;
+
+ /// The type of C++ mutable reference created to the contained object..
+ type CppMutRef: CppMutRef<'a, T>;
+
+ /// Get an immutable pointer to the underlying object.
+ fn as_ptr(&self) -> *const T;
+
+ /// Get a mutable pointer to the underlying object.
+ fn as_mut_ptr(&mut self) -> *mut T;
+
+ /// Returns a reference which obeys C++ reference semantics
+ fn as_cpp_ref(&self) -> Self::CppRef;
+
+ /// Returns a mutable reference which obeys C++ reference semantics.
+ ///
+ /// Note that this requires unique ownership of `self`, but this is
+ /// advisory since the resulting reference can be cloned.
+ fn as_cpp_mut_ref(&mut self) -> Self::CppMutRef;
+
+ /// Get a normal Rust reference to the underlying object. This is unsafe.
+ ///
+ /// # Safety
+ ///
+ /// You must guarantee that C++ will not mutate the object while the
+ /// reference exists.
+ unsafe fn as_ref(&self) -> &T {
+ &*self.as_ptr()
+ }
+
+ /// Get a normal Rust mutable reference to the underlying object. This is unsafe.
+ ///
+ /// # Safety
+ ///
+ /// You must guarantee that C++ will not mutate the object while the
+ /// reference exists.
+ unsafe fn as_mut(&mut self) -> &mut T {
+ &mut *self.as_mut_ptr()
+ }
+}
diff --git a/src/subclass.rs b/src/subclass.rs
index d2827ca..6c6ee31 100644
--- a/src/subclass.rs
+++ b/src/subclass.rs
@@ -207,8 +207,9 @@
/// * You _may_ need to implement [`CppPeerConstructor`] for your subclass,
/// but only if autocxx determines that there are multiple possible superclass
/// constructors so you need to call one explicitly (or if there's a single
-/// non-trivial superclass constructor.) autocxx will implemente this trait
-/// for you if there's no ambiguity.
+/// non-trivial superclass constructor.) autocxx will implement this trait
+/// for you if there's no ambiguity and FFI functions are safe to call due to
+/// `autocxx::safety!` being used.
///
/// # How to access your Rust structure from outside
///