1 /* 2 * Copyright 2016-2020 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license. 3 */ 4 5 package kotlinx.coroutines 6 7 import kotlinx.coroutines.flow.* 8 9 /** 10 * Marks declarations that are still **experimental** in coroutines API, which means that the design of the 11 * corresponding declarations has open issues which may (or may not) lead to their changes in the future. 12 * Roughly speaking, there is a chance that those declarations will be deprecated in the near future or 13 * the semantics of their behavior may change in some way that may break some code. 14 */ 15 @MustBeDocumented 16 @Retention(value = AnnotationRetention.BINARY) 17 @RequiresOptIn(level = RequiresOptIn.Level.WARNING) 18 public annotation class ExperimentalCoroutinesApi 19 20 /** 21 * Marks [Flow]-related API as a feature preview. 22 * 23 * Flow preview has **no** backward compatibility guarantees, including both binary and source compatibility. 24 * Its API and semantics can and will be changed in next releases. 25 * 26 * Feature preview can be used to evaluate its real-world strengths and weaknesses, gather and provide feedback. 27 * According to the feedback, [Flow] will be refined on its road to stabilization and promotion to a stable API. 28 * 29 * The best way to speed up preview feature promotion is providing the feedback on the feature. 30 */ 31 @MustBeDocumented 32 @Retention(value = AnnotationRetention.BINARY) 33 @RequiresOptIn( 34 level = RequiresOptIn.Level.WARNING, 35 message = "This declaration is in a preview state and can be changed in a backwards-incompatible manner with a best-effort migration. " + 36 "Its usage should be marked with '@kotlinx.coroutines.FlowPreview' or '@OptIn(kotlinx.coroutines.FlowPreview::class)' " + 37 "if you accept the drawback of relying on preview API" 38 ) 39 @Target(AnnotationTarget.CLASS, AnnotationTarget.FUNCTION, AnnotationTarget.TYPEALIAS, AnnotationTarget.PROPERTY) 40 public annotation class FlowPreview 41 42 /** 43 * Marks declarations that are **obsolete** in coroutines API, which means that the design of the corresponding 44 * declarations has serious known flaws and they will be redesigned in the future. 45 * Roughly speaking, these declarations will be deprecated in the future but there is no replacement for them yet, 46 * so they cannot be deprecated right away. 47 */ 48 @MustBeDocumented 49 @Retention(value = AnnotationRetention.BINARY) 50 @RequiresOptIn(level = RequiresOptIn.Level.WARNING) 51 public annotation class ObsoleteCoroutinesApi 52 53 /** 54 * Marks declarations that are **internal** in coroutines API, which means that should not be used outside of 55 * `kotlinx.coroutines`, because their signatures and semantics will change between future releases without any 56 * warnings and without providing any migration aids. 57 */ 58 @Retention(value = AnnotationRetention.BINARY) 59 @Target(AnnotationTarget.CLASS, AnnotationTarget.FUNCTION, AnnotationTarget.TYPEALIAS, AnnotationTarget.PROPERTY) 60 @RequiresOptIn( 61 level = RequiresOptIn.Level.ERROR, message = "This is an internal kotlinx.coroutines API that " + 62 "should not be used from outside of kotlinx.coroutines. No compatibility guarantees are provided." + 63 "It is recommended to report your use-case of internal API to kotlinx.coroutines issue tracker, " + 64 "so stable API could be provided instead" 65 ) 66 public annotation class InternalCoroutinesApi 67