core/java/android/util/MemoryIntArray.java

   1 /*
   2  * Copyright (C) 2016 The Android Open Source Project
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the "License");
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at
   7  *
   8  *      http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an "AS IS" BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16
  17 package android.util;
  18
  19 import android.os.Parcel;
  20 import android.os.ParcelFileDescriptor;
  21 import android.os.Parcelable;
  22 import android.os.Process;
  23
  24 import java.io.Closeable;
  25 import java.io.IOException;
  26 import java.util.UUID;
  27
  28 /**
  29  * This class is an array of integers that is backed by shared memory.
  30  * It is useful for efficiently sharing state between processes. The
  31  * write and read operations are guaranteed to not result in read/
  32  * write memory tear, i.e. they are atomic. However, multiple read/
  33  * write operations are <strong>not</strong> synchronized between
  34  * each other.
  35  * <p>
  36  * The data structure is designed to have one owner process that can
  37  * read/write. There may be multiple client processes that can only read or
  38  * read/write depending how the data structure was configured when
  39  * instantiated. The owner process is the process that created the array.
  40  * The shared memory is pinned (not reclaimed by the system) until the
  41  * owning process dies or the data structure is closed. This class
  42  * is <strong>not</strong> thread safe. You should not interact with
  43  * an instance of this class once it is closed.
  44  * </p>
  45  *
  46  * @hide
  47  */
  48 public final class MemoryIntArray implements Parcelable, Closeable {
  49     private static final int MAX_SIZE = 1024;
  50
  51     private final int mOwnerPid;
  52     private final boolean mClientWritable;
  53     private final long mMemoryAddr;
  54     private ParcelFileDescriptor mFd;
  55
  56     /**
  57      * Creates a new instance.
  58      *
  59      * @param size The size of the array in terms of integer slots. Cannot be
  60      *     more than {@link #getMaxSize()}.
  61      * @param clientWritable Whether other processes can write to the array.
  62      * @throws IOException If an error occurs while accessing the shared memory.
  63      */
  64     public MemoryIntArray(int size, boolean clientWritable) throws IOException {
  65         if (size > MAX_SIZE) {
  66             throw new IllegalArgumentException("Max size is " + MAX_SIZE);
  67         }
  68         mOwnerPid = Process.myPid();
  69         mClientWritable = clientWritable;
  70         final String name = UUID.randomUUID().toString();
  71         mFd = ParcelFileDescriptor.fromFd(nativeCreate(name, size));
  72         mMemoryAddr = nativeOpen(mFd.getFd(), true, clientWritable);
  73     }
  74
  75     private MemoryIntArray(Parcel parcel) throws IOException {
  76         mOwnerPid = parcel.readInt();
  77         mClientWritable = (parcel.readInt() == 1);
  78         mFd = parcel.readParcelable(null);
  79         if (mFd == null) {
  80             throw new IOException("No backing file descriptor");
  81         }
  82         final long memoryAddress = parcel.readLong();
  83         if (isOwner()) {
  84             mMemoryAddr = memoryAddress;
  85         } else {
  86             mMemoryAddr = nativeOpen(mFd.getFd(), false, mClientWritable);
  87         }
  88     }
  89
  90     /**
  91      * @return Gets whether this array is mutable.
  92      */
  93     public boolean isWritable() {
  94         enforceNotClosed();
  95         return isOwner() || mClientWritable;
  96     }
  97
  98     /**
  99      * Gets the value at a given index.
 100      *
 101      * @param index The index.
 102      * @return The value at this index.
 103      * @throws IOException If an error occurs while accessing the shared memory.
 104      */
 105     public int get(int index) throws IOException {
 106         enforceNotClosed();
 107         enforceValidIndex(index);
 108         return nativeGet(mFd.getFd(), mMemoryAddr, index, isOwner());
 109     }
 110
 111     /**
 112      * Sets the value at a given index. This method can be called only if
 113      * {@link #isWritable()} returns true which means your process is the
 114      * owner.
 115      *
 116      * @param index The index.
 117      * @param value The value to set.
 118      * @throws IOException If an error occurs while accessing the shared memory.
 119      */
 120     public void set(int index, int value) throws IOException {
 121         enforceNotClosed();
 122         enforceWritable();
 123         enforceValidIndex(index);
 124         nativeSet(mFd.getFd(), mMemoryAddr, index, value, isOwner());
 125     }
 126
 127     /**
 128      * Gets the array size.
 129      *
 130      * @throws IOException If an error occurs while accessing the shared memory.
 131      */
 132     public int size() throws IOException {
 133         enforceNotClosed();
 134         return nativeSize(mFd.getFd());
 135     }
 136
 137     /**
 138      * Closes the array releasing resources.
 139      *
 140      * @throws IOException If an error occurs while accessing the shared memory.
 141      */
 142     @Override
 143     public void close() throws IOException {
 144         if (!isClosed()) {
 145             nativeClose(mFd.getFd(), mMemoryAddr, isOwner());
 146             mFd = null;
 147         }
 148     }
 149
 150     /**
 151      * @return Whether this array is closed and shouldn't be used.
 152      */
 153     public boolean isClosed() {
 154         return mFd == null;
 155     }
 156
 157     @Override
 158     protected void finalize() throws Throwable {
 159         close();
 160         super.finalize();
 161     }
 162
 163     @Override
 164     public int describeContents() {
 165         return CONTENTS_FILE_DESCRIPTOR;
 166     }
 167
 168     @Override
 169     public void writeToParcel(Parcel parcel, int flags) {
 170         parcel.writeInt(mOwnerPid);
 171         parcel.writeInt(mClientWritable ? 1 : 0);
 172         parcel.writeParcelable(mFd, 0);
 173         parcel.writeLong(mMemoryAddr);
 174     }
 175
 176     @Override
 177     public boolean equals(Object obj) {
 178         if (obj == null) {
 179             return false;
 180         }
 181         if (this == obj) {
 182             return true;
 183         }
 184         if (getClass() != obj.getClass()) {
 185             return false;
 186         }
 187         MemoryIntArray other = (MemoryIntArray) obj;
 188         if (mFd == null) {
 189             if (other.mFd != null) {
 190                 return false;
 191             }
 192         } else if (mFd.getFd() != other.mFd.getFd()) {
 193             return false;
 194         }
 195         return true;
 196     }
 197
 198     @Override
 199     public int hashCode() {
 200         return mFd != null ? mFd.hashCode() : 1;
 201     }
 202
 203     private boolean isOwner() {
 204         return mOwnerPid == Process.myPid();
 205     }
 206
 207     private void enforceNotClosed() {
 208         if (isClosed()) {
 209             throw new IllegalStateException("cannot interact with a closed instance");
 210         }
 211     }
 212
 213     private void enforceValidIndex(int index) throws IOException {
 214         final int size = size();
 215         if (index < 0 || index > size - 1) {
 216             throw new IndexOutOfBoundsException(
 217                     index + " not between 0 and " + (size - 1));
 218         }
 219     }
 220
 221     private void enforceWritable() {
 222         if (!isWritable()) {
 223             throw new UnsupportedOperationException("array is not writable");
 224         }
 225     }
 226
 227     private native int nativeCreate(String name, int size);
 228     private native long nativeOpen(int fd, boolean owner, boolean writable);
 229     private native void nativeClose(int fd, long memoryAddr, boolean owner);
 230     private native int nativeGet(int fd, long memoryAddr, int index, boolean owner);
 231     private native void nativeSet(int fd, long memoryAddr, int index, int value, boolean owner);
 232     private native int nativeSize(int fd);
 233     private native static int nativeGetMemoryPageSize();
 234
 235     /**
 236      * @return The max array size.
 237      */
 238     public static int getMaxSize() {
 239         return MAX_SIZE;
 240     }
 241
 242     public static final Parcelable.Creator<MemoryIntArray> CREATOR =
 243             new Parcelable.Creator<MemoryIntArray>() {
 244         @Override
 245         public MemoryIntArray createFromParcel(Parcel parcel) {
 246             try {
 247                 return new MemoryIntArray(parcel);
 248             } catch (IOException ioe) {
 249                 throw new RuntimeException(ioe);
 250             }
 251         }
 252
 253         @Override
 254         public MemoryIntArray[] newArray(int size) {
 255             return new MemoryIntArray[size];
 256         }
 257     };
 258 }