New coroutine builder convention API

core/builtins/native/kotlin/Coroutines.kt

@@ -17,18 +17,24 @@
 package kotlin.coroutines
 
 /**
- * This function allows to obtain a continuation instance inside the suspend functions.
- * As a suspend function may be only tail-called inside another suspend function, this call will be used as a return value of the latter one.
+ * This function allows to obtain the current continuation instance inside suspend functions and either suspend
+ * currently running  coroutine or return result immediately without suspension.
+ * This function can be used in a tail-call position as the return value of another suspend function.
  *
- * If the [body] returns the [Suspend] object, that means that suspend-function cannot return a value immediately,
- * i.e. it's literally suspends continuation, and the continuation will be resumed at some moment in the future.
+ * If the [body] returns the special [SUSPENDED_COMPUTATION] value, it means that suspend function did suspend the execution and will
+ * not return any result immediately. In this case, the [Continuation] provided to the [body] shall be invoked at some moment in the future when
+ * the result becomes available to resume the computation.
  *
- * Otherwise return value must have a type assignable to 'T'.
- * As the latter part cannot be correctly typechecked, it remains on the conscience of the suspend function's author.
- *
- * Note that it's not recommended to call a [Continuation] method in the same stackframe where suspension function is run,
- * they should be called asynchronously later (probably from the different thread).
+ * Otherwise, the return value of the [body] must have a type assignable to [T] and represents the result of this suspend function.
+ * It means that the execution was not suspended and the [Continuation] provided to the [body] shall not be invoked.
+ * As the result type of the [body] is declared as `Any?` and cannot be correctly type-checked,
+ * its proper return type remains on the conscience of the suspend function's author.
  *
+ * Note that it is not recommended to call either [Continuation.resume] nor [Continuation.resumeWithException] functions synchronously in
+ * the same stackframe where suspension function is run. They should be called asynchronously either later in the same thread or
+ * from a different thread of execution.
+ * Repeated invocation of any resume function on continuation produces unspecified behavior.
+ * Use [runWithCurrentContinuation] as a safer way to obtain current continuation instance.
  */
 @SinceKotlin("1.1")
-public inline suspend fun <T> suspendWithCurrentContinuation(body: (Continuation<T>) -> Any?): T
+public inline suspend fun <T> maySuspendWithCurrentContinuation(body: (Continuation<T>) -> Any?): T

core/builtins/src/kotlin/coroutines/Coroutines.kt

@@ -43,9 +43,16 @@ public interface Continuation<in P> {
 public annotation class AllowSuspendExtensions
 
 /**
- * This object can be used as a return value of [kotlin.coroutines.suspendWithCurrentContinuation] lambda-argument to state that
- * the continuation will be resumed at some moment in the future, that means that suspend-function cannot return a value immediately,
- * i.e. it's literally suspends continuation, so no stack-unwinding will be performed by the continuation.
+ * This value can be used as a return value of [kotlin.coroutines.maySuspendWithCurrentContinuation] `body` argument to state that
+ * the execution was suspended and will not return any result immediately.
  */
 @SinceKotlin("1.1")
-public object Suspend
+public val SUSPENDED: Any? = Any()
+
+/**
+ * Classes and interfaces marked with this annotation are restricted when used as receivers for extension
+ * `suspend` functions. These `suspend` extensions can only invoke other member or extension `suspend` functions on this parcitular
+ * receiver only and are restricted from calling arbitrary suspension functions.
+ */
+@SinceKotlin("1.1")
+public annotation class RestrictSuspension