Inlining manifesto

[kyouko-taiga]

This document describes the design I have in mind for the inlining feature(s) of Hylo. Because inlining relates to resilience and visibility, the document also touches on my vision for Hylo's access control system.

Goals

• Simplicity: the system should have a small API surface.
• Predictability: it should be as straightforward as possible to predict when inlining will occur.
• Progressive disclosure: it should be possible to ignore the feature and yet obtain efficient code in optimized builds in general.

Definitions

A resilience boundary describes a conceptual boundary between two sets of symbols. The definition (e.g., contents of a function) of a symbol from one side of the boundary is not visible from the other side of the boundary. As a consequence, one cannot (in general) inline the contents of a function or determine the memory footprint of a type defined across a resilience boundary.

Note: In the context of Hylo, a resilience boundary is typically raised around the symbols of a module when that module is compiled with resilience enabled. We reserve the option to introduce other means to define resilience boundaries in the future.

A symbol is exposed if its declaration is accessible across a resilience boundary, or if it has been exposed explicitly with an annotation.

Note: intuitively, exposed symbols include those defined at the top level of a module and symbols whose qualification is also exposed.

A symbol is inlineable if its definition can be accessed across a resilience boundary. Inlineability imposes that the definition of the symbol itself can only refer to exposed symbols.

Access control

By default, all symbols in Hylo are private to the file in which they have been defined. This default can be overridden with the access modifier public, which makes a symbol accessible from outside the scope of its definition. The access modifier internal as the same effect as public except that it does not expose symbols.

The following illustrates. We assume that m0.a.hylo and m0.b.hylo are sources files in some module M, and that m1.hylo is a source file in some other module.

// --- m0.a.hylo ---

public struct A {
  public fun f() {}
  internal fun g() {}
  fun h() {}
}

fun foo(a: A) {
  a.f() // OK
  a.g() // OK
  a.h() // OK
}

// --- m0.b.hylo ---

fun bar(a: A) {
  a.f() // OK
  a.g() // OK
  a.h() // error: 'h' is not accessible here
  foo() // error: 'foo' is not accessible here
}

// --- m1.hylo ---

import M

fun ham(a: A) {
  a.f() // OK
  a.g() // error: 'g' is not accessible here
  a.h() // error: 'h' is not accessible here
  foo() // error: 'foo' is not accessible here
}

Note: intuitively, a symbol is exposed iff it is public and all the scopes in which it is enclosed are public as well.

Inlining

By default, the compiler inlines definitions in optimized builds according to some unspecified heuristics, if possible. No definition is inlined in debug builds by default. This behavior can be overridden with the following annotations:

• @inline(never): specifies that a function should never be inlined.
• @inline (short for @inline(always)): specifies that a function must be inlined.

A symbol may have only one occurrence of the annotation @inline(policy).

@inline(always) imposes a requirement on the symbol's definition, meaning that the compiler will emit an error diagnostic if that requirement cannot be upheld. Specifically, @inline(always) requires that:

• the function is not recursive; and
• if the function is exposed, then it is also inlineable.

The following illustrates:

// OK
@inline public fun foo() -> Int { 1 + 1 }
// OK
@inline fun bar() -> Int { 1 + 1 }
// OK
@inline public fun ham() -> Int { foo() }
// error: 'bar' is not exposed
@inline public fun zim() -> Int { bar() }

Relationship to monomorphization

Inlining does not mandate monomorphization. Nonetheless, the definition of a generic function declared with @inline(always) will be inlined, whether it is existentialized or monomorphized.

In the future, we could introduce other annotations controlling monomorphization in a similar fashion as inlining:

• @monomorphize(never) would specifiy that the function/type must be existentialized.
• @monomorphize(always) would specify that the function/type must be monomorphized.

Note that @monomorphize(policy) and @inline(policy) would be orthogonal in this hypothetical system.

Exposure

It may be desirable to allow or mandate the inlining of a function across a resilience boundary even if it uses symbols that are not exposed. In this case, one can use the annotation @exposed to specify that a symbol may be used from an inlined definition, regardless of its accessibility.

@exposed imposes a requirement on the symbol's definition, meaning that the compiler will emit an error diagnostic if that requirement cannot be upheld.

To illustrate, we can modify the previous example to mandate the inlining of zim:

@exposed @inline fun bar() -> Int { 1 + 1 }
@inline public fun zim() -> Int { bar() }

Note: @inline(always) does not imply inlineability; it only requires it.

Note: @inline(always) does not mandate exposure, and vice versa.

The annotation @exposed also applies on struct and enum declarations, specifying that their layout is visible across function boundaries. Again, the annotation imposes a requirement that is verified by the compiler. Specifically, all stored properties of a type introduced by an exposed declaration must be exposed.

Transparency

The annotation @transparent specifies that a function must be inlined and debugging should skip over its definition when stepping through the calling function.

Note: @transparent implies @inline(always).

[tothambrus11]

Very nice definitions! The use case for @exposed also came up for me while reading the document, though initially I had a different idea for solving this:

• internal @inline functions can be only inlined within the resilience boundary
• public @inline functions must expose their definition already fully inlined as much as possible, so when compiling the caller's module, they only need to inline one layer and not recurse into inlining subcalls.

On a second thought, I don't think this is desirable, as it can expose non-public implementation details through a backdoor/trampoline. So @exposed has the correct semantics.

Non-transitive inlining

I'm not sure if the use case is really useful for optimizations, but I can also imagine that we want to inline a function on its first 1-2 layers, but preserve some leaf calls as non-inlined. This could allow using public&inline(never)functions from public @inline functions, with the caveat that inlining would skip inlining that particular call. To force a transitively deeply inlinable call, we could have another annotation that makes the expectations stricter for the definition.