| ... | @@ -2934,8 +2934,8 @@ or | ... | @@ -2934,8 +2934,8 @@ or |
| 2934 | {#header_open|inline fn#} | 2934 | {#header_open|inline fn#} |
| 2935 | <p> | 2935 | <p> |
| 2936 | Adding the {#syntax#}inline{#endsyntax#} keyword to a function definition makes that | 2936 | Adding the {#syntax#}inline{#endsyntax#} keyword to a function definition makes that |
| 2937 | function become <em>semantically inlined</em> at the callsite. This is | 2937 | function become <em>semantically inlined</em> at the callsite. {#link|Inline Is Not A Hint#} |
| 2938 | not a hint to be possibly observed by optimization passes, but has | 2938 | to be possibly observed by optimization passes, but has |
| 2939 | implications on the types and values involved in the function call. | 2939 | implications on the types and values involved in the function call. |
| 2940 | </p> | 2940 | </p> |
| 2941 | <p> | 2941 | <p> |
| ... | @@ -2947,16 +2947,22 @@ or | ... | @@ -2947,16 +2947,22 @@ or |
| 2947 | | 2947 | |
| 2948 | <p>If {#syntax#}inline{#endsyntax#} is removed, the test fails with the compile error | 2948 | <p>If {#syntax#}inline{#endsyntax#} is removed, the test fails with the compile error |
| 2949 | instead of passing.</p> | 2949 | instead of passing.</p> |
| 2950 | <p>It is generally better to let the compiler decide when to inline a | 2950 | |
| 2951 | function, except for these scenarios:</p> | 2951 | {#header_open|Inline Is Not A Hint#} |
| | 2952 | <p>Use of {#syntax#}inline{#endsyntax#} <em>restricts</em> what the |
| | 2953 | compiler is allowed to do. <strong>This can harm binary size, compilation speed, |
| | 2954 | and even runtime performance.</strong> In exchange, these use cases are addressed:</p> |
| 2952 | <ul> | 2955 | <ul> |
| 2953 | <li>To change how many stack frames are in the call stack, for debugging purposes.</li> | 2956 | <li>Ability to ensure certain stack frames are in the call stack, for |
| 2954 | <li>To force comptime-ness of the arguments to propagate to the return value of the function, as in the above example.</li> | 2957 | debugging purposes, or for integrating with {#link|Assembly#}.</li> |
| 2955 | <li>Real world performance measurements demand it.</li> | 2958 | <li>Forcing arguments from the callsite that happen to be |
| | 2959 | {#link|comptime#} to propagate to the return value of the function, as |
| | 2960 | in the above example.</li> |
| | 2961 | <li>Working around limitations of compiler backend implementations.</li> |
| 2956 | </ul> | 2962 | </ul> |
| 2957 | <p>Note that {#syntax#}inline{#endsyntax#} actually <em>restricts</em> | 2963 | <p>For an alternative to {#syntax#}inline{#endsyntax#} that merely hints to the compiler |
| 2958 | what the compiler is allowed to do. This can harm binary size, | 2964 | that inlining a function may be valuable, use {#link|@branchHint#}.</p> |
| 2959 | compilation speed, and even runtime performance.</p> | 2965 | {#header_close#} |
| 2960 | {#header_close#} | 2966 | {#header_close#} |
| 2961 | | 2967 | |
| 2962 | {#header_open|Function Reflection#} | 2968 | {#header_open|Function Reflection#} |
Andrew Kelley <andrew@ziglang.org> 2026-08-27 13:41:18-07:00