1 package kotlinx.coroutines 2 3 import kotlinx.coroutines.flow.* 4 5 /** 6 * Marks declarations in the coroutines that are **delicate** — 7 * they have limited use-case and shall be used with care in general code. 8 * Any use of a delicate declaration has to be carefully reviewed to make sure it is 9 * properly used and does not create problems like memory and resource leaks. 10 * Carefully read documentation of any declaration marked as `DelicateCoroutinesApi`. 11 */ 12 @MustBeDocumented 13 @Retention(value = AnnotationRetention.BINARY) 14 @RequiresOptIn( 15 level = RequiresOptIn.Level.WARNING, 16 message = "This is a delicate API and its use requires care." + 17 " Make sure you fully read and understand documentation of the declaration that is marked as a delicate API." 18 ) 19 public annotation class DelicateCoroutinesApi 20 21 /** 22 * Marks declarations that are still **experimental** in coroutines API, which means that the design of the 23 * corresponding declarations has open issues which may (or may not) lead to their changes in the future. 24 * Roughly speaking, there is a chance that those declarations will be deprecated in the near future or 25 * the semantics of their behavior may change in some way that may break some code. 26 */ 27 @MustBeDocumented 28 @Retention(value = AnnotationRetention.BINARY) 29 @Target( 30 AnnotationTarget.CLASS, 31 AnnotationTarget.ANNOTATION_CLASS, 32 AnnotationTarget.PROPERTY, 33 AnnotationTarget.FIELD, 34 AnnotationTarget.LOCAL_VARIABLE, 35 AnnotationTarget.VALUE_PARAMETER, 36 AnnotationTarget.CONSTRUCTOR, 37 AnnotationTarget.FUNCTION, 38 AnnotationTarget.PROPERTY_GETTER, 39 AnnotationTarget.PROPERTY_SETTER, 40 AnnotationTarget.TYPEALIAS 41 ) 42 @RequiresOptIn(level = RequiresOptIn.Level.WARNING) 43 public annotation class ExperimentalCoroutinesApi 44 45 /** 46 * Marks [Flow]-related API as a feature preview. 47 * 48 * Flow preview has **no** backward compatibility guarantees, including both binary and source compatibility. 49 * Its API and semantics can and will be changed in next releases. 50 * 51 * Feature preview can be used to evaluate its real-world strengths and weaknesses, gather and provide feedback. 52 * According to the feedback, [Flow] will be refined on its road to stabilization and promotion to a stable API. 53 * 54 * The best way to speed up preview feature promotion is providing the feedback on the feature. 55 */ 56 @MustBeDocumented 57 @Retention(value = AnnotationRetention.BINARY) 58 @RequiresOptIn( 59 level = RequiresOptIn.Level.WARNING, 60 message = "This declaration is in a preview state and can be changed in a backwards-incompatible manner with a best-effort migration. " + 61 "Its usage should be marked with '@kotlinx.coroutines.FlowPreview' or '@OptIn(kotlinx.coroutines.FlowPreview::class)' " + 62 "if you accept the drawback of relying on preview API" 63 ) 64 @Target(AnnotationTarget.CLASS, AnnotationTarget.FUNCTION, AnnotationTarget.TYPEALIAS, AnnotationTarget.PROPERTY) 65 public annotation class FlowPreview 66 67 /** 68 * Marks declarations that are **obsolete** in coroutines API, which means that the design of the corresponding 69 * declarations has serious known flaws and they will be redesigned in the future. 70 * Roughly speaking, these declarations will be deprecated in the future but there is no replacement for them yet, 71 * so they cannot be deprecated right away. 72 */ 73 @MustBeDocumented 74 @Retention(value = AnnotationRetention.BINARY) 75 @RequiresOptIn(level = RequiresOptIn.Level.WARNING) 76 public annotation class ObsoleteCoroutinesApi 77 78 /** 79 * Marks declarations that are **internal** in coroutines API, which means that should not be used outside of 80 * `kotlinx.coroutines`, because their signatures and semantics will change between future releases without any 81 * warnings and without providing any migration aids. 82 */ 83 @MustBeDocumented 84 @Retention(value = AnnotationRetention.BINARY) 85 @Target(AnnotationTarget.CLASS, AnnotationTarget.FUNCTION, AnnotationTarget.TYPEALIAS, AnnotationTarget.PROPERTY) 86 @RequiresOptIn( 87 level = RequiresOptIn.Level.ERROR, message = "This is an internal kotlinx.coroutines API that " + 88 "should not be used from outside of kotlinx.coroutines. No compatibility guarantees are provided. " + 89 "It is recommended to report your use-case of internal API to kotlinx.coroutines issue tracker, " + 90 "so stable API could be provided instead" 91 ) 92 public annotation class InternalCoroutinesApi 93 94 /** 95 * Marks declarations that cannot be safely inherited from. 96 */ 97 @Target(AnnotationTarget.CLASS) 98 @RequiresOptIn( 99 level = RequiresOptIn.Level.WARNING, message = 100 "Inheriting from this kotlinx.coroutines API is unstable. " + 101 "Either new methods may be added in the future, which would break the inheritance, " + 102 "or correctly inheriting from it requires fulfilling contracts that may change in the future." 103 ) 104 public annotation class ExperimentalForInheritanceCoroutinesApi 105 106 /** 107 * Marks declarations that cannot be safely inherited from. 108 */ 109 @Target(AnnotationTarget.CLASS) 110 @RequiresOptIn( 111 level = RequiresOptIn.Level.WARNING, message = 112 "This is a kotlinx.coroutines API that is not intended to be inherited from, " + 113 "as the library may handle predefined instances of this in a special manner. " + 114 "This will be an error in a future release. " + 115 "If you need to inherit from this, please describe your use case in " + 116 "https://github.com/Kotlin/kotlinx.coroutines/issues, so that we can provide a stable API for inheritance. " 117 ) 118 public annotation class InternalForInheritanceCoroutinesApi 119