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