ExperimentalForeignApi

Marks foreign-language-related API as experimental.

Foreign API includes all operations and classifiers that are required for operating with unmanaged and foreign memory, including but not limited to such declarations as CPointer, CPointed, StableRef, and Pinned. It also includes API of C and Objective-C libraries, except for those that are available in Kotlin by default (like platform.posix.* or platform.Foundation.*).

Such API is considered experimental and has the following known limitations and caveats:

• It is either undocumented or lacks extensive and sound description.
• There is no clear behavioural semantics and explicit mapping between foreign (e.g. C-pointer) concepts and the corresponding foreign API (e.g. CPointer). Such declarations might have an unsound mapping.
• There is no clear semantic difference between similar declarations.
• It lacks best practices and cookbook-like recommendations.

ABI and API compatibilities are provided on a best-effort basis. We also do provide a best-effort migration path for binary/source incompatible changes, including the proper deprecation cycle, migration path, and introducing replacements for the API rather than API breakage.

This API is recommended to be used for interoperability purposes, but with the API availability scope confined and narrowed down.