docs(native-class): update memory layout documentation and add padding fields to test classes

- Add $padding field to NativeFailedClonePressure class in failed-clone-finalizer.phpt
- Add $padding field to NativeFailedLifecyclePressure class in failed-lifecycle-escape.phpt
- Add $padding field to NativeFinalizerFiller class in finalizer-allocation.phpt
- Add $padding field to NativeFinalizerPressureObject class in finalizer-inheritance-exception.phpt
- Add multiple padding fields ($padding1, $padding2, $padding3) to NativeGcThresholdValue class in gc-threshold.phpt
- Add $padding field to NativeLifecycleFiller class in lifecycle-exceptions.phpt
- Update native heap memory layout documentation with fixed header size information
- Clarify that GC header uses two machine words (16 bytes on 64-bit platforms)
- Explain that object size, alignment and callbacks are stored in static NativeTypeDescriptor
- Remove mention of initial
master
韩天峰 7 days ago
parent f1ef66622c
commit d1704b42ef
  1. 9
      docs/NATIVE_CLASS_OBJECT.md
  2. 1
      tests/compiler/native-class/failed-clone-finalizer.phpt
  3. 1
      tests/compiler/native-class/failed-lifecycle-escape.phpt
  4. 1
      tests/compiler/native-class/finalizer-allocation.phpt
  5. 1
      tests/compiler/native-class/finalizer-inheritance-exception.phpt
  6. 6
      tests/compiler/native-class/gc-threshold.phpt
  7. 1
      tests/compiler/native-class/lifecycle-exceptions.phpt

@ -431,21 +431,20 @@ Native Class Object 应使用独立的、非移动、精确 tracing GC。本文
### 8.1 Native Heap ### 8.1 Native Heap
首版 Wren 派生实现为每个对象分配一块连续内存,并在 struct 前放置隐藏 GC header: Wren 派生实现为每个对象分配一块连续内存,并在 struct 前放置隐藏 GC header。Header 固定为两个机器字,在 64 位平台上是 16 字节
```cpp ```cpp
struct NativeGcHeader { struct NativeGcHeader {
// 低 3 位复用为 marked/finalized/allocated-during-collection 标志。
uintptr_t nextAndFlags;
const NativeTypeDescriptor *type; const NativeTypeDescriptor *type;
NativeGcHeader *next;
uint32_t flags;
uint32_t size;
}; };
// 内存布局:[NativeGcHeader][php_app__point] // 内存布局:[NativeGcHeader][php_app__point]
auto *point = native_heap.make<php_app__point>(); auto *point = native_heap.make<php_app__point>();
``` ```
GC header 不属于生成的 C++ struct,也不会改变属性偏移。用户可见对象变量仍然只是一个 `native_struct *` GC header 不属于生成的 C++ struct,也不会改变属性偏移。用户可见对象变量仍然只是一个 `native_struct *`对象尺寸、对齐方式及 trace/finalize/destroy 回调保存在每个类型唯一的静态 `NativeTypeDescriptor` 中,不在每个实例中重复保存。
当前分配器使用独立 non-moving allocation;Arena/chunk/free-list 可以作为后续分配器 当前分配器使用独立 non-moving allocation;Arena/chunk/free-list 可以作为后续分配器
优化,但不得改变对象地址稳定性、header 布局、精确 tracing 或 finalization 语义。 优化,但不得改变对象地址稳定性、header 布局、精确 tracing 或 finalization 语义。

@ -25,6 +25,7 @@ class NativeFailedCloneFinalizer
class NativeFailedClonePressure class NativeFailedClonePressure
{ {
public int $value; public int $value;
public int $padding;
} }
function forceFailedCloneCollection(): void function forceFailedCloneCollection(): void

@ -68,6 +68,7 @@ class NativeFailedCloneEscape
class NativeFailedLifecyclePressure class NativeFailedLifecyclePressure
{ {
public int $value; public int $value;
public int $padding;
} }
function forceNativeCollection(): void function forceNativeCollection(): void

@ -28,6 +28,7 @@ class NativeFinalizerCreator
class NativeFinalizerFiller class NativeFinalizerFiller
{ {
public int $value; public int $value;
public int $padding;
} }
function main(): void function main(): void

@ -28,6 +28,7 @@ class NativeThrowingFinalizerChild extends NativeThrowingFinalizerBase
class NativeFinalizerPressureObject class NativeFinalizerPressureObject
{ {
public int $value; public int $value;
public int $padding;
} }
function collectThrowingFinalizer(): void function collectThrowingFinalizer(): void

@ -6,6 +6,12 @@ Native class: long-running allocation triggers automatic tracing collection
#[Native] #[Native]
class NativeGcThresholdValue class NativeGcThresholdValue
{ {
// Keep the pressure in the object payload so this test does not depend on
// the implementation size of the hidden Native GC header.
public int $padding1;
public int $padding2;
public int $padding3;
public function __destruct() public function __destruct()
{ {
global $nativeGcFinalized; global $nativeGcFinalized;

@ -66,6 +66,7 @@ class NativeThrowingFinalizer
class NativeLifecycleFiller class NativeLifecycleFiller
{ {
public int $value; public int $value;
public int $padding;
} }
function allocateUntilFinalizerRuns(): void function allocateUntilFinalizerRuns(): void

Loading…
Cancel
Save