Loading


android.os
Class MemoryFile

java.lang.Object
  extended by android.os.MemoryFile

public class MemoryFile
extends java.lang.Object

MemoryFile is a wrapper for the Linux ashmem driver. MemoryFiles are backed by shared memory, which can be optionally set to be purgeable. 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.


Constructor Summary
MemoryFile(java.io.FileDescriptor fd, int length, java.lang.String mode)
          Creates a reference to an existing memory file.
MemoryFile(java.lang.String name, int length)
          Allocates a new ashmem region.
 
Method Summary
 boolean allowPurging(boolean allowPurging)
          Enables or disables purging of the memory file.
 void close()
          Closes the memory file.
 void deactivate()
          Unmaps the memory file from the process's memory space, but does not close it.
protected  void finalize()
           
 java.io.FileDescriptor getFileDescriptor()
          Gets a FileDescriptor for the memory file.
 java.io.InputStream getInputStream()
          Creates a new InputStream for reading from the memory file.
 java.io.OutputStream getOutputStream()
          Creates a new OutputStream for writing to the memory file.
 ParcelFileDescriptor getParcelFileDescriptor()
          Gets a ParcelFileDescriptor for the memory file.
static int getSize(java.io.FileDescriptor fd)
          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.
static boolean isMemoryFile(java.io.FileDescriptor fd)
          Checks whether the given file descriptor refers to a memory file.
 boolean isPurgingAllowed()
          Is memory file purging enabled?
 int length()
          Returns the length of the memory file.
 int readBytes(byte[] buffer, int srcOffset, int destOffset, int count)
          Reads bytes from the memory file.
 void writeBytes(byte[] buffer, int srcOffset, int destOffset, int count)
          Write bytes to the memory file.
 
Methods inherited from class java.lang.Object
clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

MemoryFile

public MemoryFile(java.lang.String name,
                  int length)
           throws java.io.IOException
Allocates a new ashmem region. The region is initially not purgable.

Parameters:
name - optional name for the file (can be null).
length - of the memory file in bytes.
Throws:
java.io.IOException - if the memory file could not be created.

MemoryFile

public MemoryFile(java.io.FileDescriptor fd,
                  int length,
                  java.lang.String mode)
           throws java.io.IOException
Creates a reference to an existing memory file. Changes to the original file will be available through this reference. Calls to allowPurging(boolean) on the returned MemoryFile will fail.

Parameters:
fd - File descriptor for an existing memory file, as returned by getFileDescriptor(). This file descriptor will be closed by close().
length - Length of the memory file in bytes.
mode - File mode. Currently only "r" for read-only access is supported.
Throws:
java.lang.NullPointerException - if fd is null.
java.io.IOException - If fd does not refer to an existing memory file, or if the file mode of the existing memory file is more restrictive than mode.
Method Detail

close

public void close()
Closes the memory file. If there are no other open references to the memory file, it will be deleted.


deactivate

public void deactivate()
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 getFileDescriptor() will still return a valid file descriptor.


finalize

protected void finalize()
Overrides:
finalize in class java.lang.Object

length

public int length()
Returns the length of the memory file.

Returns:
file length.

isPurgingAllowed

public boolean isPurgingAllowed()
Is memory file purging enabled?

Returns:
true if the file may be purged.

allowPurging

public boolean allowPurging(boolean allowPurging)
                     throws java.io.IOException
Enables or disables purging of the memory file.

Parameters:
allowPurging - true if the operating system can purge the contents of the file in low memory situations
Returns:
previous value of allowPurging
Throws:
java.io.IOException

getInputStream

public java.io.InputStream getInputStream()
Creates a new InputStream for reading from the memory file.

Returns:
InputStream

getOutputStream

public java.io.OutputStream getOutputStream()
Creates a new OutputStream for writing to the memory file.

Returns:
OutputStream

readBytes

public int readBytes(byte[] buffer,
                     int srcOffset,
                     int destOffset,
                     int count)
              throws java.io.IOException
Reads bytes from the memory file. Will throw an IOException if the file has been purged.

Parameters:
buffer - byte array to read bytes into.
srcOffset - offset into the memory file to read from.
destOffset - offset into the byte array buffer to read into.
count - number of bytes to read.
Returns:
number of bytes read.
Throws:
java.io.IOException - if the memory file has been purged or deactivated.

writeBytes

public void writeBytes(byte[] buffer,
                       int srcOffset,
                       int destOffset,
                       int count)
                throws java.io.IOException
Write bytes to the memory file. Will throw an IOException if the file has been purged.

Parameters:
buffer - byte array to write bytes from.
srcOffset - offset into the byte array buffer to write from.
destOffset - offset into the memory file to write to.
count - number of bytes to write.
Throws:
java.io.IOException - if the memory file has been purged or deactivated.

getParcelFileDescriptor

public ParcelFileDescriptor getParcelFileDescriptor()
                                             throws java.io.IOException
Gets a ParcelFileDescriptor for the memory file. See getFileDescriptor() for caveats. This must be here to allow classes outside android.osParcelFileDescriptor.ParcelFileDescriptor(FileDescriptor) is package private.

Returns:
The file descriptor owned by this memory file object. The file descriptor is not duplicated.
Throws:
java.io.IOException - If the memory file has been closed.

getFileDescriptor

public java.io.FileDescriptor getFileDescriptor()
                                         throws java.io.IOException
Gets a FileDescriptor for the memory file. Note that this file descriptor is only safe to pass to #MemoryFile(FileDescriptor,int)). It should not be used with file descriptor operations that expect a file descriptor for a normal file. The returned file descriptor is not duplicated.

Throws:
java.io.IOException - If the memory file has been closed.

isMemoryFile

public static boolean isMemoryFile(java.io.FileDescriptor fd)
                            throws java.io.IOException
Checks whether the given file descriptor refers to a memory file.

Throws:
java.io.IOException - If fd is not a valid file descriptor.

getSize

public static int getSize(java.io.FileDescriptor fd)
                   throws java.io.IOException
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:
java.io.IOException - If fd is not a valid file descriptor.