summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorAndroid API Council <no-reply@android.com>2024-02-15 13:16:57 -0800
committerAndroid API Council <copybara-worker@google.com>2024-02-15 13:17:31 -0800
commit867a6bed2fe85a439039da60dcf2af0b88a3c10f (patch)
tree1e258b0d8d6ba865469e8793c9f37378c5acefbd
parent1efa6b5d603e36018713ffacb3665e9654243169 (diff)
downloaddocs-867a6bed2fe85a439039da60dcf2af0b88a3c10f.tar.gz
s/NDK/native/ for the cases that apply to other domains.
These rules were mostly written before we were responsible for the others, but many of these rules apply more broadly, and the title of the doc was misleading people into thinking the rules didn't apply to their non-NDK work. PiperOrigin-RevId: 607433144 Change-Id: Ia424c4bdfd233b5955c7ccc1d718ba7846ebb950
-rw-r--r--api-guidelines/ndk.md21
1 files changed, 10 insertions, 11 deletions
diff --git a/api-guidelines/ndk.md b/api-guidelines/ndk.md
index 00f7815..66fb6e0 100644
--- a/api-guidelines/ndk.md
+++ b/api-guidelines/ndk.md
@@ -1,6 +1,6 @@
-# Android NDK API Guidelines
+# Android NDK/Native API Guidelines
-Warning: NDK APIs do not support feature flagging.
+Warning: Native APIs do not support feature flagging.
[TOC]
@@ -68,7 +68,7 @@ Jetpack C++ APIs are exempt from this rule. See go/jetpack-cpp-guidelines
```
This C++ feature is provided for C as a Clang extension, so this should be
- be used even for NDK headers that must otherwise be C.
+ be used even for headers that must otherwise be C.
A rare exception to this rule will be made for interfaces defined by third-
parties (e.g. Vulkan or ICU) if upstream is not willing to depend on the
@@ -511,13 +511,13 @@ following exceptions:
## JNI <a name="jni"></a>
-### JNI interop methods should exclusively be in the NDK <a name="jni-ndk"></a>
+### JNI interop methods should exclusively be native APIs <a name="jni-ndk"></a>
-As in, always do `AObject_fromJava(JNIEnv, jobject)` in the NDK rather
-than having a `long Object#getNativePointer()` in the SDK.
+As in, always add `AObject_fromJava(JNIEnv, jobject)` to the native API surface
+rather than having a `long Object#getNativePointer()` in the SDK.
-Similarly do instead `jobject AObject_toJava(JNIEnv, AObject*)` in the
-NDK rather than `new Object(long nativePtr);` in the SDK.
+Similarly add `jobject AObject_toJava(JNIEnv, AObject*)` to the native API
+surface rather than `new Object(long nativePtr);` in the SDK.
If the native and Java types have the same name, the suffix should be just
`_fromJava` or `toJava`. If the type names differ, the Java type name should
@@ -539,9 +539,8 @@ Java object’s lifecycle should not be relevant to the native handle.
Similarly, if a Java object is created from a native object the native
object should not need to out-live the Java one.
-
-Typically this means both the NDK & Java types should sit on a ref-count system
-to handle this if the underlying instance is shared.
+Typically this means both the native & Java types should sit on a ref-count
+system to handle this if the underlying instance is shared.
If the interop just does a copy of the data (such as for a trivial type),
then nothing special needs to happen.