Merge pull request #424 from godot-rust/qol/experimental-features

Feature-gate Godot experimental APIs

Author: Bromeon

.github/workflows/full-ci.yml

@@ -217,7 +217,7 @@ jobs:
             os: ubuntu-20.04
             artifact-name: linux-nightly
             godot-binary: godot.linuxbsd.editor.dev.x86_64
-            rust-extra-args: --features godot/custom-godot,godot/threads,godot/serde
+            rust-extra-args: --features godot/custom-godot,godot/experimental-threads,godot/serde
 
           # Linux compat
 

.github/workflows/minimal-ci.yml

@@ -149,7 +149,7 @@ jobs:
             os: ubuntu-20.04
             artifact-name: linux-nightly
             godot-binary: godot.linuxbsd.editor.dev.x86_64
-            rust-extra-args: --features godot/custom-godot,godot/threads,godot/serde
+            rust-extra-args: --features godot/custom-godot,godot/experimental-threads,godot/serde
 
           # Linux compat
 

godot-codegen/Cargo.toml

@@ -13,6 +13,7 @@ codegen-fmt = []
 codegen-full = []
 double-precision = []
 custom-godot = ["godot-bindings/custom-godot"]
+experimental-godot-api = []
 
 [dependencies]
 godot-bindings = { path = "../godot-bindings" }

godot-codegen/src/special_cases.rs

@@ -44,14 +44,12 @@ pub(crate) fn is_deleted(class_name: &TyName, method: &ClassMethod, ctx: &mut Co
 
 #[rustfmt::skip]
 pub(crate) fn is_class_deleted(class_name: &TyName) -> bool {
-    let class_name = class_name.godot_ty.as_str();
-
-    // TODO feature-gate experimental classes.
-    /*
+    // Exclude experimental APIs unless opted-in.
     if !cfg!(feature = "experimental-godot-api") && is_class_experimental(class_name) {
         return true;
     }
-    */
+
+    let class_name = class_name.godot_ty.as_str();
 
     // OpenXR has not been available for macOS before 4.2.
     // See e.g. https://github.com/GodotVR/godot-xr-tools/issues/479.
@@ -105,7 +103,6 @@ pub(crate) fn is_class_deleted(class_name: &TyName) -> bool {
 }
 
 #[rustfmt::skip]
-#[allow(dead_code)] // remove once used.
 fn is_class_experimental(class_name: &TyName) -> bool {
     // These classes are currently hardcoded, but the information is available in Godot's doc/classes directory.
     // The XML file contains a property <class name="NavigationMesh" ... is_experimental="true">.

godot-core/Cargo.toml

@@ -14,7 +14,8 @@ codegen-fmt = ["godot-ffi/codegen-fmt", "godot-codegen/codegen-fmt"]
 codegen-full = ["godot-codegen/codegen-full"]
 double-precision = ["godot-codegen/double-precision"]
 custom-godot = ["godot-ffi/custom-godot", "godot-codegen/custom-godot"]
-threads = []
+experimental-godot-api = ["godot-codegen/experimental-godot-api"]
+experimental-threads = []
 
 [dependencies]
 godot-ffi = { path = "../godot-ffi" }

godot-core/src/obj/guards.rs

@@ -4,32 +4,32 @@
  * file, You can obtain one at https://mozilla.org/MPL/2.0/.
  */
 
-#[cfg(not(feature = "threads"))]
+#[cfg(not(feature = "experimental-threads"))]
 use std::cell;
 use std::fmt::Debug;
 use std::ops::{Deref, DerefMut};
-#[cfg(feature = "threads")]
+#[cfg(feature = "experimental-threads")]
 use std::sync;
 
 /// Immutably/shared bound reference guard for a [`Gd`][crate::obj::Gd] smart pointer.
 ///
 /// See [`Gd::bind`][crate::obj::Gd::bind] for usage.
 #[derive(Debug)]
 pub struct GdRef<'a, T> {
-    #[cfg(not(feature = "threads"))]
+    #[cfg(not(feature = "experimental-threads"))]
     cell_ref: cell::Ref<'a, T>,
 
-    #[cfg(feature = "threads")]
+    #[cfg(feature = "experimental-threads")]
     cell_ref: sync::RwLockReadGuard<'a, T>,
 }
 
 impl<'a, T> GdRef<'a, T> {
-    #[cfg(not(feature = "threads"))]
+    #[cfg(not(feature = "experimental-threads"))]
     pub(crate) fn from_cell(cell_ref: cell::Ref<'a, T>) -> Self {
         Self { cell_ref }
     }
 
-    #[cfg(feature = "threads")]
+    #[cfg(feature = "experimental-threads")]
     pub(crate) fn from_cell(cell_ref: sync::RwLockReadGuard<'a, T>) -> Self {
         Self { cell_ref }
     }
@@ -52,20 +52,20 @@ impl<T> Deref for GdRef<'_, T> {
 /// See [`Gd::bind_mut`][crate::obj::Gd::bind_mut] for usage.
 #[derive(Debug)]
 pub struct GdMut<'a, T> {
-    #[cfg(not(feature = "threads"))]
+    #[cfg(not(feature = "experimental-threads"))]
     cell_ref: cell::RefMut<'a, T>,
 
-    #[cfg(feature = "threads")]
+    #[cfg(feature = "experimental-threads")]
     cell_ref: sync::RwLockWriteGuard<'a, T>,
 }
 
 impl<'a, T> GdMut<'a, T> {
-    #[cfg(not(feature = "threads"))]
+    #[cfg(not(feature = "experimental-threads"))]
     pub(crate) fn from_cell(cell_ref: cell::RefMut<'a, T>) -> Self {
         Self { cell_ref }
     }
 
-    #[cfg(feature = "threads")]
+    #[cfg(feature = "experimental-threads")]
     pub(crate) fn from_cell(cell_ref: sync::RwLockWriteGuard<'a, T>) -> Self {
         Self { cell_ref }
     }

godot-core/src/storage.rs

@@ -18,13 +18,13 @@ pub enum Lifecycle {
     Dead, // reading this would typically already be too late, only best-effort in case of UB
 }
 
-#[cfg(not(feature = "threads"))]
+#[cfg(not(feature = "experimental-threads"))]
 pub(crate) use single_threaded::*;
 
-#[cfg(feature = "threads")]
+#[cfg(feature = "experimental-threads")]
 pub(crate) use multi_threaded::*;
 
-#[cfg(not(feature = "threads"))]
+#[cfg(not(feature = "experimental-threads"))]
 mod single_threaded {
     use std::any::type_name;
     use std::cell;
@@ -107,7 +107,7 @@ mod single_threaded {
     }
 }
 
-#[cfg(feature = "threads")]
+#[cfg(feature = "experimental-threads")]
 mod multi_threaded {
     use std::any::type_name;
     use std::sync;
@@ -219,7 +219,7 @@ mod multi_threaded {
     // This type can be accessed concurrently from multiple threads, so it should be Sync. That implies however that T must be Sync too
     // (and possibly Send, because with `&mut` access, a `T` can be extracted as a value using mem::take() etc.).
     // Which again means that we need to infest half the codebase with T: Sync + Send bounds, *and* make it all conditional on
-    // `#[cfg(feature = "threads")]`. Until the multi-threading design is clarified, we'll thus leave it as is.
+    // `#[cfg(feature = "experimental-threads")]`. Until the multi-threading design is clarified, we'll thus leave it as is.
     //
     // The following code + __static_type_check() above would make sure that InstanceStorage is Sync.
 

godot-ffi/Cargo.toml

@@ -10,6 +10,7 @@ categories = ["game-engines", "graphics"]
 [features]
 custom-godot = ["godot-bindings/custom-godot"]
 codegen-fmt = ["godot-codegen/codegen-fmt"]
+experimental-godot-api = ["godot-codegen/experimental-godot-api"]
 trace = []
 
 [dependencies]

godot/Cargo.toml

@@ -13,7 +13,8 @@ custom-godot = ["godot-core/custom-godot"]
 double-precision = ["godot-core/double-precision"]
 formatted = ["godot-core/codegen-fmt"]
 serde = ["godot-core/serde"]
-threads = ["godot-core/threads"]
+experimental-threads = ["godot-core/experimental-threads"]
+experimental-godot-api = ["godot-core/experimental-godot-api"]
 
 # Private features, they are under no stability guarantee
 codegen-full = ["godot-core/codegen-full"]

godot/src/lib.rs

@@ -99,7 +99,7 @@
 //! As a rule of thumb, if you must use threading, prefer to use [Rust threads](https://doc.rust-lang.org/std/thread)
 //! over Godot threads.
 //!
-//! The Cargo feature `threads` provides experimental support for multithreading. The underlying safety
+//! The Cargo feature `experimental-threads` provides experimental support for multithreading. The underlying safety
 //! rules are still being worked out, as such you may encounter unsoundness and an unstable API.
 //!
 //! # Cargo features
@@ -135,11 +135,16 @@
 //!   The serialized representation underlies **no stability guarantees** and may change at any time, even without a SemVer-breaking change.
 //!   <br><br>
 //!
-//! * **`threads`**
+//! * **`experimental-threads`**
 //!
 //!   Experimental threading support. This enables `Send`/`Sync` traits for `Gd<T>` and makes the guard types `Gd`/`GdMut` aware of
-//!   multi-threaded references. The safety aspects of this are not ironed out yet; use at your own risk. The API may also change
-//!   at any time.
+//!   multi-threaded references. There safety aspects are not ironed out yet; there is a high risk of unsoundness at the moment.
+//!   As this evolves, it is very likely that the API becomes more strict.
+//!
+//! * **`experimental-godot-api`**
+//!
+//!   Access to `godot::engine` APIs that Godot marks "experimental". These are under heavy development and may change at any time.
+//!   If you opt in to this feature, expect breaking changes at compile and runtime.
 //!
 //! # Public API
 //!