< prev index next >

src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/MemorySegment.java

Print this page




  62  * using the factory method {@link MemorySegment#ofByteBuffer(ByteBuffer)}.
  63  * Memory segments obtained in this way are called <em>buffer memory segments</em>. Note that buffer memory segments might
  64  * be backed by native memory (as in the case of native memory segments) or heap memory (as in the case of array memory segments),
  65  * depending on the characteristics of the byte buffer instance the segment is associated with. For instance, a buffer memory
  66  * segment obtained from a byte buffer created with the {@link ByteBuffer#allocateDirect(int)} method will be backed
  67  * by native memory.
  68  * <p>
  69  * Finally, it is also possible to obtain a memory segment backed by a memory-mapped file using the factory method
  70  * {@link MemorySegment#mapFromPath(Path, long, FileChannel.MapMode)}. Such memory segments are called <em>mapped memory segments</em>.
  71  *
  72  * <h2>Closing a memory segment</h2>
  73  *
  74  * Memory segments are closed explicitly (see {@link MemorySegment#close()}). In general when a segment is closed, all off-heap
  75  * resources associated with it are released; this has different meanings depending on the kind of memory segment being
  76  * considered:
  77  * <ul>
  78  *     <li>closing a native memory segment results in <em>freeing</em> the native memory associated with it</li>
  79  *     <li>closing a mapped memory segment results in the backing memory-mapped file to be unmapped</li>
  80  *     <li>closing an acquired memory segment <b>does not</b> result in the release of resources
  81  *     (see the section on <a href="#thread-confinement">thread confinement</a> for more details)</li>
  82  *     <li>closing a buffer, or a heap segment does not have any side-effect, other than making the marking the segment
  83  *     as <em>not alive</em> (see {@link MemorySegment#isAlive()}). Also, since the buffer and heap segments might keep
  84  *     strong references to the original buffer or array instance, it is the responsibility of clients to ensure that
  85  *     these segments are discarded in a timely manner, so as not to prevent garbage collection to reclaim the underlying
  86  *     objects.</li>
  87  * </ul>
  88  *
  89  * <h2><a id = "thread-confinement">Thread confinement</a></h2>
  90  *
  91  * Memory segments support strong thread-confinement guarantees. Upon creation, they are assigned an <em>owner thread</em>,
  92  * typically the thread which initiated the creation operation. After creation, only the owner thread will be allowed
  93  * to directly manipulate the memory segment (e.g. close the memory segment) or access the underlying memory associated with
  94  * the segment using a memory access var handle. Any attempt to perform such operations from a thread other than the
  95  * owner thread will result in a runtime failure.
  96  * <p>
  97  * If a memory segment S owned by thread A needs to be used by thread B, B needs to explicitly <em>acquire</em> S,
  98  * which will create a so called <em>acquired</em> memory segment owned by B (see {@link #acquire()}) backed by the same resources
  99  * as S. A memory segment can be acquired multiple times by one or more threads; in that case, a memory segment S cannot
 100  * be closed until all the acquired memory segments derived from S have been closed. Furthermore, closing an acquired
 101  * memory segment does <em>not</em> trigger any deallocation action. It is therefore important that clients remember to
 102  * explicitly close the original segment from which the acquired memory segments have been obtained in order to truly




  62  * using the factory method {@link MemorySegment#ofByteBuffer(ByteBuffer)}.
  63  * Memory segments obtained in this way are called <em>buffer memory segments</em>. Note that buffer memory segments might
  64  * be backed by native memory (as in the case of native memory segments) or heap memory (as in the case of array memory segments),
  65  * depending on the characteristics of the byte buffer instance the segment is associated with. For instance, a buffer memory
  66  * segment obtained from a byte buffer created with the {@link ByteBuffer#allocateDirect(int)} method will be backed
  67  * by native memory.
  68  * <p>
  69  * Finally, it is also possible to obtain a memory segment backed by a memory-mapped file using the factory method
  70  * {@link MemorySegment#mapFromPath(Path, long, FileChannel.MapMode)}. Such memory segments are called <em>mapped memory segments</em>.
  71  *
  72  * <h2>Closing a memory segment</h2>
  73  *
  74  * Memory segments are closed explicitly (see {@link MemorySegment#close()}). In general when a segment is closed, all off-heap
  75  * resources associated with it are released; this has different meanings depending on the kind of memory segment being
  76  * considered:
  77  * <ul>
  78  *     <li>closing a native memory segment results in <em>freeing</em> the native memory associated with it</li>
  79  *     <li>closing a mapped memory segment results in the backing memory-mapped file to be unmapped</li>
  80  *     <li>closing an acquired memory segment <b>does not</b> result in the release of resources
  81  *     (see the section on <a href="#thread-confinement">thread confinement</a> for more details)</li>
  82  *     <li>closing a buffer, or a heap segment does not have any side-effect, other than marking the segment
  83  *     as <em>not alive</em> (see {@link MemorySegment#isAlive()}). Also, since the buffer and heap segments might keep
  84  *     strong references to the original buffer or array instance, it is the responsibility of clients to ensure that
  85  *     these segments are discarded in a timely manner, so as not to prevent garbage collection to reclaim the underlying
  86  *     objects.</li>
  87  * </ul>
  88  *
  89  * <h2><a id = "thread-confinement">Thread confinement</a></h2>
  90  *
  91  * Memory segments support strong thread-confinement guarantees. Upon creation, they are assigned an <em>owner thread</em>,
  92  * typically the thread which initiated the creation operation. After creation, only the owner thread will be allowed
  93  * to directly manipulate the memory segment (e.g. close the memory segment) or access the underlying memory associated with
  94  * the segment using a memory access var handle. Any attempt to perform such operations from a thread other than the
  95  * owner thread will result in a runtime failure.
  96  * <p>
  97  * If a memory segment S owned by thread A needs to be used by thread B, B needs to explicitly <em>acquire</em> S,
  98  * which will create a so called <em>acquired</em> memory segment owned by B (see {@link #acquire()}) backed by the same resources
  99  * as S. A memory segment can be acquired multiple times by one or more threads; in that case, a memory segment S cannot
 100  * be closed until all the acquired memory segments derived from S have been closed. Furthermore, closing an acquired
 101  * memory segment does <em>not</em> trigger any deallocation action. It is therefore important that clients remember to
 102  * explicitly close the original segment from which the acquired memory segments have been obtained in order to truly


< prev index next >