Java tutorial
/* * Copyright (C) 2008 The Android Open Source Project * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ package android.os; import android.annotation.UnsupportedAppUsage; import android.system.ErrnoException; import java.io.FileDescriptor; import java.io.IOException; import java.io.InputStream; import java.io.OutputStream; import java.nio.ByteBuffer; /** * MemoryFile is a wrapper for {@link SharedMemory} which can optionally be set to purgeable. * * Applications should generally prefer to use {@link SharedMemory} which offers more flexible * access & control over the shared memory region than MemoryFile does. * * Purgeable files may have their contents reclaimed by the kernel * in low memory conditions (only if allowPurging is set to true). * After a file is purged, attempts to read or write the file will * cause an IOException to be thrown. */ public class MemoryFile { private static String TAG = "MemoryFile"; // Returns 'true' if purged, 'false' otherwise @UnsupportedAppUsage private static native boolean native_pin(FileDescriptor fd, boolean pin) throws IOException; @UnsupportedAppUsage private static native int native_get_size(FileDescriptor fd) throws IOException; private SharedMemory mSharedMemory; private ByteBuffer mMapping; private boolean mAllowPurging = false; // true if our ashmem region is unpinned /** * Allocates a new ashmem region. The region is initially not purgable. * * @param name optional name for the file (can be null). * @param length of the memory file in bytes, must be positive. * @throws IOException if the memory file could not be created. */ public MemoryFile(String name, int length) throws IOException { try { mSharedMemory = SharedMemory.create(name, length); mMapping = mSharedMemory.mapReadWrite(); } catch (ErrnoException ex) { ex.rethrowAsIOException(); } } /** * Closes the memory file. If there are no other open references to the memory * file, it will be deleted. */ public void close() { deactivate(); mSharedMemory.close(); } /** * Unmaps the memory file from the process's memory space, but does not close it. * After this method has been called, read and write operations through this object * will fail, but {@link #getFileDescriptor()} will still return a valid file descriptor. * * @hide */ @UnsupportedAppUsage void deactivate() { if (mMapping != null) { SharedMemory.unmap(mMapping); mMapping = null; } } private void checkActive() throws IOException { if (mMapping == null) { throw new IOException("MemoryFile has been deactivated"); } } private void beginAccess() throws IOException { checkActive(); if (mAllowPurging) { if (native_pin(mSharedMemory.getFileDescriptor(), true)) { throw new IOException("MemoryFile has been purged"); } } } private void endAccess() throws IOException { if (mAllowPurging) { native_pin(mSharedMemory.getFileDescriptor(), false); } } /** * Returns the length of the memory file. * * @return file length. */ public int length() { return mSharedMemory.getSize(); } /** * Is memory file purging enabled? * * @return true if the file may be purged. * * @deprecated Purgable is considered generally fragile and hard to use safely. Applications * are recommend to instead use {@link android.content.ComponentCallbacks2#onTrimMemory(int)} * to react to memory events and release shared memory regions as appropriate. */ @Deprecated public boolean isPurgingAllowed() { return mAllowPurging; } /** * Enables or disables purging of the memory file. * * @param allowPurging true if the operating system can purge the contents * of the file in low memory situations * @return previous value of allowPurging * * @deprecated Purgable is considered generally fragile and hard to use safely. Applications * are recommend to instead use {@link android.content.ComponentCallbacks2#onTrimMemory(int)} * to react to memory events and release shared memory regions as appropriate. */ @Deprecated synchronized public boolean allowPurging(boolean allowPurging) throws IOException { boolean oldValue = mAllowPurging; if (oldValue != allowPurging) { native_pin(mSharedMemory.getFileDescriptor(), !allowPurging); mAllowPurging = allowPurging; } return oldValue; } /** * Creates a new InputStream for reading from the memory file. * @return InputStream */ public InputStream getInputStream() { return new MemoryInputStream(); } /** * Creates a new OutputStream for writing to the memory file. * @return OutputStream */ public OutputStream getOutputStream() { return new MemoryOutputStream(); } /** * Reads bytes from the memory file. * Will throw an IOException if the file has been purged. * * @param buffer byte array to read bytes into. * @param srcOffset offset into the memory file to read from. * @param destOffset offset into the byte array buffer to read into. * @param count number of bytes to read. * @return number of bytes read. * @throws IOException if the memory file has been purged or deactivated. */ public int readBytes(byte[] buffer, int srcOffset, int destOffset, int count) throws IOException { beginAccess(); try { mMapping.position(srcOffset); mMapping.get(buffer, destOffset, count); } finally { endAccess(); } return count; } /** * Write bytes to the memory file. * Will throw an IOException if the file has been purged. * * @param buffer byte array to write bytes from. * @param srcOffset offset into the byte array buffer to write from. * @param destOffset offset into the memory file to write to. * @param count number of bytes to write. * @throws IOException if the memory file has been purged or deactivated. */ public void writeBytes(byte[] buffer, int srcOffset, int destOffset, int count) throws IOException { beginAccess(); try { mMapping.position(destOffset); mMapping.put(buffer, srcOffset, count); } finally { endAccess(); } } /** * Gets a FileDescriptor for the memory file. * * The returned file descriptor is not duplicated. * * @throws IOException If the memory file has been closed. * * @hide */ @UnsupportedAppUsage public FileDescriptor getFileDescriptor() throws IOException { return mSharedMemory.getFileDescriptor(); } /** * Returns the size of the memory file that the file descriptor refers to, * or -1 if the file descriptor does not refer to a memory file. * * @throws IOException If <code>fd</code> is not a valid file descriptor. * * @hide */ @UnsupportedAppUsage public static int getSize(FileDescriptor fd) throws IOException { return native_get_size(fd); } private class MemoryInputStream extends InputStream { private int mMark = 0; private int mOffset = 0; private byte[] mSingleByte; @Override public int available() throws IOException { if (mOffset >= mSharedMemory.getSize()) { return 0; } return mSharedMemory.getSize() - mOffset; } @Override public boolean markSupported() { return true; } @Override public void mark(int readlimit) { mMark = mOffset; } @Override public void reset() throws IOException { mOffset = mMark; } @Override public int read() throws IOException { if (mSingleByte == null) { mSingleByte = new byte[1]; } int result = read(mSingleByte, 0, 1); if (result != 1) { return -1; } return mSingleByte[0]; } @Override public int read(byte buffer[], int offset, int count) throws IOException { if (offset < 0 || count < 0 || offset + count > buffer.length) { // readBytes() also does this check, but we need to do it before // changing count. throw new IndexOutOfBoundsException(); } count = Math.min(count, available()); if (count < 1) { return -1; } int result = readBytes(buffer, mOffset, offset, count); if (result > 0) { mOffset += result; } return result; } @Override public long skip(long n) throws IOException { if (mOffset + n > mSharedMemory.getSize()) { n = mSharedMemory.getSize() - mOffset; } mOffset += n; return n; } } private class MemoryOutputStream extends OutputStream { private int mOffset = 0; private byte[] mSingleByte; @Override public void write(byte buffer[], int offset, int count) throws IOException { writeBytes(buffer, offset, mOffset, count); mOffset += count; } @Override public void write(int oneByte) throws IOException { if (mSingleByte == null) { mSingleByte = new byte[1]; } mSingleByte[0] = (byte) oneByte; write(mSingleByte, 0, 1); } } }