xref: /aosp_15_r20/external/rust/beto-rust/common/pourover_macro/src/call_method/codegen.rs

// Copyright 2024 Google LLC
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

//! Code generation for the `call_method!` series of proc-macros. This module is used by creating a
//! [`MethodCall`] instance and calling [`MethodCall::generate`]. The generated code will vary
//! for each macro based on the contained [`Receiver`] value. If there is a detected issue with the
//! [`MethodCall`] provided, then `generate` will return a [`CodegenError`] with information on
//! what is wrong. This error can be converted into a [`syn::Error`] for reporting any failures to
//! the user.

use proc_macro2::{Span, TokenStream};
use quote::{quote, quote_spanned, TokenStreamExt};
use syn::{parse_quote, spanned::Spanned, Expr, Ident, ItemStatic, LitStr, Type};

use crate::type_parser::{JavaType, MethodSig, NonArray, Primitive, ReturnType};

/// The errors that can be encountered during codegen. Used in [`CodegenError`].
#[derive(Copy, Clone, Debug, Eq, PartialEq)]
pub enum ErrorKind {
    InvalidArgsLength { expected: usize, found: usize },
    ConstructorRetValShouldBeVoid,
    InvalidTypeSignature,
}

/// An error encountered during codegen with span information. Can be converted to [`syn::Error`].
/// using [`From`].
#[derive(Clone, Debug)]
pub struct CodegenError(pub Span, pub ErrorKind);

impl From<CodegenError> for syn::Error {
    fn from(CodegenError(span, kind): CodegenError) -> syn::Error {
        use ErrorKind::*;
        match kind {
            InvalidArgsLength { expected, found } => {
                syn::Error::new(span, format!("The number of args does not match the type signature provided: expected={expected}, found={found}"))
            }
            ConstructorRetValShouldBeVoid => {
                syn::Error::new(span, "Return type should be `void` (`V`) for constructor methods")
            }
            InvalidTypeSignature => syn::Error::new(span, "Failed to parse type signature"),
        }
    }
}

/// Codegen can fail with [`CodegenError`].
pub type CodegenResult<T> = Result<T, CodegenError>;

/// Describes a method that will be generated. Create one with [`MethodCall::new`] and generate
/// code with [`MethodCall::generate`]. This should be given AST nodes from the macro input so that
/// errors are associated properly to the input span.
pub struct MethodCall {
    env: Expr,
    method: MethodInfo,
    receiver: Receiver,
    arg_exprs: Vec<Expr>,
}

impl MethodCall {
    /// Create a new MethodCall instance
    pub fn new(env: Expr, method: MethodInfo, receiver: Receiver, arg_exprs: Vec<Expr>) -> Self {
        Self {
            env,
            method,
            receiver,
            arg_exprs,
        }
    }

    /// Generate code to call the described method.
    pub fn generate(&self) -> CodegenResult<TokenStream> {
        // Needs to be threaded manually to other methods since self-referential structs can't
        // exist.
        let sig = self.method.sig()?;

        let args = self.generate_args(&sig)?;

        let method_call = self
            .receiver
            .generate_call(&self.env, &self.method, &sig, &args)?;

        // Wrap the generated code in a closure so that we can access the outer scope but any
        // variables we define aren't accessible by the outer scope. There is small hygiene issue
        // where the arg exprs have our `env` variable in scope. If this becomes an issue we can
        // refactor these exprs to be passed as closure parameters instead.
        Ok(quote! {
            (|| {
                #method_call
            })()
        })
    }

    /// Generate the `&[jni::jvalue]` arguments slice that will be passed to the `jni` method call.
    /// This validates the argument count and types.
    fn generate_args(&self, sig: &MethodSig<'_>) -> CodegenResult<Expr> {
        // Safety: must check that arg count matches the signature
        if self.arg_exprs.len() != sig.args.len() {
            return Err(CodegenError(
                self.method.sig.span(),
                ErrorKind::InvalidArgsLength {
                    expected: sig.args.len(),
                    found: self.arg_exprs.len(),
                },
            ));
        }

        // Create each `jvalue` expression
        let type_expr_pairs = core::iter::zip(sig.args.iter().copied(), self.arg_exprs.iter());
        let jvalues = type_expr_pairs.map(|(ty, expr)| generate_jvalue(ty, expr));

        // Put the `jvalue` expressions in a slice.
        Ok(parse_quote! {
            &[#(#jvalues),*]
        })
    }
}

/// The receiver of the method call and the type of the method.
pub enum Receiver {
    /// A constructor.
    Constructor,
    /// A static method.
    Static,
    /// An instance method. The `Expr` here is the `this` object.
    Instance(Expr),
}

impl Receiver {
    /// Generate the code that performs the JNI call.
    fn generate_call(
        &self,
        env: &Expr,
        method_info: &MethodInfo,
        sig: &MethodSig<'_>,
        args: &Expr,
    ) -> CodegenResult<TokenStream> {
        // Constructors are void methods. Validate this fact.
        if matches!(*self, Receiver::Constructor) && !sig.ret.is_void() {
            return Err(CodegenError(
                method_info.sig.span(),
                ErrorKind::ConstructorRetValShouldBeVoid,
            ));
        }

        // The static item containing the `pourover::[Static]MethodDesc`.
        let method_desc = self.generate_method_desc(method_info);

        // The `jni::signature::ReturnType` that the `jni` crate uses to perform the correct native
        // call.
        let return_type = return_type_from_sig(sig.ret);

        // A conversion expression to convert from `jni::object::JValueOwned` to the actual return
        // type. We have this information from the parsed method signature whereas the `jni` crate
        // only knows this at runtime.
        let conversion = return_value_conversion_from_sig(sig.ret);

        // This preamble is used to evaluate all the client-provided expressions outside of the
        // `unsafe` block. This is the same for all receiver kinds.
        let mut method_call = quote! {
            #method_desc

            let env: &mut ::jni::JNIEnv = #env;
            let method_id = ::jni::descriptors::Desc::lookup(&METHOD_DESC, env)?;
            let args: &[::jni::sys::jvalue] = #args;
        };

        // Generate the unsafe JNI call.
        //
        // Safety: `args` contains the arguments to this method. The type signature of this
        // method is `#sig`.
        //
        // `args` must adhere to the following:
        //  - `args.len()` must match the number of arguments given in the type signature.
        //  - The union value of each arg in `args` must match the type specified in the type
        //    signature.
        //
        // These conditions are upheld by this proc macro and a compile error will be caused if
        // they are broken. No user-provided code is executed within the `unsafe` block.
        method_call.append_all(match self {
            Self::Constructor => quote! {
                unsafe {
                    env.new_object_unchecked(
                        METHOD_DESC.cls(),
                        method_id,
                        args,
                    )
                }
            },
            Self::Static => quote! {
                unsafe {
                    env.call_static_method_unchecked(
                        METHOD_DESC.cls(),
                        method_id,
                        #return_type,
                        args,
                    )
                }#conversion
            },
            Self::Instance(this) => quote! {
                let this_obj: &JObject = #this;
                unsafe {
                    env.call_method_unchecked(
                        this_obj,
                        method_id,
                        #return_type,
                        args,
                    )
                }#conversion
            },
        });

        Ok(method_call)
    }

    fn generate_method_desc(&self, MethodInfo { cls, name, sig, .. }: &MethodInfo) -> ItemStatic {
        match self {
            Self::Constructor => parse_quote! {
                static METHOD_DESC: ::pourover::desc::MethodDesc = (#cls).constructor(#sig);
            },
            Self::Static => parse_quote! {
                static METHOD_DESC: ::pourover::desc::StaticMethodDesc = (#cls).static_method(#name, #sig);
            },
            Self::Instance(_) => parse_quote! {
                static METHOD_DESC: ::pourover::desc::MethodDesc = (#cls).method(#name, #sig);
            },
        }
    }
}

/// Information about the method being called
pub struct MethodInfo {
    cls: Expr,
    name: Expr,
    sig: LitStr,
    /// Derived from `sig.value()`. This string must be stored in the struct so that we can return
    /// a `MethodSig` instance that references it from `MethodInfo::sig()`.
    sig_str: String,
}

impl MethodInfo {
    pub fn new(cls: Expr, name: Expr, sig: LitStr) -> Self {
        let sig_str = sig.value();
        Self {
            cls,
            name,
            sig,
            sig_str,
        }
    }

    /// Parse the type signature from `sig`. Will return a [`CodegenError`] if the signature cannot
    /// be parsed.
    fn sig(&self) -> CodegenResult<MethodSig<'_>> {
        MethodSig::try_from_str(&self.sig_str)
            .ok_or_else(|| CodegenError(self.sig.span(), ErrorKind::InvalidTypeSignature))
    }
}

/// Generate a `jni::sys::jvalue` instance given a Java type and a Rust value.
///
/// Safety: The generated `jvalue` must match the given type `ty`.
fn generate_jvalue(ty: JavaType<'_>, expr: &Expr) -> TokenStream {
    // The `jvalue` field to inhabit
    let union_field: Ident;
    // The expected input type
    let type_name: Type;
    // Whether we need to call `JObject::as_raw()` on the input type
    let needs_as_raw: bool;

    // Fill the above values based the type signature.
    match ty {
        JavaType::Array { depth, ty } => {
            union_field = parse_quote![l];
            if let NonArray::Primitive(p) = ty {
                if depth.get() == 1 {
                    let prim_type = prim_to_sys_type(p);
                    type_name = parse_quote![::jni::objects::JPrimitiveArray<'_, #prim_type>]
                } else {
                    type_name = parse_quote![&::jni::objects::JObjectArray<'_>];
                }
            } else {
                type_name = parse_quote![&::jni::objects::JObjectArray<'_>];
            }
            needs_as_raw = true;
        }
        JavaType::NonArray(NonArray::Object { cls }) => {
            union_field = parse_quote![l];
            type_name = match cls {
                "java/lang/String" => parse_quote![&::jni::objects::JString<'_>],
                "java/util/List" => parse_quote![&::jni::objects::JList<'_>],
                "java/util/Map" => parse_quote![&::jni::objects::JMap<'_>],
                _ => parse_quote![&::jni::objects::JObject<'_>],
            };
            needs_as_raw = true;
        }
        JavaType::NonArray(NonArray::Primitive(p)) => {
            union_field = prim_to_union_field(p);
            type_name = prim_to_sys_type(p);
            needs_as_raw = false;
        }
    }

    // The as_raw() tokens if required.
    let as_raw = if needs_as_raw {
        quote! { .as_raw() }
    } else {
        quote![]
    };

    // Create the `jvalue` expression. This uses `identity` to produce nice type error messages.
    quote_spanned! { expr.span() =>
        ::jni::sys::jvalue {
            #union_field: ::core::convert::identity::<#type_name>(#expr) #as_raw
        }
    }
}

/// Get a `::jni::signature::ReturnType` expression from a [`crate::type_parser::ReturnType`]. This
/// value is passed to the `jni` crate so that it knows which JNI method to call.
fn return_type_from_sig(ret: ReturnType<'_>) -> Expr {
    let prim_type = |prim| parse_quote![::jni::signature::ReturnType::Primitive(::jni::signature::Primitive::#prim)];

    use crate::type_parser::{JavaType::*, NonArray::*, Primitive::*};

    match ret {
        ReturnType::Void => prim_type(quote![Void]),
        ReturnType::Returns(NonArray(Primitive(Boolean))) => prim_type(quote![Boolean]),
        ReturnType::Returns(NonArray(Primitive(Byte))) => prim_type(quote![Byte]),
        ReturnType::Returns(NonArray(Primitive(Char))) => prim_type(quote![Char]),
        ReturnType::Returns(NonArray(Primitive(Double))) => prim_type(quote![Double]),
        ReturnType::Returns(NonArray(Primitive(Float))) => prim_type(quote![Float]),
        ReturnType::Returns(NonArray(Primitive(Int))) => prim_type(quote![Int]),
        ReturnType::Returns(NonArray(Primitive(Long))) => prim_type(quote![Long]),
        ReturnType::Returns(NonArray(Primitive(Short))) => prim_type(quote![Short]),
        ReturnType::Returns(NonArray(Object { .. })) => {
            parse_quote![::jni::signature::ReturnType::Object]
        }
        ReturnType::Returns(Array { .. }) => parse_quote![::jni::signature::ReturnType::Array],
    }
}

/// A postfix call on a `jni::objects::JValueOwned` instance to convert it to the type specified by
/// `ret`. Since we have this information from the type signature we can  perform this conversion
/// in the macro.
fn return_value_conversion_from_sig(ret: ReturnType<'_>) -> TokenStream {
    use crate::type_parser::{JavaType::*, NonArray::*};

    match ret {
        ReturnType::Void => quote! { .and_then(::jni::objects::JValueOwned::v) },
        ReturnType::Returns(NonArray(Primitive(p))) => {
            let prim = prim_to_union_field(p);
            quote! { .and_then(::jni::objects::JValueOwned::#prim) }
        }
        ReturnType::Returns(NonArray(Object { cls })) => {
            let mut conversion = quote! { .and_then(::jni::objects::JValueOwned::l) };
            match cls {
                "java/lang/String" => {
                    conversion.append_all(quote! { .map(::jni::objects::JString::from) });
                }
                "java/util/List" => {
                    conversion.append_all(quote! { .map(::jni::objects::JList::from) });
                }
                "java/util/Map" => {
                    conversion.append_all(quote! { .map(::jni::objects::JMap::from) });
                }
                _ => {
                    // Already a JObject, so we are good here
                }
            }
            conversion
        }
        ReturnType::Returns(Array {
            depth,
            ty: Primitive(p),
        }) if depth.get() == 1 => {
            let sys_type = prim_to_sys_type(p);
            quote! {
                .and_then(::jni::objects::JValueOwned::l)
                .map(::jni::objects::JPrimitiveArray::<#sys_type>::from)
            }
        }
        ReturnType::Returns(Array { .. }) => quote! {
            .and_then(::jni::objects::JValueOwned::l)
            .map(::jni::objects::JObjectArray::from)
        },
    }
}

/// From a [`Primitive`], this gets the `jni::sys::jvalue` union field name for that type. This is
/// also the `jni::objects::JValueGen` getter name.
fn prim_to_union_field(p: Primitive) -> Ident {
    quote::format_ident!("{}", p.as_char().to_ascii_lowercase())
}

/// From a [`Primitive`], this gets the matching `jvalue::sys` type.
fn prim_to_sys_type(p: Primitive) -> Type {
    match p {
        Primitive::Boolean => parse_quote![::jni::sys::jboolean],
        Primitive::Byte => parse_quote![::jni::sys::jbyte],
        Primitive::Char => parse_quote![::jni::sys::jchar],
        Primitive::Double => parse_quote![::jni::sys::jdouble],
        Primitive::Float => parse_quote![::jni::sys::jfloat],
        Primitive::Int => parse_quote![::jni::sys::jint],
        Primitive::Long => parse_quote![::jni::sys::jlong],
        Primitive::Short => parse_quote![::jni::sys::jshort],
    }
}

#[cfg(test)]
#[allow(clippy::unwrap_used, clippy::expect_used, clippy::panic)]
mod tests {
    use super::*;
    use crate::test_util::contains_ident;
    use quote::ToTokens;
    use syn::parse_quote;

    fn example_method_call() -> MethodCall {
        MethodCall::new(
            parse_quote![&mut env],
            MethodInfo::new(
                parse_quote![&FOO_CLS],
                parse_quote!["example"],
                parse_quote!["(II)I"],
            ),
            Receiver::Instance(parse_quote![&foo]),
            vec![parse_quote![123], parse_quote![2 + 3]],
        )
    }

    #[test]
    fn args_are_counted() {
        let mut call = example_method_call();
        call.arg_exprs.push(parse_quote![too_many]);

        let CodegenError(_span, kind) = call.generate().unwrap_err();

        assert_eq!(
            ErrorKind::InvalidArgsLength {
                expected: 2,
                found: 3
            },
            kind
        );
    }

    #[test]
    fn constructor_return_type_is_void() {
        let mut call = example_method_call();
        call.receiver = Receiver::Constructor;

        let CodegenError(_span, kind) = call.generate().unwrap_err();

        assert_eq!(ErrorKind::ConstructorRetValShouldBeVoid, kind);
    }

    #[test]
    fn invalid_type_sig_is_error() {
        let mut call = example_method_call();
        call.method.sig = parse_quote!["L"];
        call.method.sig_str = call.method.sig.value();

        let CodegenError(_span, kind) = call.generate().unwrap_err();

        assert_eq!(ErrorKind::InvalidTypeSignature, kind);
    }

    #[test]
    fn jni_types_are_used_for_stdlib_classes_input() {
        let types = [
            ("Ljava/lang/String;", "JString"),
            ("Ljava/util/Map;", "JMap"),
            ("Ljava/util/List;", "JList"),
            ("[Ljava/lang/String;", "JObjectArray"),
            ("[[I", "JObjectArray"),
            ("[I", "JPrimitiveArray"),
            ("Lcom/example/MyObject;", "JObject"),
            ("Z", "jboolean"),
            ("C", "jchar"),
            ("B", "jbyte"),
            ("S", "jshort"),
            ("I", "jint"),
            ("J", "jlong"),
            ("F", "jfloat"),
            ("D", "jdouble"),
        ];

        for (desc, jni_type) in types {
            let jt = JavaType::try_from_str(desc).unwrap();
            let expr = parse_quote![some_value];

            let jvalue = generate_jvalue(jt, &expr);

            assert!(
                contains_ident(jvalue, jni_type),
                "desc: {desc}, jni_type: {jni_type}"
            );
        }
    }

    #[test]
    fn jni_types_are_used_for_stdlib_classes_output() {
        let types = [
            ("Ljava/lang/String;", "JString"),
            ("Ljava/util/Map;", "JMap"),
            ("Ljava/util/List;", "JList"),
            ("[Ljava/lang/String;", "JObjectArray"),
            ("[[I", "JObjectArray"),
            ("[I", "JPrimitiveArray"),
        ];

        for (desc, jni_type) in types {
            let rt = ReturnType::try_from_str(desc).unwrap();

            let conversion = return_value_conversion_from_sig(rt);

            assert!(
                contains_ident(conversion, jni_type),
                "desc: {desc}, jni_type: {jni_type}"
            );
        }
    }

    #[test]
    fn return_type_passed_to_jni_is_correct() {
        let types = [
            ("Ljava/lang/String;", "Object"),
            ("Ljava/util/Map;", "Object"),
            ("Ljava/util/List;", "Object"),
            ("[Ljava/lang/String;", "Array"),
            ("[[I", "Array"),
            ("[I", "Array"),
            ("V", "Void"),
            ("Z", "Boolean"),
            ("C", "Char"),
            ("B", "Byte"),
            ("S", "Short"),
            ("I", "Int"),
            ("J", "Long"),
            ("F", "Float"),
            ("D", "Double"),
        ];

        for (desc, return_type) in types {
            let rt = ReturnType::try_from_str(desc).unwrap();

            let expr = return_type_from_sig(rt).into_token_stream();

            assert!(
                contains_ident(expr, return_type),
                "desc: {desc}, return_type: {return_type}"
            );
        }
    }

    #[test]
    fn method_desc_is_correct() {
        let mut call = example_method_call();
        call.method.sig = parse_quote!["(II)V"];
        call.method.sig_str = call.method.sig.value();

        let tests = [
            (Receiver::Constructor, "constructor"),
            (Receiver::Static, "static_method"),
            (Receiver::Instance(parse_quote![this_value]), "method"),
        ];

        for (receiver, method_ident) in tests {
            let desc = receiver.generate_method_desc(&call.method);
            let rhs = desc.expr.into_token_stream();

            assert!(contains_ident(rhs, method_ident), "method: {method_ident}");
        }
    }

    #[test]
    fn jni_call_is_correct() {
        let mut call = example_method_call();
        call.method.sig = parse_quote!["(II)V"];
        call.method.sig_str = call.method.sig.value();
        let sig = call.method.sig().unwrap();
        let args = parse_quote![test_stub];

        let tests = [
            (Receiver::Constructor, "new_object_unchecked"),
            (Receiver::Static, "call_static_method_unchecked"),
            (
                Receiver::Instance(parse_quote![this_value]),
                "call_method_unchecked",
            ),
        ];

        for (receiver, method_ident) in tests {
            let call = receiver
                .generate_call(&call.env, &call.method, &sig, &args)
                .unwrap();

            assert!(contains_ident(call, method_ident), "method: {method_ident}");
        }
    }
}