Skip to content

Most visited

Recently visited

navigation

SharedMemory

public final class SharedMemory
extends Object implements Parcelable, Closeable

java.lang.Object
   ↳ android.os.SharedMemory


SharedMemory enables the creation, mapping, and protection control over anonymous shared memory.

Summary

Inherited constants

From interface android.os.Parcelable

Fields

public static final Creator<SharedMemory> CREATOR

Public methods

void close()

Close the backing FileDescriptor of this SharedMemory instance.

static SharedMemory create(String name, int size)

Creates an anonymous SharedMemory instance with the provided debug name and size.

int describeContents()

Describe the kinds of special objects contained in this Parcelable instance's marshaled representation.

int getSize()
ByteBuffer map(int prot, int offset, int length)

Creates an mmap of the SharedMemory with the specified prot, offset, and length.

ByteBuffer mapReadOnly()

Creates a read-only mapping of the entire shared memory region.

ByteBuffer mapReadWrite()

Creates a read/write mapping of the entire shared memory region.

boolean setProtect(int prot)

Sets the protection on the shared memory to the combination specified in prot, which is either a bitwise-or'd combination of PROT_READ, PROT_WRITE, PROT_EXEC from OsConstants, or PROT_NONE, to remove all further access.

static void unmap(ByteBuffer buffer)

Unmaps a buffer previously returned by map(int, int, int).

void writeToParcel(Parcel dest, int flags)

Flatten this object in to a Parcel.

Inherited methods

From class java.lang.Object
From interface android.os.Parcelable
From interface java.io.Closeable
From interface java.lang.AutoCloseable

Fields

CREATOR

added in API level 27
Creator<SharedMemory> CREATOR

Public methods

close

added in API level 27
void close ()

Close the backing FileDescriptor of this SharedMemory instance. Note that all open mappings of the shared memory will remain valid and may continue to be used. The shared memory will not be freed until all file descriptor handles are closed and all memory mappings are unmapped.

create

added in API level 27
SharedMemory create (String name, 
                int size)

Creates an anonymous SharedMemory instance with the provided debug name and size. The name is only used for debugging purposes and can help identify what the shared memory is used for when inspecting memory maps for the processes that have mapped this SharedMemory instance.

Parameters
name String: The debug name to use for this SharedMemory instance. This can be null, however a debug name is recommended to help identify memory usage when using tools such as lsof or examining /proc/[pid]/maps

size int: The size of the shared memory to create. Must be greater than 0.

Returns
SharedMemory A SharedMemory instance of the requested size

This value will never be null.

Throws
ErrnoException if the requested allocation fails.

describeContents

added in API level 27
int describeContents ()

Describe the kinds of special objects contained in this Parcelable instance's marshaled representation. For example, if the object will include a file descriptor in the output of writeToParcel(Parcel, int), the return value of this method must include the CONTENTS_FILE_DESCRIPTOR bit.

Returns
int a bitmask indicating the set of special object types marshaled by this Parcelable object instance.

getSize

added in API level 27
int getSize ()

Returns
int The size of the SharedMemory region.

map

added in API level 27
ByteBuffer map (int prot, 
                int offset, 
                int length)

Creates an mmap of the SharedMemory with the specified prot, offset, and length. This will always produce a new ByteBuffer window to the backing shared memory region. Every call to map() may be paired with a call to unmap(ByteBuffer) when the ByteBuffer returned by map() is no longer needed.

Parameters
prot int: A bitwise-or'd combination of PROT_READ, PROT_WRITE, PROT_EXEC, or PROT_NONE.

offset int: The offset into the shared memory to begin mapping. Must be >= 0 and less than getSize().

length int: The length of the region to map. Must be > 0 and offset + length must not exceed getSize().

Returns
ByteBuffer A ByteBuffer mapping.

This value will never be null.

Throws
ErrnoException if the mmap call failed.

mapReadOnly

added in API level 27
ByteBuffer mapReadOnly ()

Creates a read-only mapping of the entire shared memory region. This requires the the protection level of the shared memory is at least PROT_READ or the map will fail. Use map(int, int, int) to have more control over the mapping if desired. This is equivalent to map(OsConstants.PROT_READ, 0, getSize())

Returns
ByteBuffer A ByteBuffer mapping

This value will never be null.

Throws
ErrnoException if the mmap call failed.

mapReadWrite

added in API level 27
ByteBuffer mapReadWrite ()

Creates a read/write mapping of the entire shared memory region. This requires the the protection level of the shared memory is at least PROT_READ|PROT_WRITE or the map will fail. Use map(int, int, int) to have more control over the mapping if desired. This is equivalent to map(OsConstants.PROT_READ | OsConstants.PROT_WRITE, 0, getSize())

Returns
ByteBuffer A ByteBuffer mapping

This value will never be null.

Throws
ErrnoException if the mmap call failed.

setProtect

added in API level 27
boolean setProtect (int prot)

Sets the protection on the shared memory to the combination specified in prot, which is either a bitwise-or'd combination of PROT_READ, PROT_WRITE, PROT_EXEC from OsConstants, or PROT_NONE, to remove all further access. Note that protection can only ever be removed, not added. By default shared memory is created with protection set to PROT_READ | PROT_WRITE | PROT_EXEC. The protection passed here also only applies to any mappings created after calling this method. Existing mmaps of the shared memory retain whatever protection they had when they were created. A common usage of this is to share a read-only copy of the data with something else. To do that first create the read/write mapping with PROT_READ | PROT_WRITE, then call setProtect(PROT_READ) to remove write capability, then send the SharedMemory to another process. That process will only be able to mmap with PROT_READ.

Parameters
prot int: Any bitwise-or'ed combination of PROT_READ, PROT_WRITE, and PROT_EXEC; or PROT_NONE

Returns
boolean Whether or not the requested protection was applied. Returns true on success, false if the requested protection was broader than the existing protection.

unmap

added in API level 27
void unmap (ByteBuffer buffer)

Unmaps a buffer previously returned by map(int, int, int). This will immediately release the backing memory of the ByteBuffer, invalidating all references to it. Only call this method if there are no duplicates of the ByteBuffer in use and don't access the ByteBuffer after calling this method.

Parameters
buffer ByteBuffer: The buffer to unmap

This value must never be null.

writeToParcel

added in API level 27
void writeToParcel (Parcel dest, 
                int flags)

Flatten this object in to a Parcel.

Parameters
dest Parcel: The Parcel in which the object should be written.

This value must never be null.

flags int: Additional flags about how the object should be written. May be 0 or PARCELABLE_WRITE_RETURN_VALUE.

This site uses cookies to store your preferences for site-specific language and display options.

Get the latest Android developer news and tips that will help you find success on Google Play.

* Required Fields

Hooray!

Follow Google Developers on WeChat

Browse this site in ?

You requested a page in , but your language preference for this site is .

Would you like to change your language preference and browse this site in ? If you want to change your language preference later, use the language menu at the bottom of each page.

This class requires API level or higher

This doc is hidden because your selected API level for the documentation is . You can change the documentation API level with the selector above the left navigation.

For more information about specifying the API level your app requires, read Supporting Different Platform Versions.

Take a short survey?
Help us improve the Android developer experience.
(Sep 2017 survey)