M1 mac fix, document doNotCompleteOnReturn's behavioral gap explicitly (#776)

* Fix gradle for M1 OSX machines

* Document doNotCompleteOnReturn's behavioral gap explicitly

Java counterpart to cadence-workflow/cadence-go-client#1229

Resolving this "two kinds of finished-timeouts / heartbeat-timeouts, but only one config" issue with Activity.doNotCompleteOnReturn will need some new semantics on the server side... but at least there's a workaround until then.

The general concept of a "pending activity" does seem worth supporting, particularly because it can respond with an "already completed" error when a second "complete" request is received. It just has unfortunate quirks at the moment.

* sometimes

Author: Groxx

build.gradle

@@ -119,11 +119,19 @@ sourceSets {
 
 protobuf {
     protoc {
-        artifact = 'com.google.protobuf:protoc:3.11.0'
+        if (osdetector.os == "osx") {
+            artifact = 'com.google.protobuf:protoc:3.11.0:osx-x86_64' // no arm version available
+        } else {
+            artifact = 'com.google.protobuf:protoc:3.11.0'
+        }
     }
     plugins {
         grpc {
-            artifact = 'io.grpc:protoc-gen-grpc-java:1.28.0'
+            if (osdetector.os == "osx") {
+                artifact = 'io.grpc:protoc-gen-grpc-java:1.28.0:osx-x86_64' // no arm version available
+            } else {
+                artifact = 'io.grpc:protoc-gen-grpc-java:1.28.0'
+            }
         }
     }
     generateProtoTasks {

src/main/java/com/uber/cadence/activity/Activity.java

@@ -163,6 +163,19 @@
  *     }
  * </code></pre>
  *
+ * <p>Caution: since using this sometimes implies "long" timeouts, activity-worker losses prior to recording the
+ * {@link Activity#getTaskToken()} in an external system (or prior to another thread calling it) may not be noticed
+ * until the "long" timeout occurs. This can be resolved by having another system call
+ * {@link com.uber.cadence.client.ActivityCompletionClient#heartbeat(byte[], Object)} while that external action is
+ * running, but there is currently no way to mitigate this issue without these heartbeats.  For in-process-only async
+ * completion, relying on heartbeating is safe and reliable because these heartbeats should occur as long as the
+ * process / background thread is still running.
+ *
+ * <p>If you cannot heartbeat and cannot tolerate this kind of delayed-activity-loss detection, consider emulating a
+ * long activity via a signal channel instead: you can start a short-lived activity and wait for a "saved to external
+ * system" signal, retrying as necessary, and then wait for an "external system finished" signal containing the final
+ * result.
+ *
  * <h3>Activity Heartbeating</h3>
  *
  * <p>Some activities are long running. To react to their crashes quickly, use a heartbeat
@@ -201,9 +214,23 @@
 public final class Activity {
 
   /**
-   * If this method is called during an activity execution then activity is not going to complete
+   * If this method is called during an activity execution then activity will not complete
    * when its method returns. It is expected to be completed asynchronously using {@link
    * com.uber.cadence.client.ActivityCompletionClient}.
+   *
+   * <p>Caution: since using this sometimes implies "long" timeouts, activity-worker losses prior to recording the
+   * {@link Activity#getTaskToken()} in an external system (or prior to another thread calling it) may not be noticed
+   * until the "long" timeout occurs.
+   * This can be resolved by having another system call
+   * {@link com.uber.cadence.client.ActivityCompletionClient#heartbeat(byte[], Object)} while that external action is
+   * running, but there is currently no way to mitigate this issue without these heartbeats.  For in-process-only async
+   * completion, relying on heartbeating is safe and reliable because these heartbeats should occur as long as the
+   * process / background thread is still running.
+   *
+   * <p>If you cannot heartbeat and cannot tolerate this kind of delayed-activity-loss detection, consider emulating a
+   * long activity via a signal channel instead: you can start a short-lived activity and wait for a "saved to external
+   * system" signal, retrying as necessary, and then wait for an "external system finished" signal containing the final
+   * result.
    */
   public static void doNotCompleteOnReturn() {
     ActivityInternal.doNotCompleteOnReturn();