In a Swift binary framework, a generic JSON decode function runs several times slower when the app calls it than in a benchmark inside the framework module: why, and how do @inlinable and @usableFromInline fix it?
answer
- who can see the body
- metadata and witness tables passed in
- library evolution hides definitions
- export the body, keep helpers ABI-public
basics
~20 sAcross the module boundary the app cannot see the generic body, so it calls one unspecialized entry point that receives type metadata and witness tables. @inlinable publishes the body for client specialization; @usableFromInline lets that body call internal helpers.
solid answer
~40 sInside the framework the optimizer sees the generic body and the concrete type, so it emits a specialized copy with direct calls. From the app it sees only the declaration, and a framework built with library evolution exposes no bodies except `@inlinable` ones, so every call goes to the one unspecialized entry point, which receives the type's metadata and witness tables and reaches each operation indirectly. `@inlinable` serializes the body into the module's interface so the client's optimizer **may** specialize or inline it; it is permission, not a guarantee. That body may reference only ABI-public declarations, so the internal helpers it calls need `@usableFromInline`, which exports their symbols without making them visible to client source. Verify in a Release build: the specialized loop should appear in the app's code, not the framework's generic symbol.
code
swift · 18 lines// Framework module JSONKit, built with -enable-library-evolution
public protocol TokenSink {
mutating func accept(_ byte: UInt8)
}
@usableFromInline
func isStructural(_ b: UInt8) -> Bool {
b == 0x7B || b == 0x7D || b == 0x5B || b == 0x5D || b == 0x3A || b == 0x2C
}
public func scanOpaque<S: TokenSink>(_ bytes: [UInt8], into sink: inout S) {
for b in bytes where isStructural(b) { sink.accept(b) }
}
@inlinable
public func scan<S: TokenSink>(_ bytes: [UInt8], into sink: inout S) {
for b in bytes where isStructural(b) { sink.accept(b) }
}go deeper
Recall that a generic function can run as one shared version or as a copy specialized for a concrete type, and that the specialized copy is faster.
Explain what the unspecialized body receives, type metadata and witness tables, and why the optimizer needs the body and the concrete type together to specialize.
Diagnose the boundary: library evolution hides bodies, @inlinable exposes them, @usableFromInline makes helpers ABI-public. Prove the fix in a Release profile or the client's SIL.
Treat each @inlinable as a published promise: bodies ship inside clients and helpers become permanent ABI, so limit it to small, stable, measured-hot generic entry points.
## One body, many types Swift compiles a generic function once, as a shared body that works for any type. Each call passes extra hidden arguments: the **type metadata** for each generic parameter (size, alignment, how to copy and destroy a value) and a **witness table** for each protocol conformance, the table of function pointers that implements the protocol's requirements for that type. Inside the shared body every `sink.accept(b)` is an indirect call through the witness table, and values of the generic type are moved through memory rather than registers. When the optimizer can see both the body and the concrete type at a call site, it emits a **specialized** copy, for example `scan<Counter>`, in which the generic parameter is replaced by `Counter`. The indirect calls become direct calls, which can then be inlined, and the loop can be optimized like hand-written code. The standard library's own generic algorithms, such as `map` on `Sequence`, are written to be specialized in your module for exactly this reason. ## Why the module boundary stops it Specialization needs the body, and a body is not always visible: - **Same file:** always visible. - **Same module, other files:** visible when the module is compiled as a whole (whole-module optimization), which Release builds normally do. - **Another module built from source with the app:** sometimes. Swift Package Manager enables a conservative form of **cross-module optimization** by default, which makes mainly public function bodies available to clients; a hand-written `swiftc` build needs a flag such as `-cross-module-optimization`. - **A binary framework built with library evolution** (`-enable-library-evolution`, Xcode's Build Libraries for Distribution): clients see only declarations, plus the bodies of `@inlinable` declarations. Library evolution exists so the framework can change implementations without clients recompiling, so hiding bodies is the point. So a benchmark compiled inside the framework module runs specialized code, while the app's call goes through the generic entry point. Time Profiler in the app shows time in the framework's generic symbol and in the witness-table calls back into your type. ## What @inlinable does `@inlinable` on a `public` (or `internal`) function, method, initializer, subscript or computed property makes its body part of the module's public interface: it is written into the `.swiftinterface` file and the binary module. A client's optimizer may then: 1. inline the body at the call site, 2. emit a specialized copy in the client, or 3. ignore it and call the framework's exported symbol, which still exists. The name over-promises: nothing forces inlining. What it guarantees is visibility. The price is that the body is now compiled into clients, so a later change to it reaches a client only when that client is rebuilt. Two further restrictions follow from the body being compiled elsewhere. An inlinable body cannot declare a local type (Swift 6.4 says the type "cannot be nested inside an '@inlinable' function"), because a type must have one identity across every binary that might inline it. And under library evolution an `@inlinable` initializer of a resilient struct must delegate with `self.init(...)` instead of assigning stored properties directly, since clients do not know the struct's layout. Local functions and closures inside the body are likewise emitted into each client that inlines it. ## What @usableFromInline does An inlinable body is compiled in other modules, so it may reference only **ABI-public** declarations: `public` ones, or `internal` ones marked `@usableFromInline` (or `@inlinable`). Calling an ordinary internal helper is a compile error. `@usableFromInline` exports the helper's symbol so inlined code in a client can call it, while it stays invisible to client source and its own body stays private. In the example, the app's specialized loop still makes a real call to `isStructural`; mark that helper `@inlinable` too if it is hot. Rules worth knowing: - It applies only to `internal` or `package` declarations; `private`, `fileprivate` and `public` ones are rejected. - On a declaration that is already `@inlinable` it is redundant, and the compiler warns. - Once shipped, a `@usableFromInline` declaration is ABI: an old client's inlined code may call it, so you cannot delete it. ## Verifying the fix 1. Build the framework for distribution and the app in Release. 2. Profile the app's decode path with Time Profiler; the hot frames should now be in the app's own code, not the framework's generic function. 3. For certainty, emit the client's intermediate language with `swiftc -O -emit-sil` and check that the call to the generic entry point is gone. 4. Mark only the hot, small, stable generic entry points; every `@inlinable` body becomes a promise to every client.
- Why did the same slowdown not appear when the code was a Swift package built from source with the app?Built from source without library evolution, the package's bodies can reach the app: Swift Package Manager enables a conservative cross-module optimization by default, which exposes mainly public function bodies to clients. A binary framework built with library evolution exposes only `@inlinable` bodies, so the client has nothing to specialize.
- Does @inlinable make the client inline the function?No. It makes the body available. The client's optimizer may inline it, emit a specialized out-of-line copy, use it only for analysis, or ignore it and call the framework's exported symbol. The attribute's real effect is visibility; inlining policy is a separate question, answered by the `@inline` attribute family.
- Which declarations can take @usableFromInline?Only `internal` or `package` ones. Swift 6.4 rejects it on `private`, `fileprivate` and `public` declarations with "'@usableFromInline' attribute can only be applied to internal or package declarations". On an internal declaration that is already `@inlinable` it has no effect and draws a warning, because `@inlinable` already makes it ABI-public.
- Swift always specializes generics at compile time, so generic calls are free.
- @inlinable forces the compiler to inline every call site.
- Making the helper public is the only way an @inlinable body can call it.
- @usableFromInline also copies the helper's body into client modules.
- Turning on whole-module optimization in the app specializes the framework's generics.