Встроенные функции

noinline

Если вы не хотите, чтобы все лямбда-выражения, передаваемые встраиваемой функции, встраивались, пометьте некоторые параметры вашей функции модификатором noinline:

inline fun foo(inlined: () -> Unit, noinline notInlined: () -> Unit) { ... }

Встраиваемые лямбда-выражения могут вызываться только внутри встраиваемых функций или передаваться как встраиваемые аргументы. noinline лямбда-выражения, однако, могут обрабатываться любым способом, включая хранение в полях или передачу.

Нелокальные возвраты

В Kotlin вы можете использовать только обычный, неквалифицированный return для выхода из именованной функции или безымянной функции. Для выхода из лямбда-выражения используйте метку. Голый return запрещён внутри лямбда-выражения, потому что лямбда-выражение не может заставить окружающую функцию return:

fun ordinaryFunction(block: () -> Unit) {
    println("hi!")
}
//sampleStart
fun foo() {
    ordinaryFunction {
        return // ERROR: cannot make `foo` return here
    }
}
//sampleEnd
fun main() {
    foo()
}

Но если функция, которой передаётся лямбда-выражение, встраивается, возврат также может быть встроен. Поэтому это разрешено:

inline fun inlined(block: () -> Unit) {
    println("hi!")
}
//sampleStart
fun foo() {
    inlined {
        return // OK: the lambda is inlined
    }
}
//sampleEnd
fun main() {
    foo()
}

Такие возвраты (расположенные в лямбда-выражении, но выходящие из окружающей функции) называются нелокальными возвратами. Этот тип конструкций обычно встречается в циклах, которые часто содержат встроенные функции:

fun hasZeros(ints: List<Int>): Boolean {
    ints.forEach {
        if (it == 0) return true // returns from hasZeros
    }
    return false
}

Обратите внимание, что некоторые встроенные функции могут вызывать передаваемые в них в качестве параметров лямбда-выражения не напрямую из тела функции, а из другой области выполнения, например, из локального объекта или вложенной функции. В таких случаях нелокальное управление потоком также запрещено в лямбда-выражениях. Чтобы указать, что параметр лямбда-выражения встраиваемой функции не может использовать нелокальные возвраты, пометьте параметр лямбда-выражения модификатором crossinline:

inline fun f(crossinline body: () -> Unit) {
    val f = object: Runnable {
        override fun run() = body()
    }
    // ...
}

Реифицированные параметры типа

Иногда вам нужно получить доступ к типу, переданному в качестве параметра:

fun <T> TreeNode.findParentOfType(clazz: Class<T>): T? {
    var p = parent
    while (p != null && !clazz.isInstance(p)) {
        p = p.parent
    }
    @Suppress("UNCHECKED_CAST")
    return p as T?
}

Здесь вы поднимаетесь по дереву и используете рефлексию для проверки, содержит ли узел определённый тип. Всё хорошо, но место вызова не очень приятное:

treeNode.findParentOfType(MyTreeNode::class.java)

Лучшим решением было бы просто передать тип в эту функцию. Вы можете вызвать её следующим образом:

treeNode.findParentOfType<MyTreeNode>()

Для этого встроенные функции поддерживают реифицированные параметры типа, поэтому вы можете написать что-то вроде этого:

inline fun <reified T> TreeNode.findParentOfType(): T? {
    var p = parent
    while (p != null && p !is T) {
        p = p.parent
    }
    return p as T?
}

В приведенном выше коде параметр типа квалифицируется модификатором reified для того, чтобы он стал доступен внутри функции, практически так же, как и обычный класс. Поскольку функция встроенная, рефлексия не нужна, и теперь доступны обычные операторы, такие как !is и as. Кроме того, вы можете вызвать функцию, как показано выше: myTree.findParentOfType<MyTreeNodeType>().

Хотя рефлексия может не потребоваться во многих случаях, её можно использовать с реифицированным параметром типа:

inline fun <reified T> membersOf() = T::class.members

fun main(s: Array<String>) {
    println(membersOf<StringBuilder>().joinToString("\n"))
}

Обычные функции (не помеченные как встроенные) не могут иметь реифицированные параметры. Тип, у которого нет представления во время выполнения (например, параметр типа, не реифицированный, или фиктивный тип, такой как Nothing), не может использоваться в качестве аргумента для реифицированного параметра типа.

Встроенные свойства

Модификатор inline можно использовать для аксессоров свойств, у которых нет полей-хранилищ. Вы можете аннотировать отдельные аксессоры свойств:

val foo: Foo
    inline get() = Foo()

var bar: Bar
    get() = ...
    inline set(v) { ... }

Вы также можете аннотировать всё свойство, что отмечает оба его аксессора как inline:

inline var bar: Bar
    get() = ...
    set(v) { ... }

В месте вызова встроенные аксессоры встраиваются как обычные встроенные функции.

Ограничения для встраиваемых функций публичного API

Когда встроенная функция является частью публичного API модуля, но не является частью объявления private или internal, она считается публичным API модуля. Её можно вызывать из других модулей, и она также встраивается в таких местах вызова.

Это создаёт определённые риски бинарной несовместимости, вызванные изменениями в модуле, который объявляет встроенную функцию, в случае, если вызывающий модуль не перекомпилируется после изменения.

Чтобы устранить риск такой несовместимости, вносимой изменением в не-публичного API модуля, встроенные функции публичного API не допускают использования объявлений не-публичного API, то есть private и internal объявлений и их частей, в своих телах.

Объявление internal может быть аннотировано @PublishedApi, что позволяет использовать его во встроенных функциях публичного API. Когда встроенная функция internal помечена как @PublishedApi, её тело проверяется тоже, как если бы оно было публичным.