Introduced with Swift 5.0 alongside library evolution support, the @frozen attribute was designed to resolve the tension between API extensibility and binary stability. Prior to this mechanism, all public enums in resilient libraries were implicitly non-frozen, forcing the compiler to assume that future versions might add unknown cases. This assumption prevented the generation of compact, fixed-size layouts and mandated defensive programming patterns in client code. The attribute provides a formal guarantee that the enum's case inventory is immutable forever, enabling aggressive optimizations.
The problem arises when a library publishes an enum without this attribute. Swift must then treat the enum as resilient, reserving variable space in its memory representation to accommodate future case discriminators and associated value layouts. This forces client switches to include a @unknown default case, effectively disabling compile-time verification that all logical states are handled. Without such a default, adding a case to the library would cause undefined behavior in precompiled client binaries that lack the code to process the new discriminator value, leading to crashes or memory corruption.
The solution lies in the @frozen annotation establishing a permanent contract. By marking an enum as frozen, the library author promises that the set of cases will never change, allowing the compiler to assign fixed integer tags and use a stable, compact memory layout. This enables exhaustive switch statements without default cases, as the compiler can prove that all possible bit patterns of the discriminator correspond to known cases. The resulting ABI stability ensures that the enum's size and alignment remain constant across library versions, while client code benefits from jump-table optimizations and mandatory handling of every state.
// Within a library compiled with -enable-library-evolution @frozen public enum LoadState { case idle case loading case loaded(Data) } // Client code in a separate module func updateUI(for state: LoadState) { switch state { case .idle: print("Waiting") case .loading: print("Spinner") case .loaded: print("Content") // Compiler verifies exhaustiveness; no default required } }
The platform team at a logistics company was shipping a Swift package for route optimization that exposed a TransportMode enum with cases for .truck, .air, and .ship. Because they anticipated adding .drone and .rail in subsequent releases, they initially distributed the library without the @frozen attribute. Client teams soon reported that Xcode refused to compile switches without @unknown default clauses, hiding logic errors where they forgot to handle .ship in freight cost calculations.
The team considered three architectural approaches to resolve this.
First, they could maintain the non-frozen status and invest in heavy linting to ensure clients wrote @unknown default handlers that logged warnings. This preserved flexibility to add transport modes without major version bumps, but it permanently disabled compile-time exhaustiveness checking. It also failed to address the binary size overhead, as each enum instance carried resilience metadata that bloated the serialized route packets sent to drivers' devices.
Second, they could replace the enum with a RawRepresentable struct backed by integer constants. This would provide a fixed memory layout and allow adding new modes without breaking binary compatibility, but it would sacrifice Swift's pattern matching capabilities entirely. Developers would be forced into verbose if-else chains, and the compiler could no longer verify that all possible transport states were handled in critical pathfinding algorithms.
Third, they could apply @frozen to the enum and commit to the existing three cases, creating a separate ExtendedTransportMode wrapper for future expansions. This would eliminate the resilience overhead, enable exhaustive switch compilation, and guarantee that every client handled all current modes explicitly. The trade-off was a permanent restriction on modifying the original enum and the necessity of versioning for any fundamental additions.
They chose the third solution. After freezing TransportMode, they immediately discovered two unhandled switch cases in their own analytics dashboard during compilation. The removal of resilience metadata reduced the size of transmitted route objects by 18%, and the explicit architectural boundary forced a cleaner separation between core transport logic and experimental modes.
Why does adding a case to a non-frozen public enum break binary compatibility even when client source code still compiles successfully?
When Swift compiles a resilient module, non-frozen enums utilize a variable-width representation that reserves space for future case discriminators. If the library subsequently adds a case, the runtime layout of the enum changes—for example, the discriminator integer might expand from 8 bits to 16 bits to accommodate the new tag. Precompiled client binaries expect the old layout and contain jump tables or conditional branches that only account for the original tag range. When these binaries encounter the new discriminator value, they may execute invalid code paths or read memory beyond the expected payload boundary, causing crashes that source-level @unknown default clauses cannot prevent.
How does @frozen interact with enums that contain indirect cases or associated values of resilient types?
@frozen guarantees that the identity and count of cases remain constant, but it does not freeze the size of associated values. If a case carries a payload of a non-frozen struct or a class reference, the enum's ABI stability refers to the fixed discriminator tag, while the payload storage may still utilize dynamic sizing through pointers or value witness tables. Candidates often incorrectly assume that @frozen pins the entire memory footprint including payload sizes; in reality, the optimization primarily applies to the tag, and associated values may still require runtime layout calculations if their types are themselves resilient or contain unknown sizes.
Can a frozen enum be declared within a non-resilient module, and what are the long-term implications of doing so?
Yes, @frozen can be applied to enums within regular application targets where library evolution is disabled. In this context, the attribute functions as documentation of intent, as all enums within the module are effectively frozen due to the lack of resilience boundaries. However, candidates frequently overlook that @frozen constitutes a permanent ABI contract; if the module is later extracted into a resilient library framework, the enum cannot be unfrozen or extended without breaking binary compatibility with existing clients. Explicitly marking enums as frozen during initial development future-proofs the codebase against accidental ABI violations when the project's architecture evolves.