为了账号安全,请及时绑定邮箱和手机立即绑定

Kotlin Contract

标签:
Kotlin 源码

Kotlin 的智能推断是其语言的一大特色。

智能推断,能够根据类型检测自动转换类型。

但是,智能推断并没有想象中的强大,例如下面的代码就无法进行推断,导致编译失败:

fun String?.isNotNull():Boolean {
    return this!=null && this.isNotEmpty()
}

fun printLength(s:String?=null) {
    if (!s.isNotNull()) {
        println(s.length) // Only safe (?.) or non-null asserted (!!.) calls are allowed on a nullable receiver of type String?
    }

}

因为编译器在处理s.length时,会将 s 推断成value-parameter s: String? = ...并不是 String 类型。智能推断失效了,代码也无法编译。

对上述代码做如下修改,即可编译成功:

fun printLength(s:String?=null) {
    if (!s.isNullOrEmpty()) {
        println(s.length)
    }
}

isNullOrEmpty() 是 Kotlin 标准库中 String 的扩展函数,其源码:

@kotlin.internal.InlineOnly
public inline fun CharSequence?.isNullOrEmpty(): Boolean {
    contract {
        returns(false) implies (this@isNullOrEmpty != null)
    }

    return this == null || this.length == 0
}

我们会发现 isNullOrEmpty() 的源码中包含了contract函数,实际上它会告诉编译器当 isNullOrEmpty() 返回 false 时,则 isNullOrEmpty != null 成立,因此 printLength() 函数中的变量 s 不会为 null。

通过契约,开发者可以向编译器提供有关函数的行为,以帮助编译器对代码执行更完整的分析。

契约就像是开发者和编译器沟通的桥梁,但是编译器必须无条件地遵守契约。

一. Contract 的概念

Contract 是一种向编译器通知函数行为的方法。

Contract 是 Kotlin1.3 的新特性,在当前 Kotlin 1.4 时仍处于试验阶段。

二. Contract 的特性

  • 只能在 top-level 函数体内使用 Contract,不能在成员和类函数上使用它们。
  • Contract 所调用的声明必须是函数体内第一条语句。
  • 目前 Kotlin 编译器并不会验证 Contract,因此开发者有责任编写正确合理的 Contract。

在 Kotlin 1.4 中,对于 Contract 有两项改进:

  • 支持使用内联特化的函数来实现契约
  • Kotlin 1.3 不能为成员函数添加 Contract,从 Kotlin 1.4 开始支持为 final 类型的成员函数添加 Contract(当然任意成员函数可能存在被覆写的问题,因而不能添加)。

当前 Contract 有两种类型:

  • Returns Contracts
  • CallInPlace Contracts

2.1 Returns Contracts

Returns Contracts 表示当 return 的返回值是某个值(例如true、false、null)时,implies后面的条件成立。

Returns Contracts 有以下几种形式:

  • returns(true) implies
  • returns(false) implies
  • returns(null) implies
  • returns implies
  • returnsNotNull implies

其他几个类型按照字面意思很好理解,returns implies 怎么理解呢?

我们来看一下 Kotlin 的 requireNotNull() 函数的源码:

@kotlin.internal.InlineOnly
public inline fun  requireNotNull(value: T?): T {
    contract {
        returns() implies (value != null)
    }
    return requireNotNull(value) { "Required value was null." }
}

@kotlin.internal.InlineOnly
public inline fun  requireNotNull(value: T?, lazyMessage: () -> Any): T {
    contract {
        returns() implies (value != null)
    }

    if (value == null) {
        val message = lazyMessage()
        throw IllegalArgumentException(message.toString())
    } else {
        return value
    }
}

contract() 告诉编译器,如果调用 requireNotNull 函数后能够正常返回,且没有抛出异常,则 value 不为空。

因此,returns implies 表示当该函数正常返回时,implies后面的条件成立。

Contract 正是通过这种声明函数调用的结果与所传参数值之间的关系来改进 Kotlin 智能推断的效果。

2.2 CallInPlace Contracts

前面Kotlin 如何优雅地使用 Scope Functions曾介绍过 Scope Function,我们来回顾一下 let 函数的源码:

@kotlin.internal.InlineOnly
public inline fun  T.let(block: (T) -> R): R {
    contract {
        callsInPlace(block, InvocationKind.EXACTLY_ONCE)
    }
    return block(this)
}

contract() 中的 callsInPlace 会告知编译器,lambda 表达式 block 在 let 函数内只会执行一次。在 let 函数被调用结束后,block 将不再被执行。

callsInPlace() 允许开发者提供对调用的 lambda 表达式进行时间/位置/频率上的约束。

callsInPlace() 中的 InvocationKind 是一个枚举类,包含如下的枚举值:

  • AT_MOST_ONCE:函数参数将被调用一次或根本不调用。
  • EXACTLY_ONCE:函数参数将只被调用一次。
  • AT_LEAST_ONCE:函数参数将被调用一次或多次。
  • UNKNOWN:一个函数参数它可以被调用的次数未知。

Kotlin 的 Scope Function 都使用了上述 Contracts。

三. Contract 源码解析

Contract 采用 DSL 方式进行声明,我们来看一下 contract() 函数的源码:

@ContractsDsl
@ExperimentalContracts
@InlineOnly
@SinceKotlin("1.3")
@Suppress("UNUSED_PARAMETER")
public inline fun contract(builder: ContractBuilder.() -> Unit) { }

通过 ContractBuilder 构建了 Contract,其源码如下:

@ContractsDsl
@ExperimentalContracts
@SinceKotlin("1.3")
public interface ContractBuilder {
    /**
     * Describes a situation when a function returns normally, without any exceptions thrown.
     *
     * Use [SimpleEffect.implies] function to describe a conditional effect that happens in such case.
     *
     */
    // @sample samples.contracts.returnsContract
    @ContractsDsl public fun returns(): Returns

    /**
     * Describes a situation when a function returns normally with the specified return [value].
     *
     * The possible values of [value] are limited to `true`, `false` or `null`.
     *
     * Use [SimpleEffect.implies] function to describe a conditional effect that happens in such case.
     *
     */
    // @sample samples.contracts.returnsTrueContract
    // @sample samples.contracts.returnsFalseContract
    // @sample samples.contracts.returnsNullContract
    @ContractsDsl public fun returns(value: Any?): Returns

    /**
     * Describes a situation when a function returns normally with any value that is not `null`.
     *
     * Use [SimpleEffect.implies] function to describe a conditional effect that happens in such case.
     *
     */
    // @sample samples.contracts.returnsNotNullContract
    @ContractsDsl public fun returnsNotNull(): ReturnsNotNull

    /**
     * Specifies that the function parameter [lambda] is invoked in place.
     *
     * This contract specifies that:
     * 1. the function [lambda] can only be invoked during the call of the owner function,
     *  and it won't be invoked after that owner function call is completed;
     * 2. _(optionally)_ the function [lambda] is invoked the amount of times specified by the [kind] parameter,
     *  see the [InvocationKind] enum for possible values.
     *
     * A function declaring the `callsInPlace` effect must be _inline_.
     *
     */
    /* @sample samples.contracts.callsInPlaceAtMostOnceContract
    * @sample samples.contracts.callsInPlaceAtLeastOnceContract
    * @sample samples.contracts.callsInPlaceExactlyOnceContract
    * @sample samples.contracts.callsInPlaceUnknownContract
    */
    @ContractsDsl public fun  callsInPlace(lambda: Function, kind: InvocationKind = InvocationKind.UNKNOWN): CallsInPlace
}

returns()、returnsNotNull()、callsInPlace() 分别返回 Returns、ReturnsNotNull、CallsInPlace 对象。这些对象最终都实现了 Effect 接口:

@ContractsDsl
@ExperimentalContracts
@SinceKotlin("1.3")
public interface Effect

Effect 表示函数调用的效果。每当调用一个函数时,它的所有效果都会被激发。编译器将收集所有激发的效果以便于其分析。

目前 Kotlin 只支持有 4 种 Effect:

  • Returns: 表示函数成功返回,不会不引发异常。
  • ReturnsNotNull:表示函数成功返回不为 null 的值。
  • ConditionalEffect:表示一个效果和一个布尔表达式的组合,如果触发了效果,则保证为true。
  • CallsInPlace:表示对传递的 lambda 参数的调用位置和调用次数的约束。

四. 小结

Contract 是帮助编译器分析的一个很好的工具,它们对于编写更干净、更好的代码非常有帮助。在使用 Contract 的时候,请不要忘记编译器不会去验证 Contract。

点击查看更多内容
1人点赞

若觉得本文不错,就分享一下吧!

评论

作者其他优质文章

正在加载中
全栈工程师
手记
粉丝
1.7万
获赞与收藏
594

关注作者,订阅最新文章

阅读免费教程

感谢您的支持,我会继续努力的~
扫码打赏,你说多少就多少
赞赏金额会直接到老师账户
支付方式
打开微信扫一扫,即可进行扫码打赏哦
今天注册有机会得

100积分直接送

付费专栏免费学

大额优惠券免费领

立即参与 放弃机会
意见反馈 帮助中心 APP下载
官方微信

举报

0/150
提交
取消