Snap for 7489879 from 716086b0971e19671204ca17392ab591002ab221 to sc-v2-release
Change-Id: I84cb7a811b1cebbec948ea1757d4555c11a3e5d8
diff --git a/NativeCode.bp b/NativeCode.bp
index 18a8abc..a7f18ea 100644
--- a/NativeCode.bp
+++ b/NativeCode.bp
@@ -52,6 +52,7 @@
name: "libjavacore",
visibility: [
"//art/build/apex",
+ "//art/runtime",
],
apex_available: [
"com.android.art",
diff --git a/libart/src/main/java/dalvik/system/VMStack.java b/libart/src/main/java/dalvik/system/VMStack.java
index 89ce215..bad912b 100644
--- a/libart/src/main/java/dalvik/system/VMStack.java
+++ b/libart/src/main/java/dalvik/system/VMStack.java
@@ -40,6 +40,8 @@
* @deprecated Use {@code ClassLoader.getClassLoader(sun.reflect.Reflection.getCallerClass())}.
* Note that that can return {@link BootClassLoader} on Android where the RI
* would have returned null.
+ *
+ * @hide
*/
@UnsupportedAppUsage
@FastNative
@@ -51,6 +53,8 @@
*
* @return the requested class, or {@code null}.
* @deprecated Use {@link sun.reflect.Reflection#getCallerClass()}.
+ *
+ * @hide
*/
@Deprecated
public static Class<?> getStackClass1() {
@@ -61,6 +65,8 @@
* Returns the class of the caller's caller's caller.
*
* @return the requested class, or {@code null}.
+ *
+ * @hide
*/
@UnsupportedAppUsage
@FastNative
@@ -69,6 +75,8 @@
/**
* Returns the first ClassLoader on the call stack that isn't the
* bootstrap class loader.
+ *
+ * @hide
*/
@FastNative
public native static ClassLoader getClosestUserClassLoader();
@@ -80,6 +88,8 @@
* thread of interest
* @return an array of stack trace elements, or null if the thread
* doesn't have a stack trace (e.g. because it exited)
+ *
+ * @hide
*/
@UnsupportedAppUsage
@FastNative
@@ -92,6 +102,8 @@
* thread of interest
* @return an array of annotated stack frames, or null if the thread
* doesn't have a stack trace (e.g. because it exited)
+ *
+ * @hide
*/
@libcore.api.CorePlatformApi
@FastNative
@@ -108,6 +120,8 @@
* preallocated array for use when only the top of stack is
* desired. Unused elements will be filled with null values.
* @return the number of elements filled
+ *
+ * @hide
*/
@UnsupportedAppUsage
@FastNative
diff --git a/luni/src/main/java/android/system/StructLinger.java b/luni/src/main/java/android/system/StructLinger.java
index 6726d59..2a29fc0 100644
--- a/luni/src/main/java/android/system/StructLinger.java
+++ b/luni/src/main/java/android/system/StructLinger.java
@@ -31,17 +31,25 @@
* See <a href="https://man7.org/linux/man-pages/man7/socket.7.html">socket(7)</a>
* for linger struct description.
*
- * @see {@link Os.getsockoptLinger(java.io.FileDescriptor, int, int)}.
- * @see {@link OsConstants.SO_LINGER}.
+ * @see Os#getsockoptLinger(java.io.FileDescriptor, int, int).
+ * @see OsConstants#SO_LINGER
*
* @hide
*/
@libcore.api.CorePlatformApi(status = libcore.api.CorePlatformApi.Status.STABLE)
public final class StructLinger {
- /** Whether or not linger is enabled. Non-zero is on. */
+ /**
+ * Whether or not linger is enabled. Non-zero is on.
+ *
+ * @hide
+ */
public final int l_onoff;
- /** Linger time in seconds. */
+ /**
+ * Linger time in seconds.
+ *
+ * @hide
+ */
@libcore.api.CorePlatformApi(status = libcore.api.CorePlatformApi.Status.STABLE)
public final int l_linger;
@@ -50,6 +58,8 @@
*
* @param l_onoff whether or not linger is enabled, non-zero is on
* @param l_linger linger time, in seconds
+ *
+ * @hide
*/
@libcore.api.CorePlatformApi(status = libcore.api.CorePlatformApi.Status.STABLE)
public StructLinger(int l_onoff, int l_linger) {
@@ -61,13 +71,19 @@
* Returns whether linger is on or not.
*
* @return {@code true} if linger is enabled, and {@code false} otherwise
+ *
+ * @hide
*/
@libcore.api.CorePlatformApi(status = libcore.api.CorePlatformApi.Status.STABLE)
public boolean isOn() {
return l_onoff != 0;
}
- @Override public String toString() {
+ /**
+ * @hide
+ */
+ @Override
+ public String toString() {
return Objects.toString(this);
}
}
diff --git a/luni/src/main/java/libcore/io/IoBridge.java b/luni/src/main/java/libcore/io/IoBridge.java
index 7d4ca81..8341bf5 100644
--- a/luni/src/main/java/libcore/io/IoBridge.java
+++ b/luni/src/main/java/libcore/io/IoBridge.java
@@ -16,6 +16,7 @@
package libcore.io;
+import android.annotation.SystemApi;
import android.compat.annotation.UnsupportedAppUsage;
import android.system.ErrnoException;
import android.system.StructGroupReq;
@@ -36,6 +37,7 @@
import java.net.NetworkInterface;
import java.net.NoRouteToHostException;
import java.net.PortUnreachableException;
+import java.net.Socket;
import java.net.SocketAddress;
import java.net.SocketException;
import java.net.SocketOptions;
@@ -43,12 +45,50 @@
import java.net.UnknownHostException;
import java.nio.ByteBuffer;
import java.util.concurrent.TimeUnit;
+
import libcore.util.ArrayUtils;
+import static android.annotation.SystemApi.Client.MODULE_LIBRARIES;
import static android.system.OsConstants.*;
/**
- * Implements java.io/java.net/java.nio semantics in terms of the underlying POSIX system calls.
+ * Collection of utility methods to work with blocking and non-blocking I/O that wrap raw POSIX
+ * system calls, e.g. {@link android.system.Os}. These wrappers are to signal other blocked I/O
+ * threads and avoid boilerplate code of routine error checks when using raw system calls.
+ *
+ * <p>
+ * For example, when using {@link Os#read(FileDescriptor, byte[], int, int)}, return value can
+ * contain:
+ * <ul>
+ * <li>{@code 0} which means EOF</li>
+ * <li>{@code N > 0} which means number of bytes read</li>
+ * <li>{@code -1} which means error, and {@link ErrnoException} is thrown</li>
+ * </ul>
+ *
+ * <p>
+ * {@link ErrnoException} in its turn can be one of:
+ * <ul>
+ * <li>{@link android.system.OsConstants#EAGAIN} which means the file descriptor refers to a file
+ * or a socket, which has been marked nonblocking
+ * ({@link android.system.OsConstants#O_NONBLOCK}), and the read would block</li>
+ * <li>{@link android.system.OsConstants#EBADF} which means the file descriptor is not a valid
+ * file descriptor or is not open for reading</li>
+ * <li>{@link android.system.OsConstants#EFAULT} which means given buffer is outside accessible
+ * address space</li>
+ * <li>{@link android.system.OsConstants#EINTR} which means the call was interrupted by a signal
+ * before any data was read</li>
+ * <li>{@link android.system.OsConstants#EINVAL} which means the file descriptor is attached to
+ * an object which is unsuitable for reading; or the file was opened with the
+ * {@link android.system.OsConstants#O_DIRECT} flag, and either the address specified in
+ * {@code buffer}, the value specified in {@code count}, or the file {@code offset} is not
+ * suitably aligned</li>
+ * <li>{@link android.system.OsConstants#EIO} which means I/O error happened</li>
+ * <li>{@link android.system.OsConstants#EISDIR} which means the file descriptor refers to a
+ * directory</li>
+ * </ul>
+ *
+ * All these errors require handling, and this class contains some wrapper methods that handle most
+ * common cases, making usage of system calls more user friendly.
*
* @hide
*/
@@ -58,6 +98,7 @@
private IoBridge() {
}
+ /** @hide */
public static int available(FileDescriptor fd) throws IOException {
try {
int available = Libcore.os.ioctlInt(fd, FIONREAD);
@@ -80,7 +121,7 @@
}
}
-
+ /** @hide */
public static void bind(FileDescriptor fd, InetAddress address, int port) throws SocketException {
if (address instanceof Inet6Address) {
Inet6Address inet6Address = (Inet6Address) address;
@@ -114,6 +155,8 @@
/**
* Connects socket 'fd' to 'inetAddress' on 'port', with no timeout. The lack of a timeout
* means this method won't throw SocketTimeoutException.
+ *
+ * @hide
*/
public static void connect(FileDescriptor fd, InetAddress inetAddress, int port) throws SocketException {
try {
@@ -126,6 +169,8 @@
/**
* Connects socket 'fd' to 'inetAddress' on 'port', with a the given 'timeoutMs'.
* Use timeoutMs == 0 for a blocking connect with no timeout.
+ *
+ * @hide
*/
public static void connect(FileDescriptor fd, InetAddress inetAddress, int port, int timeoutMs) throws SocketException, SocketTimeoutException {
try {
@@ -193,6 +238,8 @@
/**
* Constructs the message for an exception that the caller is about to throw.
+ *
+ * @hide
*/
private static String createMessageForException(FileDescriptor fd, InetAddress inetAddress,
int port, int timeoutMs, Exception causeOrNull) {
@@ -233,10 +280,15 @@
* Closes the Unix file descriptor associated with the supplied file descriptor, resets the
* internal int to -1, and sends a signal to any threads are currently blocking. In order for
* the signal to be sent the blocked threads must have registered with the
- * AsynchronousCloseMonitor before they entered the blocking operation. {@code fd} will be
+ * {@link AsynchronousCloseMonitor} before they entered the blocking operation. {@code fd} will be
* invalid after this call.
*
* <p>This method is a no-op if passed a {@code null} or already-closed file descriptor.
+ *
+ * @param fd file descriptor to be closed
+ * @throws IOException if underlying system call fails with {@link ErrnoException}
+ *
+ * @hide
*/
@libcore.api.CorePlatformApi
public static void closeAndSignalBlockedThreads(FileDescriptor fd) throws IOException {
@@ -260,6 +312,7 @@
}
}
+ /** @hide */
@UnsupportedAppUsage
public static boolean isConnected(FileDescriptor fd, InetAddress inetAddress, int port,
int timeoutMs, int remainingTimeoutMs) throws IOException {
@@ -293,14 +346,19 @@
}
// Socket options used by java.net but not exposed in SocketOptions.
+ /** @hide */
public static final int JAVA_MCAST_JOIN_GROUP = 19;
+ /** @hide */
public static final int JAVA_MCAST_LEAVE_GROUP = 20;
+ /** @hide */
public static final int JAVA_IP_MULTICAST_TTL = 17;
+ /** @hide */
public static final int JAVA_IP_TTL = 25;
/**
* java.net has its own socket options similar to the underlying Unix ones. We paper over the
* differences here.
+ * @hide
*/
public static Object getSocketOption(FileDescriptor fd, int option) throws SocketException {
try {
@@ -373,6 +431,8 @@
/**
* java.net has its own socket options similar to the underlying Unix ones. We paper over the
* differences here.
+ *
+ * @hide
*/
public static void setSocketOption(FileDescriptor fd, int option, Object value) throws SocketException {
try {
@@ -472,9 +532,22 @@
}
/**
- * java.io only throws FileNotFoundException when opening files, regardless of what actually
- * went wrong. Additionally, java.io is more restrictive than POSIX when it comes to opening
- * directories: POSIX says read-only is okay, but java.io doesn't even allow that.
+ * Wrapper for {@link Os#open(String, int, int)} that behaves similar to {@link java.io.File}.
+ * When a {@link java.io.File} is opened and there is an error, it throws
+ * {@link java.io.FileNotFoundException} regardless of what went wrong, when POSIX
+ * {@link Os#open(String, int, int)} throws more grained exceptions of what went wrong.
+ *
+ * <p>Additionally, attempt to open directory using {@link java.io.File} is also error, however
+ * POSIX {@link Os#open(String, int, int)} for read-only directories is not error.
+ *
+ * @see <a href="https://man7.org/linux/man-pages/man2/open.2.html">open(2)</a>.
+ *
+ * @param path path of the file to be opened
+ * @param flags bitmask of the access, file creation and file status flags
+ * @return {@link FileDescriptor} of an opened file
+ * @throws FileNotFoundException if there was error opening file under {@code path}
+ *
+ * @hide
*/
@libcore.api.CorePlatformApi
public static FileDescriptor open(String path, int flags) throws FileNotFoundException {
@@ -501,8 +574,21 @@
}
/**
- * java.io thinks that a read at EOF is an error and should return -1, contrary to traditional
- * Unix practice where you'd read until you got 0 bytes (and any future read would return -1).
+ * Wrapper for {@link Os#read(FileDescriptor, byte[], int, int)} that behaves similar to
+ * {@link java.io.FileInputStream#read(byte[], int, int)} and
+ * {@link java.io.FileReader#read(char[], int, int)} which interpret reading at {@code EOF} as
+ * error, when POSIX system call returns {@code 0} (and future reads return {@code -1}).
+ *
+ * <p>@see <a href="https://man7.org/linux/man-pages/man2/read.2.html">read(2)</a>.
+ *
+ * @param fd file descriptor to read from
+ * @param bytes buffer to put data read from {@code fd}
+ * @param byteOffset offset in {@code bytes} buffer to put read data at
+ * @param byteCount number of bytes to read from {@code fd}
+ * @return number of bytes read, if read operation was successful
+ * @throws IOException if underlying system call returned error
+ *
+ * @hide
*/
@libcore.api.CorePlatformApi
public static int read(FileDescriptor fd, byte[] bytes, int byteOffset, int byteCount) throws IOException {
@@ -526,8 +612,24 @@
}
/**
- * java.io always writes every byte it's asked to, or fails with an error. (That is, unlike
- * Unix it never just writes as many bytes as happens to be convenient.)
+ * Wrapper for {@link Os#write(FileDescriptor, byte[], int, int)} that behaves similar to
+ * {@link java.io.FileOutputStream#write(byte[], int, int)} and
+ * {@link java.io.FileWriter#write(char[], int, int)} which always either write all requested
+ * bytes, or fail with error; as opposed to POSIX write, when the number of bytes written may
+ * be less than {@code bytes}. This may happen, for example, if there is insufficient space on
+ * the underlying physical medium, or the {@code RLIMIT_FSIZE} resource limit is encountered,
+ * or the call was interrupted by a signal handler after having written less than {@code bytes}
+ * bytes.
+ *
+ * <p>@see <a href="https://man7.org/linux/man-pages/man2/write.2.html">write(2)</a>.
+ *
+ * @param fd file descriptor to write to
+ * @param bytes buffer containing the data to be written
+ * @param byteOffset offset in {@code bytes} buffer to read written data from
+ * @param byteCount number of bytes to write to {@code fd}
+ * @throws IOException if underlying system call returned error
+ *
+ * @hide
*/
@libcore.api.CorePlatformApi
public static void write(FileDescriptor fd, byte[] bytes, int byteOffset, int byteCount) throws IOException {
@@ -546,6 +648,30 @@
}
}
+ /**
+ * Wrapper around {@link Os#sendto(FileDescriptor, byte[], int, int, int, InetAddress, int)}
+ * that allows sending data over both TCP and UDP socket; handles
+ * {@link android.system.OsConstants#EAGAIN} and {@link android.system.OsConstants#ECONNREFUSED}
+ * and behaves similar to and behaves similar to
+ * {@link java.net.DatagramSocket#send(DatagramPacket)} and
+ * {@link Socket#getOutputStream()#write(FileDescriptor, byte[], int, int)}.
+ *
+ * <p>See {@link android.system.OsConstants} for available flags.
+ *
+ * <p>@see <a href="https://man7.org/linux/man-pages/man2/send.2.html">send(2)</a>.
+ *
+ * @param fd {@link FileDescriptor} of the socket to send data over
+ * @param bytes byte buffer containing the data to be sent
+ * @param byteOffset offset in {@code bytes} at which data to be sent starts
+ * @param byteCount number of bytes to be sent
+ * @param flags bitwise OR of zero or more of flags, like {@link android.system.OsConstants#MSG_DONTROUTE}
+ * @param inetAddress destination address
+ * @param port destination port
+ * @return number of bytes sent on success
+ * @throws IOException if underlying system call returned error
+ *
+ * @hide
+ */
@libcore.api.CorePlatformApi
public static int sendto(FileDescriptor fd, byte[] bytes, int byteOffset, int byteCount, int flags, InetAddress inetAddress, int port) throws IOException {
boolean isDatagram = (inetAddress != null);
@@ -561,6 +687,7 @@
return result;
}
+ /** @hide */
public static int sendto(FileDescriptor fd, ByteBuffer buffer, int flags, InetAddress inetAddress, int port) throws IOException {
boolean isDatagram = (inetAddress != null);
if (!isDatagram && buffer.remaining() == 0) {
@@ -591,6 +718,31 @@
throw errnoException.rethrowAsIOException();
}
+ /**
+ * Wrapper around {@link Os#recvfrom(FileDescriptor, byte[], int, int, int, InetSocketAddress)}
+ * that receives a message from both TCP and UDP socket; handles
+ * {@link android.system.OsConstants#EAGAIN} and {@link android.system.OsConstants#ECONNREFUSED}
+ * and behaves similar to {@link java.net.DatagramSocket#receive(DatagramPacket)} and
+ * {@link Socket#getInputStream()#recvfrom(boolean, FileDescriptor, byte[], int, int, int, DatagramPacket, boolean)}.
+ *
+ * <p>If {@code packet} is not {@code null}, and the underlying protocol provides the source
+ * address of the message, that source address is placed in the {@code packet}.
+ *
+ * @see <a href="https://man7.org/linux/man-pages/man2/recv.2.html">recv(2)</a>.
+ *
+ * @param isRead {@code true} if some data been read already from {@code fd}
+ * @param fd socket to receive data from
+ * @param bytes buffer to put data read from {@code fd}
+ * @param byteOffset offset in {@code bytes} buffer to put read data at
+ * @param byteCount number of bytes to read from {@code fd}
+ * @param flags bitwise OR of zero or more of flags, like {@link android.system.OsConstants#MSG_DONTROUTE}
+ * @param packet {@link DatagramPacket} to fill with source address
+ * @param isConnected {@code true} if socket {@code fd} is connected
+ * @return number of bytes read, if read operation was successful
+ * @throws IOException if underlying system call returned error
+ *
+ * @hide
+ */
@libcore.api.CorePlatformApi
public static int recvfrom(boolean isRead, FileDescriptor fd, byte[] bytes, int byteOffset, int byteCount, int flags, DatagramPacket packet, boolean isConnected) throws IOException {
int result;
@@ -604,6 +756,7 @@
return result;
}
+ /** @hide */
public static int recvfrom(boolean isRead, FileDescriptor fd, ByteBuffer buffer, int flags, DatagramPacket packet, boolean isConnected) throws IOException {
int result;
try {
@@ -652,6 +805,33 @@
}
}
+ /**
+ * Creates an endpoint for communication and returns a file descriptor that refers
+ * to that endpoint.
+ *
+ * <p>The {@code domain} specifies a communication domain; this selects the protocol
+ * family which will be used for communication, e.g. {@link android.system.OsConstants#AF_UNIX}
+ * {@link android.system.OsConstants#AF_INET}.
+ *
+ * <p>The socket has the indicated type, which specifies the communication semantics,
+ * e.g. {@link android.system.OsConstants#SOCK_STREAM} or
+ * {@link android.system.OsConstants#SOCK_DGRAM}.
+ *
+ * <p>The protocol specifies a particular protocol to be used with the
+ * socket. Normally only a single protocol exists to support a
+ * particular socket type within a given protocol family, in which
+ * case protocol can be specified as {@code 0}.
+ *
+ * @see <a href="https://man7.org/linux/man-pages/man2/socket.2.html">socket(2)</a>.
+ *
+ * @param domain socket domain
+ * @param type socket type
+ * @param protocol socket protocol
+ * @return {@link FileDescriptor} of an opened socket
+ * @throws SocketException if underlying system call returned error
+ *
+ * @hide
+ */
@libcore.api.CorePlatformApi
public static FileDescriptor socket(int domain, int type, int protocol) throws SocketException {
FileDescriptor fd;
@@ -670,6 +850,8 @@
*
* @throws SocketException if poll(2) fails.
* @throws SocketTimeoutException if the event has not happened before timeout period has passed.
+ *
+ * @hide
*/
public static void poll(FileDescriptor fd, int events, int timeout)
throws SocketException, SocketTimeoutException {
@@ -688,7 +870,15 @@
}
/**
- * @throws SocketException if fd is not currently bound to an InetSocketAddress
+ * Returns the current address to which the socket {@code fd} is bound.
+ *
+ * @see <a href="https://man7.org/linux/man-pages/man2/getsockname.2.html">getsockname(2)</a>.
+ *
+ * @param fd socket to get the bounded address of
+ * @return current address to which the socket {@code fd} is bound
+ * @throws SocketException if {@code fd} is not currently bound to an {@link InetSocketAddress}
+ *
+ * @hide
*/
@libcore.api.CorePlatformApi
public static InetSocketAddress getLocalInetSocketAddress(FileDescriptor fd)
diff --git a/luni/src/main/java/libcore/util/EmptyArray.java b/luni/src/main/java/libcore/util/EmptyArray.java
index 0d1e321..a8936ea 100644
--- a/luni/src/main/java/libcore/util/EmptyArray.java
+++ b/luni/src/main/java/libcore/util/EmptyArray.java
@@ -19,40 +19,71 @@
import android.compat.annotation.UnsupportedAppUsage;
import dalvik.annotation.compat.VersionCodes;
-/** @hide */
+/**
+ * Empty array is immutable. Use a shared empty array to avoid allocation. Intended to be
+ * used by ART and libcore only.
+ *
+ * @hide
+ */
@libcore.api.CorePlatformApi
public final class EmptyArray {
private EmptyArray() {}
+ /** @hide */
@libcore.api.CorePlatformApi
public static final boolean[] BOOLEAN = new boolean[0];
+
+ /** @hide */
@UnsupportedAppUsage(maxTargetSdk=VersionCodes.Q,
publicAlternatives="Use {@code new byte[0]} instead.")
@libcore.api.CorePlatformApi
public static final byte[] BYTE = new byte[0];
+
+ /** @hide */
public static final char[] CHAR = new char[0];
+
+ /** @hide */
public static final double[] DOUBLE = new double[0];
+
+ /** @hide */
@libcore.api.CorePlatformApi
public static final float[] FLOAT = new float[0];
+
+ /** @hide */
@UnsupportedAppUsage(maxTargetSdk=VersionCodes.Q,
publicAlternatives="Use {@code new int[0]} instead.")
@libcore.api.CorePlatformApi
public static final int[] INT = new int[0];
+
+ /** @hide */
@UnsupportedAppUsage(maxTargetSdk=VersionCodes.Q,
publicAlternatives="Use {@code new long[0]} instead.")
@libcore.api.CorePlatformApi
public static final long[] LONG = new long[0];
+ /** @hide */
public static final Class<?>[] CLASS = new Class[0];
+
+ /** @hide */
@UnsupportedAppUsage(maxTargetSdk=VersionCodes.Q,
publicAlternatives="Use {@code new Object[0]} instead.")
@libcore.api.CorePlatformApi
public static final Object[] OBJECT = new Object[0];
+
+ /** @hide */
@libcore.api.CorePlatformApi
public static final String[] STRING = new String[0];
+
+ /** @hide */
public static final Throwable[] THROWABLE = new Throwable[0];
+
+ /** @hide */
public static final StackTraceElement[] STACK_TRACE_ELEMENT = new StackTraceElement[0];
+
+ /** @hide */
public static final java.lang.reflect.Type[] TYPE = new java.lang.reflect.Type[0];
+
+ /** @hide */
public static final java.lang.reflect.TypeVariable[] TYPE_VARIABLE =
new java.lang.reflect.TypeVariable[0];
}