Release 0.19.0

Author: astonbitecode

.gitignore

@@ -7,4 +7,5 @@
 **/settings/
 **/primer/
 **/.settings
-**/.classpath
+**/.classpath
+*.code-workspace

README.md

@@ -1,7 +1,7 @@
 # j4rs
 
 [![crates.io](https://img.shields.io/crates/v/j4rs.svg)](https://crates.io/crates/j4rs)
-[![Maven Central](https://img.shields.io/badge/Maven%20Central-0.18.0-blue.svg)](https://central.sonatype.com/artifact/io.github.astonbitecode/j4rs/)
+[![Maven Central](https://img.shields.io/badge/Maven%20Central-0.19.0-blue.svg)](https://central.sonatype.com/artifact/io.github.astonbitecode/j4rs/)
 ![Build](https://github.com/astonbitecode/j4rs/actions/workflows/ci-workflow.yml/badge.svg)
 
 j4rs stands for __'Java for Rust'__ and allows effortless calls to Java code from Rust and vice-versa.
@@ -260,6 +260,14 @@ using an internal one-threaded `ScheduledExecutorService`.
 
 This has apparent performance issues.
 
+#### `invoke_async` and `Send`
+
+`Instance`s  are `Send` and can be safely sent to other threads. However, because of [Send Approximation](https://rust-lang.github.io/async-book/07_workarounds/03_send_approximation.html), the `Future` returned by `invoke_async` is _not_ `Send`, even if it just contains an `Instance`. This is because the `Jvm` is being captured by the `async` call as well and the `Jvm` is __not__ `Send`.
+
+In order to have a `Future<Instance>` that __is__ `Send`, the `Jvm::invoke_into_sendable_async` can be used. This function does not get a `Jvm` as argument; it creates one internally when needed and applies some scoping workarounds in order to achieve returning a `Future<Instance>` which is also `Send`.
+
+Discussion [here](https://github.com/astonbitecode/j4rs/issues/103).
+
 ### Casting
 
 An `Instance` may be casted to some other Class:
@@ -446,7 +454,7 @@ The jar for `j4rs` is available in the Maven Central. It may be used by adding t
 <dependency>
     <groupId>io.github.astonbitecode</groupId>
     <artifactId>j4rs</artifactId>
-    <version>0.18.0</version>
+    <version>0.19.0</version>
     <scope>provided</scope>
 </dependency>
 ```

java/pom.xml

@@ -3,7 +3,7 @@
     <modelVersion>4.0.0</modelVersion>
     <groupId>io.github.astonbitecode</groupId>
     <artifactId>j4rs</artifactId>
-    <version>0.19.0-SNAPSHOT</version>
+    <version>0.19.0</version>
     <name>j4rs</name>
     <description>Java for Rust</description>
     <url>https://github.com/astonbitecode/j4rs</url>

rust/README.md

@@ -1,7 +1,7 @@
 # j4rs
 
 [![crates.io](https://img.shields.io/crates/v/j4rs.svg)](https://crates.io/crates/j4rs)
-[![Maven Central](https://img.shields.io/badge/Maven%20Central-0.18.0-blue.svg)](https://central.sonatype.com/artifact/io.github.astonbitecode/j4rs/)
+[![Maven Central](https://img.shields.io/badge/Maven%20Central-0.19.0-blue.svg)](https://central.sonatype.com/artifact/io.github.astonbitecode/j4rs/)
 ![Build](https://github.com/astonbitecode/j4rs/actions/workflows/ci-workflow.yml/badge.svg)
 
 j4rs stands for __'Java for Rust'__ and allows effortless calls to Java code from Rust and vice-versa.
@@ -260,6 +260,14 @@ using an internal one-threaded `ScheduledExecutorService`.
 
 This has apparent performance issues.
 
+#### `invoke_async` and `Send`
+
+`Instance`s  are `Send` and can be safely sent to other threads. However, because of [Send Approximation](https://rust-lang.github.io/async-book/07_workarounds/03_send_approximation.html), the `Future` returned by `invoke_async` is _not_ `Send`, even if it just contains an `Instance`. This is because the `Jvm` is being captured by the `async` call as well and the `Jvm` is __not__ `Send`.
+
+In order to have a `Future<Instance>` that __is__ `Send`, the `Jvm::invoke_into_sendable_async` can be used. This function does not get a `Jvm` as argument; it creates one internally when needed and applies some scoping workarounds in order to achieve returning a `Future<Instance>` which is also `Send`.
+
+Discussion [here](https://github.com/astonbitecode/j4rs/issues/103).
+
 ### Casting
 
 An `Instance` may be casted to some other Class:
@@ -446,7 +454,7 @@ The jar for `j4rs` is available in the Maven Central. It may be used by adding t
 <dependency>
     <groupId>io.github.astonbitecode</groupId>
     <artifactId>j4rs</artifactId>
-    <version>0.18.0</version>
+    <version>0.19.0</version>
     <scope>provided</scope>
 </dependency>
 ```
@@ -486,7 +494,7 @@ pub extern fn jni_onload(env: *mut JavaVM, _reserved: jobject) -> jint {
 Create an `Activity` and define your native methods normally, as described [here](#java-to-rust-support).
 
 Note:
-If you encounter any issues when using j4rs in older Android versions, this may be caused by Java 8 compatibility problems. 
+If you encounter any issues when using j4rs in older Android versions, this may be caused by Java 8 compatibility problems.
 This is why there is a `Java 7` version of `j4rs`:
 
 ```xml

rust/build.rs

@@ -27,7 +27,7 @@ use java_locator;
 use sha2::{Digest, Sha256};
 
 // This is the version of the jar that should be used
-const VERSION: &'static str = "0.19.0-SNAPSHOT";
+const VERSION: &'static str = "0.19.0";
 const JAVA_FX_VERSION: &'static str = "21.0.2";
 
 fn main() -> Result<(), J4rsBuildError> {

rust/jassets/j4rs-0.19.0-SNAPSHOT-jar-with-dependencies.jar renamed to rust/jassets/j4rs-0.19.0-jar-with-dependencies.jar

@@ -22,6 +22,7 @@ use std::convert::TryFrom;
 use std::sync::mpsc::{Receiver, Sender};
 
 /// A Java instance
+/// Instances contain global Java references and can be sent to other threads
 #[derive(Serialize)]
 pub struct Instance {
     /// The name of the class of this instance
@@ -127,12 +128,13 @@ impl Drop for Instance {
     }
 }
 
+/// Instances contain global Java references and can be sent to other threads
 unsafe impl Send for Instance {}
 
 /// A receiver for Java Instances.
 ///
 /// It keeps a channel Receiver to get callback Instances from the Java world
-/// and the address of a Box<Sender<Instance>> Box in the heap. This Box is used by Java to communicate
+/// and the address of a `Box<Sender<Instance>>` Box in the heap. This Box is used by Java to communicate
 /// asynchronously Instances to Rust.
 ///
 /// On Drop, the InstanceReceiver removes the Box from the heap.

rust/src/api/instance.rs

@@ -1756,17 +1756,17 @@ impl<'a> JvmBuilder<'a> {
     ///
     /// If not, you will get exceptions like the following:
     ///
-    /// java.lang.NoSuchMethodError: java.net.URLClassLoader.<init>(Ljava/lang/String;[Ljava/net/URL;Ljava/lang/ClassLoader;)V
-    //         at org.astonbitecode.j4rs.api.deploy.J4rsClassLoader.<init>(J4rsClassLoader.java:22)
-    //         at sun.reflect.NativeConstructorAccessorImpl.newInstance0(Native Method)
-    //         at sun.reflect.NativeConstructorAccessorImpl.newInstance(NativeConstructorAccessorImpl.java:62)
-    //         at sun.reflect.DelegatingConstructorAccessorImpl.newInstance(DelegatingConstructorAccessorImpl.java:45)
-    //         at java.lang.reflect.Constructor.newInstance(Constructor.java:423)
-    //         at java.lang.SystemClassLoaderAction.run(ClassLoader.java:2204)
-    //         at java.lang.SystemClassLoaderAction.run(ClassLoader.java:2188)
-    //         at java.security.AccessController.doPrivileged(Native Method)
-    //         at java.lang.ClassLoader.initSystemClassLoader(ClassLoader.java:1449)
-    //         at java.lang.ClassLoader.getSystemClassLoader(ClassLoader.java:1429)
+    /// > java.lang.NoSuchMethodError: java.net.URLClassLoader.`<init>`(Ljava/lang/String;[Ljava/net/URL;Ljava/lang/ClassLoader;)V
+    ///         at org.astonbitecode.j4rs.api.deploy.J4rsClassLoader.`<init>`(J4rsClassLoader.java:22)
+    ///         at sun.reflect.NativeConstructorAccessorImpl.newInstance0(Native Method)
+    ///         at sun.reflect.NativeConstructorAccessorImpl.newInstance(NativeConstructorAccessorImpl.java:62)
+    ///         at sun.reflect.DelegatingConstructorAccessorImpl.newInstance(DelegatingConstructorAccessorImpl.java:45)
+    ///         at java.lang.reflect.Constructor.newInstance(Constructor.java:423)
+    ///         at java.lang.SystemClassLoaderAction.run(ClassLoader.java:2204)
+    ///         at java.lang.SystemClassLoaderAction.run(ClassLoader.java:2188)
+    ///         at java.security.AccessController.doPrivileged(Native Method)
+    ///         at java.lang.ClassLoader.initSystemClassLoader(ClassLoader.java:1449)
+    ///         at java.lang.ClassLoader.getSystemClassLoader(ClassLoader.java:1429)
     pub fn with_default_classloader(&'a mut self) -> &'a mut JvmBuilder {
         self.default_classloader = true;
         self

rust/src/api/mod.rs

@@ -48,6 +48,13 @@ impl Jvm {
         Self::do_return(self.jni_env, instance)?
     }
 
+    /// Invokes the method `method_name` of a created `Instance` asynchronously, passing an array of `InvocationArg`s.
+    /// It returns an `Instance` as the result of the invocation.
+    /// 
+    /// 
+    /// `Instance`s  are `Send` and can be safely sent to other threads. However, because of [Send Approximation](https://rust-lang.github.io/async-book/07_workarounds/03_send_approximation.html), the `Future` returned by `invoke_async` is _not_ `Send`, even if it just contains an `Instance`. This is because the `Jvm` is being captured by the `async` call as well and the `Jvm` is __not__ `Send`.
+    /// 
+    /// In order to have a `Future<Instance>` that __is__ `Send`, the `Jvm::invoke_into_sendable_async` can be used. This function does not get a `Jvm` as argument; it creates one internally when needed and applies some scoping workarounds in order to achieve returning a `Future<Instance>` which is also `Send`.
     pub async fn invoke_into_sendable_async(
         instance: Instance,
         method_name: String,

rust/src/async_api/mod.rs

@@ -12,6 +12,8 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+#![doc = include_str!("../README.md")]
+
 #[macro_use]
 extern crate lazy_static;
 extern crate libc;