github.com/primecitizens/pcz/std@v0.2.1/core/mark/notinheap.go (about)

     1  // SPDX-License-Identifier: Apache-2.0
     2  // Copyright 2023 The Prime Citizens
     3  
     4  package mark
     5  
     6  import (
     7  	"github.com/primecitizens/pcz/std/core/mark/internal/sys"
     8  )
     9  
    10  // NotInHeap is a type must never be allocated from the GC'd heap or on the stack,
    11  // and is called not-in-heap.
    12  //
    13  // Other types can embed NotInHeap to make it not-in-heap. Specifically, pointers
    14  // to these types must always fail the `runtime.inheap` check. The type may be used
    15  // for global variables, or for objects in unmanaged memory (e.g., allocated with
    16  // `sysAlloc`, `persistentalloc`, r`fixalloc`, or from a manually-managed span).
    17  //
    18  // Specifically:
    19  //
    20  // 1. `new(T)`, `make([]T)`, `append([]T, ...)` and implicit heap
    21  // allocation of T are disallowed. (Though implicit allocations are
    22  // disallowed in the runtime anyway.)
    23  //
    24  // 2. A pointer to a regular type (other than `unsafe.Pointer`) cannot be
    25  // converted to a pointer to a not-in-heap type, even if they have the
    26  // same underlying type.
    27  //
    28  // 3. Any type that containing a not-in-heap type is itself considered as not-in-heap.
    29  //
    30  // - Structs and arrays are not-in-heap if their elements are not-in-heap.
    31  // - Maps and channels contains no-in-heap types are disallowed.
    32  //
    33  // 4. Write barriers on pointers to not-in-heap types can be omitted.
    34  //
    35  // The last point is the real benefit of NotInHeap. The runtime uses
    36  // it for low-level internal structures to avoid memory barriers in the
    37  // scheduler and the memory allocator where they are illegal or simply
    38  // inefficient. This mechanism is reasonably safe and does not compromise
    39  // the readability of the runtime.
    40  type NotInHeap = sys.NotInHeap