Loading

android.os
Class MemoryFile

java.lang.Object
  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.