In Swift, how do @inlinable, @inline(__always), @inline(never) and Swift 6.3's @inline(always) differ, and which one guarantees a call is inlined?
answer
- visibility versus inlining policy
- underscored hint, no promise
- keep a cold path out of line
- direct calls only, errors otherwise
basics
~20 s@inlinable only exposes a body to other modules. @inline(__always) is an unenforced hint and @inline(never) blocks inlining. Swift 6.3's @inline(always) is the guarantee: direct calls are inlined even at -Onone, and declarations it cannot honour are rejected.
solid answer
~40 sThey answer different questions. `@inlinable` is about **visibility**: it puts a body in the module interface so clients may specialize or inline it. The `@inline` forms are **policy**. `@inline(never)` keeps a function out of line, which suits a cold error path. `@inline(__always)` is an underscored hint the optimizer may ignore; it is not honoured at `-Onone`, and on a `public` function it does not export the body, so other modules still cannot inline it. Swift 6.3's `@inline(always)` (SE-0496) is the enforced form: direct calls to free functions, struct, enum and actor methods and `final` class methods are inlined even at `-Onone`, a non-`final` class method is rejected, and on a `public` function it implies `@inlinable`. Calls through a protocol, an existential or a function value may still not be inlined.
code
swift · 15 lines@inline(always)
func lowNibble(_ b: UInt8) -> UInt8 { b & 0x0F }
@inline(__always)
func highNibble(_ b: UInt8) -> UInt8 { b >> 4 }
@inline(never)
func reportBadByte(_ b: UInt8) -> Never {
fatalError("unexpected byte \(b)")
}
public func classify(_ b: UInt8) -> UInt8 {
if b == 0xFF { reportBadByte(b) }
return lowNibble(b) &+ highNibble(b)
}go deeper
Recall what inlining is: replacing a call with the callee's body. Know that the compiler normally decides on its own in optimized builds.
Separate visibility from policy: @inlinable exposes a body to other modules, while the @inline forms tell the optimizer whether to inline a call it can see.
Explain what each attribute guarantees and where it stops: __always is a hint, always is enforced only for direct calls, never keeps cold paths out of hot loops.
Set a rule for library code: no inlining attributes without a profile, prefer @inline(always) over the underscored hint on Swift 6.3 toolchains, and review public bodies it exports as ABI.
## Two separate questions **Inlining** replaces a call with a copy of the callee's body, which removes call overhead and, more importantly, lets the optimizer simplify the combined code: constants propagate, branches disappear, values stay in registers. The Swift optimizer decides by heuristics, such as callee size and how hot the call looks, which can change between compiler releases. Inlining also matters for generics: once a generic callee is inlined into a caller that knows the concrete type, the inlined code is effectively specialized, which is why the visibility of a body and the decision to inline it are so often discussed together. They are still different decisions, and Swift's attributes split the topic in two: | Attribute | Controls | Enforced? | Effect across modules | |---|---|---|---| | `@inlinable` | Whether the body is visible to clients | Visibility only | Body published in the module interface | | `@inline(never)` | Inlining policy | Yes | None by itself | | `@inline(__always)` | Inlining policy | No, a hint | Does not publish the body | | `@inline(always)` (Swift 6.3) | Inlining policy | Yes, for direct calls | On `public`, `open` or `package` functions it implies `@inlinable` | Confusing visibility with policy is the usual mistake: `@inlinable` never forces inlining, and an `@inline` hint cannot inline a body the caller cannot see. ## @inline(never) and @inline(__always) `@inline(never)` tells the optimizer to keep the function as a real call. It is useful for a cold path, such as building an error message or reporting a bad byte, that would otherwise bloat a hot loop it is inlined into, and for keeping a function visible as its own frame in a profile. It does not change the function's access level or its symbol: other modules call it exactly as before. `@inline(__always)` predates Swift 6.3; its underscores mark it as unofficial, a directive that never went through Swift Evolution as a supported feature. It raises the optimizer's preference for inlining but is not enforced and not applied at every optimization level: in an `-Onone` build the call stays a call. It also does not imply `@inlinable`, so on a `public` function in a library it cannot help clients, which never see the body. ## @inline(always) in Swift 6.3 SE-0496 added `@inline(always)` as an optimization **control**: the author wants the body inlined into every direct caller, and the compiler either does it or reports an error. The rules follow from which calls are statically resolvable: - **Always inlined:** calls to free functions, to methods of structs, enums and actors, to `final` methods of classes and to `static` methods of classes, barring recursion, even in `-Onone` builds. - **Rejected at the declaration:** a non-`final` class method, because a subclass could override it and the compiler cannot promise which body runs; for a method `peek()`, Swift 6.4 reports "'@inline(always)' on class methods requires 'peek()' to be marked 'final'". - **Rejected as a cycle:** `@inline(always)` functions that call each other recursively. - **Not diagnosed, maybe not inlined:** calls through a protocol requirement, an existential, a generic constraint or a function value; the optimizer inlines them only if it can work out the callee. - **Implies `@inlinable`** on `public`, `open` and `package` functions, so the body follows every `@inlinable` rule and may reference only ABI-public declarations; combining it with `@usableFromInline` is an error. ## Across a module boundary For a framework, the decisive question is still visibility. A client can inline only a body it can see, so: 1. `@inline(__always)` alone on a `public` function: clients call the exported symbol. 2. `@inlinable`: clients may inline or specialize, at their optimizer's discretion. 3. `@inline(always)` on a `public` function: the body is exported and direct calls in every client are inlined. The third option is the strongest commitment, because the body is then compiled into every client and changes reach them only when they rebuild. ## When to reach for each - Leave most code alone; the optimizer's heuristics are usually right, and inlining grows code size. - Use `@inline(never)` to keep a cold path out of a hot loop or to keep a function visible in a profile. - Use `@inlinable` for small, stable, generic library entry points that clients need to specialize. - Use `@inline(always)` only where a Release profile shows a direct call that the heuristics did not inline and that matters, and prefer it to `@inline(__always)` in new code built with Swift 6.3 or later, because its failures are diagnosed instead of silent.
- Why is @inline(always) rejected on a non-final class method?A call through a class reference is dispatched on the object's dynamic type, and a subclass can override the method, so the compiler cannot promise which body a call site runs. SE-0496 makes that a declaration-site error rather than a silent miss. Mark the method `final`, or move it to a struct, and direct calls inline.
- Should a team put @inline(always) on every hot helper?No, only where a profile proves it. Every inlined copy grows code size, which can cost instruction-cache misses and binary size, and on a `public` function the attribute also exports the body, so clients compile your implementation into themselves. The heuristics are usually right; reserve the attribute for measured misses.
- @inlinable guarantees the function is inlined at every call site.
- @inline(__always) is enforced at every optimization level, including -Onone.
- @inline(__always) on a public function lets other modules inline it.
- @inline(always) also guarantees inlining through a protocol existential.
- Swift's optimizer never inlines a function unless it carries an inlining attribute.
Assumes Swift 6.4; @inline(always) arrived in Swift 6.3 (SE-0496), while @inlinable, @inline(__always) and @inline(never) work in every supported release.