Skip to content

generate schemas as statically initialized package-level variables - #749

Draft
lucix-aws wants to merge 1 commit into
mainfrom
static-schemas
Draft

lucix-aws wants to merge 1 commit into
mainfrom
static-schemas

Conversation

@lucix-aws

@lucix-aws lucix-aws commented Nov 10, 2026 •

Copy link
Copy Markdown
Collaborator

Schemas are now generated as package-level variables that the compiler initializes statically, instead of NewSchema/AddMember calls in an init(). Schema packages no longer run code or allocate at startup, and the linker can drop schemas that nothing references.

This replaces the table-based layout from the pagedata branch (records indexed by row in a per-package SchemaSet). That layout fixed the heap but made every accessor chain through the set, record slices and bounds checks, and it was slower than main. Here every schema reaches its data with the same number of loads as main, except trait lookups (one extra load) and extension lookups (one extra load).

Layout

type Schema struct{ d StaticSchema } // no exported fields

type StaticSchema struct {
	Member  string            // member name, "" for shapes
	ID      *ShapeName        // the shape's name, or a member's target's
	Members *SchemaMembers    // shared by a shape and every member that targets it
	Traits  *TraitSet         // deduplicated effective traits, nil if none
	Type    ShapeType
	Ext     *SchemaExtensions // codec extension slots, a zero variable per schema
}

type SchemaMembers struct {
	List []*Schema   // definition order, a map's key before its value
	Hash *MemberHash // perfect hash for shapes with more than 8 members
	// unexported: map for NewSchema schemas, lazily built map for Members()
}

Generated code looks like this:

var mAttributeValue = smithy.SchemaMembers{List: []*smithy.Schema{&sAttributeValue_S, ...}, Hash: &hAttributeValue}
var sAttributeValue = smithy.NewStaticSchema(smithy.StaticSchema{ID: &iAttributeValue, Members: &mAttributeValue, Type: smithy.ShapeTypeUnion, Ext: &eAttributeValue})
var AttributeValue = &sAttributeValue

NewStaticSchema is small enough to inline, which is what lets the compiler lay these out as data. Recursive shapes would make the initializers refer to each other in a cycle, which Go rejects, so the member that closes each cycle is left without Members and completed in a small init() (one store per member, no allocation). That's 182 members across the whole SDK, in 57 packages.

Member(name) scans List for shapes with up to 8 members and uses the perfect hash otherwise. ListMember, MapKey and MapValue read List[0]/List[1]. NewSchema and AddMember build the same structure on the heap and still work, including with a static schema as the AddMember target.

The JSON and CBOR struct readers now call Member(serde.UnsafeString(key)) instead of Members()[string(key)].

API

Added, for generated code only: NewStaticSchema, StaticSchema, SchemaMembers, MemberHash, ShapeName, SchemaExtensions, TraitSet. Schema.Dump and SchemaDump are also added; only the SDK's static-vs-dynamic verification test uses them, and they could move somewhere less visible. No existing exported signature changed.

Behavior changes:

  • ListMember, MapKey and MapValue return nil unless the schema is a list/set or map. Before, ListMember returned a member named member on any shape.
  • AddMember keeps a map's key before its value.
  • Members() is nil for a static shape without members, instead of an empty map.
  • AddMember on a static schema panics.

Results

Measured on m7i.xlarge and m7g.xlarge with Go 1.27.3, against main and against the pagedata layout. All variants were interleaved within each rep on the same boxes, over two rounds (10 and 6 reps). The aws-sdk-go-v2 side is the pagedata-ptrc branch.

Serde benchmarks, mean over 71 cases versus main:

x86_64 arm64
this PR -1.0% -1.1%
pagedata layout +0.5% +0.6%

The gain comes from member lookups. A linear scan or perfect hash takes about half the time of a Go map lookup (4-member struct: 10.3 ns -> 6.0 ns on x86, 10.0 -> 5.5 on arm). On arm, ListMember also avoids an atomic load. The one regression is REST serialize, at +1-2.6%. The httpbinding serializer makes about 6 SchemaTrait calls per member per request, and deduplicated trait sets sit farther from the schema than main's per-member copies, which costs L1 misses. Caching HTTP-binding membership in the httpbinding extension would fix that for any layout.

Stripped binary size, MiB (x86_64):

program main this PR
all 435 services, every operation reachable 522.95 521.68
all 435 services, blank import 65.52 21.84
QuickSight, every operation reachable 19.78 19.82
DynamoDB, one GetItem call 7.20 7.02

Heap and startup (x86_64):

main this PR
all 435 services linked: heap after init 139.7 MiB (821k objects) 20.1 MiB (106k objects)
all 435 services linked: schema package init 145 ms, 117 MiB, 718k allocations 0.3 ms, 0 allocations
all 435 services linked: start to exit 221 ms 53 ms
QuickSight alone: heap after init 3,696 KiB 211 KiB
QuickSight alone: start to exit 6.1 ms 1.8 ms

Costs:

  • Static schemas hold pointers, so the GC scans them as roots. A forced GC on an otherwise idle QuickSight client takes 405 us here versus 1,152 us on main.
  • Generated schemas.go is about 2x main's size across the SDK, because every schema is a keyed composite literal.

Testing

  • smithy-go go test ./..., codegen ./gradlew build.
  • In aws-sdk-go-v2 regenerated with this codegen: all protocol test and serde benchmark modules, and a check that every QuickSight and Glue schema matches the one the old generator produced (11,818 and 7,489 schemas). On the pointer layout without the ext/size changes, the 490-module fleet passed go test and go vet --all except codegen and one config test, which fails on the base commit too.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant