SharedMemory
bookmark_borderbookmark
Stay organized with collections
Save and categorize content based on your preferences.
public
final
class
SharedMemory
extends Object
implements
Closeable,
Parcelable
SharedMemory enables the creation, mapping, and protection control over anonymous shared memory.
Summary
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.
|
static
SharedMemory
|
fromFileDescriptor(ParcelFileDescriptor fd)
Creates an instance from existing shared memory passed as ParcelFileDescriptor .
|
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 OsConstants.PROT_READ ,
OsConstants.PROT_WRITE , OsConstants.PROT_EXEC
from OsConstants , or OsConstants.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
Object
|
clone()
Creates and returns a copy of this object.
|
boolean
|
equals(Object obj)
Indicates whether some other object is "equal to" this one.
|
void
|
finalize()
Called by the garbage collector on an object when garbage collection
determines that there are no more references to the object.
|
final
Class<?>
|
getClass()
Returns the runtime class of this Object .
|
int
|
hashCode()
Returns a hash code value for the object.
|
final
void
|
notify()
Wakes up a single thread that is waiting on this object's
monitor.
|
final
void
|
notifyAll()
Wakes up all threads that are waiting on this object's monitor.
|
String
|
toString()
Returns a string representation of the object.
|
final
void
|
wait(long timeoutMillis, int nanos)
Causes the current thread to wait until it is awakened, typically
by being notified or interrupted, or until a
certain amount of real time has elapsed.
|
final
void
|
wait(long timeoutMillis)
Causes the current thread to wait until it is awakened, typically
by being notified or interrupted, or until a
certain amount of real time has elapsed.
|
final
void
|
wait()
Causes the current thread to wait until it is awakened, typically
by being notified or interrupted.
|
|
From interface
java.io.Closeable
abstract
void
|
close()
Closes this stream and releases any system resources associated
with it.
|
|
From interface
android.os.Parcelable
abstract
int
|
describeContents()
Describe the kinds of special objects contained in this Parcelable
instance's marshaled representation.
|
abstract
void
|
writeToParcel(Parcel dest, int flags)
Flatten this object in to a Parcel.
|
|
From interface
java.lang.AutoCloseable
abstract
void
|
close()
Closes this resource, relinquishing any underlying resources.
|
|
Fields
Public methods
close
public 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
public static 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 cannot be null . |
describeContents
public 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(android.os.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.
Value is either 0 or CONTENTS_FILE_DESCRIPTOR |
fromFileDescriptor
public static SharedMemory fromFileDescriptor (ParcelFileDescriptor fd)
Creates an instance from existing shared memory passed as ParcelFileDescriptor
.
The fd
should be a shared memory created from
SharedMemory or ASharedMemory
. This can be useful when shared memory is passed as
file descriptor through JNI or binder service implemented in cpp.
Note that newly created SharedMemory
takes ownership of passed fd
and
the original fd
becomes detached (Check ParcelFileDescriptor.detachFd()
).
If the caller wants to use the file descriptor after the call, the caller should duplicate
the file descriptor (Check ParcelFileDescriptor.dup()
) and pass the duped version
instead.
Parameters |
fd |
ParcelFileDescriptor : File descriptor of shared memory passed as ParcelFileDescriptor .
This value cannot be null . |
getSize
public int getSize ()
Returns |
int |
The size of the SharedMemory region. |
map
public 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(java.nio.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 cannot be null . |
mapReadOnly
public 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 cannot be null . |
mapReadWrite
public 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 cannot be null . |
setProtect
public 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 OsConstants.PROT_READ
,
OsConstants.PROT_WRITE
, OsConstants.PROT_EXEC
from OsConstants
, or OsConstants.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.
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
public static 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 cannot be null . |
writeToParcel
public void writeToParcel (Parcel dest,
int flags)
Flatten this object in to a Parcel.