Merge pull request #61 from NikitaKatkov/reactive-blocking-annotations

[Non]BlockingContext annotations introduced

Author: amaembo

common/src/main/java/org/jetbrains/annotations/Blocking.java

@@ -1,3 +1,19 @@
+/*
+ * Copyright 2000-2021 JetBrains s.r.o.
+ *
+ * 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
+ *
+ * https://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.jetbrains.annotations;
 
 import java.lang.annotation.*;

common/src/main/java/org/jetbrains/annotations/NonBlocking.java

@@ -1,3 +1,19 @@
+/*
+ * Copyright 2000-2021 JetBrains s.r.o.
+ *
+ * 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
+ *
+ * https://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.jetbrains.annotations;
 
 import java.lang.annotation.*;

java8/src/main/java/org/jetbrains/annotations/BlockingExecutor.java

@@ -0,0 +1,71 @@
+/*
+ * Copyright 2000-2021 JetBrains s.r.o.
+ *
+ * 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
+ *
+ * https://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.jetbrains.annotations;
+
+import java.lang.annotation.*;
+
+/**
+ * Indicates that the annotated executor (CoroutineContext, Scheduler)
+ * allows blocking methods execution.<br><br>
+ * <p>
+ * If a given executor does not allow blocking calls, {@link NonBlockingExecutor} should be used.<br><br>
+ * <p>
+ *
+ * Example 1 (Kotlin coroutines):
+ * <pre>
+ * {@code
+ *  class BlockingExampleService {
+ *      val dispatcher: @BlockingExecutor CoroutineContext
+ *          get() { ... }
+ *
+ *      suspend fun foo() {
+ *          val result = withContext(dispatcher) {
+ *              blockingBuzz() // no IDE warning
+ *          }
+ *      }
+ *
+ *      @Blocking fun blockingBuzz() { ... }
+ *  }
+ * }
+ * </pre><br>
+ * <p>
+ * Example 2 (Java with Reactor framework):
+ * <pre>
+ * {@code
+ * class BlockingExampleService {
+ *     private static final @BlockingExecutor Scheduler blockingScheduler =
+ *             Schedulers.newBoundedElastic(4, 10, "executor");
+ *
+ *     public Flux<String> foo(Flux<String> urls) {
+ *         return urls.publishOn(blockingScheduler)
+ *                 .map(url -> blockingBuzz(url));  // no IDE warning
+ *     }
+ *
+ *     @Blocking
+ *     private String blockingBuzz(String url) { ... }
+ * }
+ * }
+ * </pre>
+ * <p>
+ * @see Blocking
+ * @see NonBlocking
+ */
+@Documented
+@Retention(RetentionPolicy.CLASS)
+@Target({ElementType.TYPE, ElementType.TYPE_USE})
+public @interface BlockingExecutor {
+}

java8/src/main/java/org/jetbrains/annotations/NonBlockingExecutor.java

@@ -0,0 +1,72 @@
+/*
+ * Copyright 2000-2021 JetBrains s.r.o.
+ *
+ * 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
+ *
+ * https://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.jetbrains.annotations;
+
+import java.lang.annotation.*;
+
+/**
+ * Indicates that the annotated executor (CoroutineContext, Scheduler)
+ * does not allow blocking methods execution.<br><br>
+ * <p>
+ *
+ * If a given executor allows blocking calls, {@link BlockingExecutor} should be used.<br><br>
+ * <p>
+ *
+ * Example 1 (Kotlin coroutines):
+ * <pre>
+ * {@code
+ *  class NonBlockingExampleService {
+ *      val dispatcher: @NonBlockingExecutor CoroutineContext
+ *          get() { ... }
+ *
+ *      suspend fun foo() {
+ *          val result = withContext(dispatcher) {
+ *              blockingBuzz() // IDE warning: `Possibly blocking call in non-blocking context`
+ *          }
+ *      }
+ *
+ *      @Blocking fun blockingBuzz() { ... }
+ *  }
+ * }
+ * </pre><br>
+ * <p>
+ * Example 2 (Java with Reactor framework):
+ * <pre>
+ * {@code
+ *  class NonBlockingExampleService {
+ *      private static final @NonBlockingExecutor Scheduler operationsScheduler =
+ *              Schedulers.newParallel("parallel");
+ *
+ *      public Flux<String> foo(Flux<String> urls) {
+ *          return urls.publishOn(operationsScheduler)
+ *                  .filter(url -> blockingBuzz(url) != null);  // IDE warning: `Possibly blocking call in non-blocking context`
+ *      }
+ *
+ *      @Blocking
+ *      private String blockingBuzz(String url) { ... }
+ *  }
+ * }
+ * </pre>
+ * <p>
+ *  @see Blocking
+ *  @see NonBlocking
+ */
+@Documented
+@Retention(RetentionPolicy.CLASS)
+@Target({ElementType.TYPE, ElementType.TYPE_USE})
+public @interface NonBlockingExecutor {
+}