when to use an inline function in Kotlin?

Let’s say you create a higher order function that takes a lambda of type () -> Unit (no parameters, no return value), and executes it like so:

fun nonInlined(block: () -> Unit) {
    println("before")
    block()
    println("after")
}

In Java parlance, this will translate to something like this (simplified!):

public void nonInlined(Function block) {
    System.out.println("before");
    block.invoke();
    System.out.println("after");
}

And when you call it from Kotlin…

nonInlined {
    println("do something here")
}

Under the hood, an instance of Function will be created here, that wraps the code inside the lambda (again, this is simplified):

nonInlined(new Function() {
    @Override
    public void invoke() {
        System.out.println("do something here");
    }
});

So basically, calling this function and passing a lambda to it will always create an instance of a Function object.

On the other hand, if you use the inline keyword:

inline fun inlined(block: () -> Unit) {
    println("before")
    block()
    println("after")
}

When you call it like this:

inlined {
    println("do something here")
}

No Function instance will be created, instead, the code around the invocation of block inside the inlined function will be copied to the call site, so you’ll get something like this in the bytecode:

System.out.println("before");
System.out.println("do something here");
System.out.println("after");

In this case, no new instances are created.