Skip to content

Commit 222295b

Browse files
mvincentonggaaclarkeloic-sharma
authored
Document frozen embedder API structs (flutter#186842)
## Issue Part of flutter#38470. The issue asks for embedder API structs that must not be extended in place to be documented. Review feedback asked what basis was used to decide which structs were frozen. ## Fix Narrowed the PR to document only the structs that are already protected by the `EmbedderFrozen` golden test in `engine/src/flutter/shell/platform/embedder/tests/embedder_frozen_unittests.cc`. This removes the earlier unsupported `ABI-sealed` labels from renderer, backing-store, task, Dart object, and AOT structs that are not covered by that test-backed source of truth. ## Tests - `git diff --check` - Not run: `clang-format --dry-run --Werror engine/src/flutter/shell/platform/embedder/embedder.h`, because `clang-format` is not installed in this checkout. ## Risk Docs-only change to `engine/src/flutter/shell/platform/embedder/embedder.h`. No generated output. Other possible sealed embedder structs may still need a separate verified pass before being documented. --------- Co-authored-by: gaaclarke <[email protected]> Co-authored-by: Loïc Sharma <[email protected]>
1 parent 8ef2fe4 commit 222295b

1 file changed

Lines changed: 16 additions & 0 deletions

File tree

  • engine/src/flutter/shell/platform/embedder

‎engine/src/flutter/shell/platform/embedder/embedder.h‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,8 @@
3131
// - Instead of array of structures, prefer array of pointers to structures.
3232
// This ensures that array indexing does not break if members are added
3333
// to the structure.
34+
// - Structures documented as frozen must not have members added. Introduce a
35+
// new versioned structure instead.
3436
//
3537
// These changes are allowed:
3638
// - Adding new struct members at the end of a structure as long as the struct
@@ -392,6 +394,7 @@ typedef struct _FlutterEngine* FLUTTER_API_SYMBOL(FlutterEngine);
392394
/// opaque to the engine; the engine does not interpret view IDs in any way.
393395
typedef int64_t FlutterViewId;
394396

397+
// Frozen because adding members would break the ABI of `FlutterSemanticsNode`.
395398
typedef struct {
396399
/// horizontal scale factor
397400
double scaleX;
@@ -645,6 +648,9 @@ typedef struct {
645648
} FlutterUIntSize;
646649

647650
/// A structure to represent a rectangle.
651+
///
652+
// Frozen because adding members would break the ABI of `FlutterSemanticsNode`
653+
// and `FlutterDamage`.
648654
typedef struct {
649655
double left;
650656
double top;
@@ -653,6 +659,8 @@ typedef struct {
653659
} FlutterRect;
654660

655661
/// A structure to represent a 2D point.
662+
///
663+
// Frozen because adding members would break the ABI of `FlutterLayer`.
656664
typedef struct {
657665
double x;
658666
double y;
@@ -668,6 +676,8 @@ typedef struct {
668676
} FlutterRoundedRect;
669677

670678
/// A structure to represent a damage region.
679+
///
680+
// Frozen because adding members would break the ABI of `FlutterPresentInfo`.
671681
typedef struct {
672682
/// The size of this struct. Must be sizeof(FlutterDamage).
673683
size_t struct_size;
@@ -1582,6 +1592,9 @@ typedef struct {
15821592
/// ABI compatibility for existing users, no new fields will be
15831593
/// added to this struct. New fields will continue to be added
15841594
/// to `FlutterSemanticsNode2`.
1595+
///
1596+
// Frozen because adding members would break the ABI of
1597+
// `FlutterSemanticsUpdate`.
15851598
typedef struct {
15861599
/// The size of this struct. Must be sizeof(FlutterSemanticsNode).
15871600
size_t struct_size;
@@ -1789,6 +1802,9 @@ extern const int32_t kFlutterSemanticsCustomActionIdBatchEnd;
17891802
/// preserve ABI compatility for existing users, no new fields
17901803
/// will be added to this struct. New fields will continue to
17911804
/// be added to `FlutterSemanticsCustomAction2`.
1805+
///
1806+
// Frozen because adding members would break the ABI of
1807+
// `FlutterSemanticsUpdate`.
17921808
typedef struct {
17931809
/// The size of the struct. Must be sizeof(FlutterSemanticsCustomAction).
17941810
size_t struct_size;

0 commit comments

Comments
 (0)