APISIX-38 Document the threading model and async plugins

Author: chibenwa

docs/en/latest/the-internal-of-apisix-java-plugin-runner.md

@@ -78,3 +78,39 @@ The current type takes the following values
 * 2 means http_req_call
 
 The binary data generated by the flatbuffer serialization is placed in the data segment.
+
+## Threading model
+
+Apisix plugin runner will run your plugins directly onto the event loop.
+
+While this empower the best performance possible, as a plugin developer you will have the responsibility 
+never to block threads on the event loop. Doing so would result in catastrophic performance drop.
+
+Hopefully one can write asynchronous plugins easily: just call the `PluginFilterChain` as a callback once you 
+are done.
+
+For instance:
+
+```java
+@Component
+public class AsyncResponseFilter implements PluginFilter {
+    @Override
+    public String name() {
+        return "AyncResponseFilter";
+    }
+
+    @Override
+    public void postFilter(PostRequest request, PostResponse response, PluginFilterChain chain) {
+        callExternalService()
+            .thenAccept(body -> {
+                response.setBody(body);
+                chain.postFilter(request, response);
+            });
+    }
+
+    // This simulates calls to an external service
+    CompletableFuture<String> callExternalService() {
+        return CompletableFuture.completedFuture("response_body");
+    }
+}
+```

sample/src/main/java/org/apache/apisix/plugin/runner/filter/AsyncResponseFilter.java

@@ -0,0 +1,46 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You 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.
+ */
+
+package org.apache.apisix.plugin.runner.filter;
+
+import java.util.concurrent.CompletableFuture;
+
+import org.apache.apisix.plugin.runner.PostRequest;
+import org.apache.apisix.plugin.runner.PostResponse;
+import org.springframework.stereotype.Component;
+
+@Component
+public class AsyncResponseFilter implements PluginFilter {
+    @Override
+    public String name() {
+        return "AsyncResponseFilter";
+    }
+
+    @Override
+    public void postFilter(PostRequest request, PostResponse response, PluginFilterChain chain) {
+        callExternalService()
+            .thenAccept(body -> {
+                response.setBody(body);
+                chain.postFilter(request, response);
+            });
+    }
+
+    // This simulates calls to an external service
+    CompletableFuture<String> callExternalService() {
+        return CompletableFuture.completedFuture("response_body");
+    }
+}