As owner of a Swift binary framework built for distribution, what do you commit to when you mark public types @frozen and functions @inlinable, and how do you decide what to mark?
answer
- resilient by default, opt out per type
- stored layout becomes permanent ABI
- inlined bodies outlive your fixes
- freeze small, stable, hot types
basics
~20 s@frozen makes a type's stored layout, or an enum's cases, permanent ABI: no adding, removing or reordering, and the attribute can never be removed. @inlinable compiles a body into clients, where old copies survive until each client rebuilds.
solid answer
~50 sWith library evolution on, public structs and enums are **resilient**: clients reach their fields and cases through the framework at run time, so you can change them. `@frozen` trades that for direct access. Stored properties, even private ones, can no longer be added, removed, reordered or switched between stored and computed, and `@frozen` can be neither added later nor removed; a frozen enum can never gain a case, so clients may switch over it without `@unknown default`. `@inlinable` compiles a body into clients, so a fix reaches them only when they rebuild, several versions can coexist in one process, and every internal helper it calls must stay exported while old clients might call it. I would freeze only small, stable, measured-hot value types such as tokens or geometry, keep options and models resilient, make only short, obviously correct code `@inlinable`, and compare the ABI of every release in CI.
code
swift · 26 lines// Built with -enable-library-evolution (Xcode: Build Libraries for Distribution)
@frozen
public struct JSONToken {
public var kind: JSONKind
public var start: Int32
public var length: Int32
}
@frozen
public enum JSONKind: UInt8 {
case string, number, object, array, literal
}
public struct ParserOptions { // resilient: can grow next release
public var maxDepth: Int
public init(maxDepth: Int = 512) { self.maxDepth = maxDepth }
}
extension JSONToken {
@inlinable
public var end: Int32 { start + length }
@inlinable
public var isContainer: Bool { kind == .object || kind == .array }
}go deeper
Recall that a binary framework must keep working with apps built against older versions, and that @frozen and @inlinable give up some of that flexibility for speed.
Explain resilient types: clients reach fields and cases through the framework at run time, which @frozen replaces with a fixed, published layout.
List the exact commitments: no stored-property or case changes, no removing @frozen, inlined bodies persisting in clients, and helpers that must stay exported.
Own the policy: measure from a client first, freeze only small stable hot value types, keep evolving types resilient, inline only trivial generic entry points, and gate every release on an ABI comparison.
## Resilient by default A framework shipped as a binary, for example an XCFramework that apps link without recompiling it, is built with **library evolution**: the `-enable-library-evolution` flag, or Xcode's Build Libraries for Distribution setting, which swift.org's library evolution article recommends turning on in both Debug and Release builds. In that mode every public struct and enum is **resilient**. Clients do not know its size or field offsets at compile time; they copy, read and switch over it through the framework, at run time. That indirection is the price of being able to add a stored property or an enum case in version 2 without breaking apps built against version 1. Two attributes let you opt out where speed matters more than flexibility. Both are permanent promises to every client binary. ## What @frozen commits you to `@frozen` publishes a struct's stored layout, or an enum's set of cases, so clients can access fields directly, copy values without calling into the framework and pass small ones in registers rather than indirectly. | Change | Resilient struct | `@frozen` struct | |---|---|---| | Add a stored property, even `private` | Allowed | Breaks ABI | | Reorder stored properties | Allowed | Breaks ABI | | Remove a non-public stored property | Allowed | Breaks ABI | | Change a stored property to computed, or back | Allowed | Breaks ABI | | Add a method, computed property or conformance | Allowed | Allowed | | Change an existing method body | Allowed | Allowed | | `@frozen` itself | Cannot be added later | Cannot be removed | More rules follow from the same promise: - Every type used in a stored property must be ABI-public, so an internal helper type must become `public` or `@usableFromInline`; the compiler enforces this even when library evolution is off. - A frozen enum can never gain a case, which is why clients may switch over it exhaustively without `@unknown default`. For a non-frozen enum from a library-evolution framework, a client's missing `@unknown default` is a warning in Swift 5 mode and an error in Swift 6 mode. - Types must be born frozen: there is no supported way to freeze an existing resilient type later. - Break the promise and clients that were not rebuilt use the old layout; SE-0260 calls the result undefined behaviour, on par with misusing unsafe pointers. The compiler does not stop you. Without library evolution, for a package always built with the app, the compiler already treats every struct and enum as frozen, so the attribute buys nothing there. ## What @inlinable commits you to `@inlinable` copies a function's body into the module interface so clients can inline and specialize it. Consequences: 1. A bug fix in the body reaches a client only when that client rebuilds; until then the old body runs inside the app. 2. Several versions of the body can run in one process: the framework's own copy and each client's inlined one. Anything that must agree across them, a hash algorithm or an encoding, must never change. 3. The body may reference only ABI-public declarations, so internal helpers become `@usableFromInline` and stay exported for as long as any shipped client might call them. 4. Removing `@inlinable` later is binary-compatible, but already-built clients keep their copies. ## Deciding what to mark The decision has no single right answer; it is a trade between client speed and your freedom to evolve. A defensible policy: 1. **Measure first.** Profile a client app's Release build calling the resilient framework. Mark nothing that does not show up in the profile. 2. **Freeze small, stable value types on hot paths:** token kinds, spans, points, identifiers, whose fields are dictated by their meaning and are unlikely to grow. 3. **Keep evolving types resilient:** options, configuration, models and anything that might gain a field or a case, such as an error enum. 4. **Make only short, obviously correct, generic entry points `@inlinable`,** typically thin wrappers that need specialization, and keep the substantial logic behind non-inlinable calls you can still fix. 5. **Version the promise.** Record each `@frozen` and `@inlinable` decision in review, because it cannot be undone. ## Guardrails - Compare the module's ABI against the previous release in CI; the Swift repository ships `swift-api-digester` for this kind of check. - Review every `@usableFromInline` declaration as if it were public API: once shipped, it cannot be deleted while old clients might call it. - Re-measure from a client after each release; a frozen type that no longer sits on a hot path is still frozen forever.
- Does @frozen matter for a Swift package that is always built from source with the app?Not for speed. Without library evolution the compiler already treats every struct and enum as frozen and sees their layouts. The attribute's source rules still apply, for example a stored property's type must be public or `@usableFromInline`, so adding it there only adds constraints.
- What happens if a later release adds a stored property to a @frozen struct anyway?Clients built against the old release keep using the old size and field offsets, so they read and write the wrong memory. SE-0260 calls this undefined behaviour, on par with misusing unsafe pointers. The compiler will not stop you; only an ABI comparison between releases catches it, which is why that check belongs in CI.
- Is removing @inlinable from a function in a later release safe?It is binary-compatible: under library evolution the function keeps its exported symbol, so newly built clients simply call it. But clients built earlier keep their inlined copies until they rebuild, and any `@usableFromInline` helpers those copies call must remain exported.
- @frozen makes the struct's values immutable.
- You can add @frozen in a later release once the type has settled.
- Private stored properties of a @frozen struct can still be added freely.
- Changing an @inlinable body ships the fix to every existing client app.
- Every Swift package should turn on library evolution to be safe.
Assumes Swift 6.4; library evolution and @frozen date from Swift 5.1 (SE-0260), and a client's switch over a library-evolution framework's non-frozen enum without @unknown default warns in Swift 5 mode and is an error in Swift 6 mode.