Changed return_ref syntax to returns(as_ref) and returns(cloned) (#772)

* Changed `return_ref` syntax to `returns(as_ref)` and `returns(cloned)`

* Implement

* renamed module for return_mode

* Rename macro, fix docs, add tests, validate return modes

* Cargo fmt

---------

Co-authored-by: Micha Reiser <[email protected]>

Author: CheaterCodes

benches/compare.rs

@@ -10,7 +10,7 @@ include!("shims/global_alloc_overwrite.rs");
 
 #[salsa::input]
 pub struct Input {
-    #[return_ref]
+    #[returns(ref)]
     pub text: String,
 }
 
@@ -22,7 +22,7 @@ pub fn length(db: &dyn salsa::Database, input: Input) -> usize {
 
 #[salsa::interned]
 pub struct InternedInput<'db> {
-    #[return_ref]
+    #[returns(ref)]
     pub text: String,
 }
 

benches/incremental.rs

@@ -15,7 +15,7 @@ struct Tracked<'db> {
     number: usize,
 }
 
-#[salsa::tracked(return_ref)]
+#[salsa::tracked(returns(ref))]
 #[inline(never)]
 fn index<'db>(db: &'db dyn salsa::Database, input: Input) -> Vec<Tracked<'db>> {
     (0..input.field(db)).map(|i| Tracked::new(db, i)).collect()

book/src/overview.md

@@ -79,7 +79,7 @@ pub struct ProgramFile(salsa::Id);
 This means that, when you have a `ProgramFile`, you can easily copy it around and put it wherever you like.
 To actually read any of its fields, however, you will need to use the database and a getter method.
 
-### Reading fields and `return_ref`
+### Reading fields and `returns(ref)`
 
 You can access the value of an input's fields by using the getter method.
 As this is only reading the field, it just needs a `&`-reference to the database:
@@ -89,13 +89,13 @@ let contents: String = file.contents(&db);
 ```
 
 Invoking the accessor clones the value from the database.
-Sometimes this is not what you want, so you can annotate fields with `#[return_ref]` to indicate that they should return a reference into the database instead:
+Sometimes this is not what you want, so you can annotate fields with `#[returns(ref)]` to indicate that they should return a reference into the database instead:
 
 ```rust
 #[salsa::input]
 pub struct ProgramFile {
     pub path: PathBuf,
-    #[return_ref]
+    #[returns(ref)]
     pub contents: String,
 }
 ```
@@ -145,7 +145,7 @@ Tracked functions have to follow a particular structure:
 - They must take a "Salsa struct" as the second argument -- in our example, this is an input struct, but there are other kinds of Salsa structs we'll describe shortly.
 - They _can_ take additional arguments, but it's faster and better if they don't.
 
-Tracked functions can return any clone-able type. A clone is required since, when the value is cached, the result will be cloned out of the database. Tracked functions can also be annotated with `#[return_ref]` if you would prefer to return a reference into the database instead (if `parse_file` were so annotated, then callers would actually get back an `&Ast`, for example).
+Tracked functions can return any clone-able type. A clone is required since, when the value is cached, the result will be cloned out of the database. Tracked functions can also be annotated with `#[returns(ref)]` if you would prefer to return a reference into the database instead (if `parse_file` were so annotated, then callers would actually get back an `&Ast`, for example).
 
 ## Tracked structs
 
@@ -158,7 +158,7 @@ Example:
 ```rust
 #[salsa::tracked]
 struct Ast<'db> {
-    #[return_ref]
+    #[returns(ref)]
     top_level_items: Vec<Item>,
 }
 ```
@@ -252,7 +252,7 @@ Most compilers, for example, will define a type to represent a user identifier:
 ```rust
 #[salsa::interned]
 struct Word {
-    #[return_ref]
+    #[returns(ref)]
     pub text: String,
 }
 ```
@@ -269,7 +269,7 @@ let w3 = Word::new(db, "foo".to_string());
 
 When you create two interned structs with the same field values, you are guaranteed to get back the same integer id. So here, we know that `assert_eq!(w1, w3)` is true and `assert_ne!(w1, w2)`.
 
-You can access the fields of an interned struct using a getter, like `word.text(db)`. These getters respect the `#[return_ref]` annotation. Like tracked structs, the fields of interned structs are immutable.
+You can access the fields of an interned struct using a getter, like `word.text(db)`. These getters respect the `#[returns(ref)]` annotation. Like tracked structs, the fields of interned structs are immutable.
 
 ## Accumulators
 

book/src/reference/algorithm.md

@@ -20,7 +20,7 @@ fn parse_module(db: &dyn Db, module: Module) -> Ast {
     Ast::parse_text(module_text)
 }
 
-#[salsa::tracked(return_ref)]
+#[salsa::tracked(returns(ref))]
 fn module_text(db: &dyn Db, module: Module) -> String {
     panic!("text for module `{module:?}` not set")
 }

book/src/tutorial/ir.md

@@ -92,7 +92,7 @@ Apart from the fields being immutable, the API for working with a tracked struct
 
 - You can create a new value by using `new`: e.g., `Program::new(&db, some_statements)`
 - You use a getter to read the value of a field, just like with an input (e.g., `my_func.statements(db)` to read the `statements` field).
-  - In this case, the field is tagged as `#[return_ref]`, which means that the getter will return a `&Vec<Statement>`, instead of cloning the vector.
+  - In this case, the field is tagged as `#[returns(ref)]`, which means that the getter will return a `&Vec<Statement>`, instead of cloning the vector.
 
 ### The `'db` lifetime
 

book/src/tutorial/parser.md

@@ -61,12 +61,12 @@ Tracked functions may take other arguments as well, though our examples here do
 Functions that take additional arguments are less efficient and flexible.
 It's generally better to structure tracked functions as functions of a single Salsa struct if possible.
 
-### The `return_ref` annotation
+### The `returns(ref)` annotation
 
-You may have noticed that `parse_statements` is tagged with `#[salsa::tracked(return_ref)]`.
+You may have noticed that `parse_statements` is tagged with `#[salsa::tracked(returns(ref))]`.
 Ordinarily, when you call a tracked function, the result you get back is cloned out of the database.
-The `return_ref` attribute means that a reference into the database is returned instead.
+The `returns(ref)` attribute means that a reference into the database is returned instead.
 So, when called, `parse_statements` will return an `&Vec<Statement>` rather than cloning the `Vec`.
 This is useful as a performance optimization.
-(You may recall the `return_ref` annotation from the [ir](./ir.md) section of the tutorial,
+(You may recall the `returns(ref)` annotation from the [ir](./ir.md) section of the tutorial,
 where it was placed on struct fields, with roughly the same meaning.)

components/salsa-macro-rules/src/lib.rs

@@ -14,8 +14,8 @@
 
 mod macro_if;
 mod maybe_backdate;
-mod maybe_clone;
 mod maybe_default;
+mod return_mode;
 mod setup_accumulator_impl;
 mod setup_input_struct;
 mod setup_interned_struct;

components/salsa-macro-rules/src/maybe_backdate.rs

@@ -2,7 +2,7 @@
 #[macro_export]
 macro_rules! maybe_backdate {
     (
-        ($maybe_clone:ident, no_backdate, $maybe_default:ident),
+        ($return_mode:ident, no_backdate, $maybe_default:ident),
         $field_ty:ty,
         $old_field_place:expr,
         $new_field_place:expr,
@@ -20,7 +20,7 @@ macro_rules! maybe_backdate {
     };
 
     (
-        ($maybe_clone:ident, backdate, $maybe_default:ident),
+        ($return_mode:ident, backdate, $maybe_default:ident),
         $field_ty:ty,
         $old_field_place:expr,
         $new_field_place:expr,

components/salsa-macro-rules/src/maybe_clone.rs

@@ -4,15 +4,15 @@
 #[macro_export]
 macro_rules! maybe_default {
     (
-        ($maybe_clone:ident, $maybe_backdate:ident, default),
+        ($return_mode:ident, $maybe_backdate:ident, default),
         $field_ty:ty,
         $field_ref_expr:expr,
     ) => {
         <$field_ty>::default()
     };
 
     (
-        ($maybe_clone:ident, $maybe_backdate:ident, required),
+        ($return_mode:ident, $maybe_backdate:ident, required),
         $field_ty:ty,
         $field_ref_expr:expr,
     ) => {
@@ -22,11 +22,11 @@ macro_rules! maybe_default {
 
 #[macro_export]
 macro_rules! maybe_default_tt {
-    (($maybe_clone:ident, $maybe_backdate:ident, default) => $($t:tt)*) => {
+    (($return_mode:ident, $maybe_backdate:ident, default) => $($t:tt)*) => {
         $($t)*
     };
 
-    (($maybe_clone:ident, $maybe_backdate:ident, required) => $($t:tt)*) => {
+    (($return_mode:ident, $maybe_backdate:ident, required) => $($t:tt)*) => {
 
     };
 }

components/salsa-macro-rules/src/maybe_default.rs

@@ -0,0 +1,104 @@
+/// Generate the expression for the return type, depending on the return mode defined in [`salsa-macros::options::Options::returns`]
+///
+/// Used when generating field getters.
+#[macro_export]
+macro_rules! return_mode_expression {
+    (
+        (copy, $maybe_backdate:ident, $maybe_default:ident),
+        $field_ty:ty,
+        $field_ref_expr:expr,
+    ) => {
+        *$field_ref_expr
+    };
+
+    (
+        (clone, $maybe_backdate:ident, $maybe_default:ident),
+        $field_ty:ty,
+        $field_ref_expr:expr,
+    ) => {
+        ::core::clone::Clone::clone($field_ref_expr)
+    };
+
+    (
+        (ref, $maybe_backdate:ident, $maybe_default:ident),
+        $field_ty:ty,
+        $field_ref_expr:expr,
+    ) => {
+        $field_ref_expr
+    };
+
+    (
+        (deref, $maybe_backdate:ident, $maybe_default:ident),
+        $field_ty:ty,
+        $field_ref_expr:expr,
+    ) => {
+        ::core::ops::Deref::deref($field_ref_expr)
+    };
+
+    (
+        (as_ref, $maybe_backdate:ident, $maybe_default:ident),
+        $field_ty:ty,
+        $field_ref_expr:expr,
+    ) => {
+        ::salsa::SalsaAsRef::as_ref($field_ref_expr)
+    };
+
+    (
+        (as_deref, $maybe_backdate:ident, $maybe_default:ident),
+        $field_ty:ty,
+        $field_ref_expr:expr,
+    ) => {
+        ::salsa::SalsaAsDeref::as_deref($field_ref_expr)
+    };
+}
+
+#[macro_export]
+macro_rules! return_mode_ty {
+    (
+        (copy, $maybe_backdate:ident, $maybe_default:ident),
+        $db_lt:lifetime,
+        $field_ty:ty
+    ) => {
+        $field_ty
+    };
+
+    (
+        (clone, $maybe_backdate:ident, $maybe_default:ident),
+        $db_lt:lifetime,
+        $field_ty:ty
+    ) => {
+        $field_ty
+    };
+
+    (
+        (ref, $maybe_backdate:ident, $maybe_default:ident),
+        $db_lt:lifetime,
+        $field_ty:ty
+    ) => {
+        & $db_lt $field_ty
+    };
+
+    (
+        (deref, $maybe_backdate:ident, $maybe_default:ident),
+        $db_lt:lifetime,
+        $field_ty:ty
+    ) => {
+        & $db_lt <$field_ty as ::core::ops::Deref>::Target
+    };
+
+    (
+        (as_ref, $maybe_backdate:ident, $maybe_default:ident),
+        $db_lt:lifetime,
+        $field_ty:ty
+    ) => {
+        <$field_ty as ::salsa::SalsaAsRef>::AsRef<$db_lt>
+    };
+
+    (
+        (as_deref, $maybe_backdate:ident, $maybe_default:ident),
+        $db_lt:lifetime,
+        $field_ty:ty
+    ) => {
+        <$field_ty as ::salsa::SalsaAsDeref>::AsDeref<$db_lt>
+    };
+}

components/salsa-macro-rules/src/return_mode.rs

@@ -182,7 +182,7 @@ macro_rules! setup_input_struct {
                 }
 
                 $(
-                    $field_getter_vis fn $field_getter_id<'db, $Db>(self, db: &'db $Db) -> $zalsa::maybe_cloned_ty!($field_option, 'db, $field_ty)
+                    $field_getter_vis fn $field_getter_id<'db, $Db>(self, db: &'db $Db) -> $zalsa::return_mode_ty!($field_option, 'db, $field_ty)
                     where
                         // FIXME(rust-lang/rust#65991): The `db` argument *should* have the type `dyn Database`
                         $Db: ?Sized + $zalsa::Database,
@@ -192,7 +192,7 @@ macro_rules! setup_input_struct {
                             self,
                             $field_index,
                         );
-                        $zalsa::maybe_clone!(
+                        $zalsa::return_mode_expression!(
                             $field_option,
                             $field_ty,
                             &fields.$field_index,

components/salsa-macro-rules/src/setup_input_struct.rs

@@ -215,13 +215,13 @@ macro_rules! setup_interned_struct {
                 }
 
                 $(
-                    $field_getter_vis fn $field_getter_id<$Db>(self, db: &'db $Db) -> $zalsa::maybe_cloned_ty!($field_option, 'db, $field_ty)
+                    $field_getter_vis fn $field_getter_id<$Db>(self, db: &'db $Db) -> $zalsa::return_mode_ty!($field_option, 'db, $field_ty)
                     where
                         // FIXME(rust-lang/rust#65991): The `db` argument *should* have the type `dyn Database`
                         $Db: ?Sized + $zalsa::Database,
                     {
                         let fields = $Configuration::ingredient(db).fields(db.as_dyn_database(), self);
-                        $zalsa::maybe_clone!(
+                        $zalsa::return_mode_expression!(
                             $field_option,
                             $field_ty,
                             &fields.$field_index,