1 /* 2 * Copyright (C) 2019 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 package android.os; 18 19 import android.annotation.IntRange; 20 import android.annotation.NonNull; 21 import android.annotation.Nullable; 22 import android.annotation.SystemApi; 23 24 import java.io.Closeable; 25 import java.io.IOException; 26 27 /** 28 * An abstract representation of a memory block, as representing by the HIDL system. 29 * 30 * The block is defined by a {name, size, handle} tuple, where the name is used to determine how to 31 * interpret the handle. The underlying handle is assumed to be owned by this instance and will be 32 * closed as soon as {@link #close()} is called on this instance, or this instance has been 33 * finalized (the latter supports using it in a shared manner without having to worry about who owns 34 * this instance, the former is more efficient resource-wise and is recommended for most use-cases). 35 * Note, however, that ownership of the handle does not necessarily imply ownership of the 36 * underlying file descriptors - the underlying handle may or may not own them. If you want the 37 * underlying handle to outlive this instance, call {@link #releaseHandle()} to obtain the handle 38 * and detach the ownership relationship. 39 * 40 * @hide 41 */ 42 @SystemApi 43 public class HidlMemory implements Closeable { 44 private final @NonNull String mName; 45 private final long mSize; 46 private @Nullable NativeHandle mHandle; 47 private long mNativeContext; // For use of native code. 48 49 /** 50 * Constructor. 51 * 52 * @param name The name of the IMapper service used to resolve the handle (e.g. "ashmem"). 53 * @param size The (non-negative) size in bytes of the memory block. 54 * @param handle The handle. May be null. This instance will own the handle and will close it 55 * as soon as {@link #close()} is called or the object is destroyed. This, this 56 * handle instance should generally not be shared with other clients. 57 */ HidlMemory(@onNull String name, @IntRange(from = 0) long size, @Nullable NativeHandle handle)58 public HidlMemory(@NonNull String name, @IntRange(from = 0) long size, 59 @Nullable NativeHandle handle) { 60 mName = name; 61 mSize = size; 62 mHandle = handle; 63 } 64 65 /** 66 * Create a copy of this instance, where the underlying handle (and its file descriptors) have 67 * been duplicated. 68 */ 69 @NonNull dup()70 public HidlMemory dup() throws IOException { 71 return new HidlMemory(mName, mSize, mHandle != null ? mHandle.dup() : null); 72 } 73 74 /** 75 * Close the underlying native handle. No-op if handle is null or has been released using {@link 76 * #releaseHandle()}. 77 */ 78 @Override close()79 public void close() throws IOException { 80 if (mHandle != null) { 81 mHandle.close(); 82 mHandle = null; 83 } 84 } 85 86 /** 87 * Disowns the underlying handle and returns it. The underlying handle becomes null. 88 * 89 * @return The underlying handle. 90 */ 91 @Nullable releaseHandle()92 public NativeHandle releaseHandle() { 93 NativeHandle handle = mHandle; 94 mHandle = null; 95 return handle; 96 } 97 98 /** 99 * Gets the name, which represents how the handle is to be interpreted. 100 * 101 * @return The name. 102 */ 103 @NonNull getName()104 public String getName() { 105 return mName; 106 } 107 108 /** 109 * Gets the size of the block, in bytes. 110 * 111 * @return The size. 112 */ getSize()113 public long getSize() { 114 return mSize; 115 } 116 117 /** 118 * Gets a native handle. The actual interpretation depends on the name and is implementation 119 * defined. 120 * 121 * @return The native handle. 122 */ 123 @Nullable getHandle()124 public NativeHandle getHandle() { 125 return mHandle; 126 } 127 128 @Override finalize()129 protected void finalize() { 130 try { 131 close(); 132 } catch (IOException e) { 133 throw new RuntimeException(e); 134 } finally { 135 nativeFinalize(); 136 } 137 } 138 nativeFinalize()139 private native void nativeFinalize(); 140 } 141