Sets of members

A module can gather some of its members into a Set, such as every service that has to be started when the application starts. You mark the members with an annotation of your own, and the processor generates a function returning all of them.

Declaring a set

A set is an annotation class annotated with @DISet, which names the type of its elements:

AppModule.kt
interface Service {
    fun start()
}

@DISet(of = Service::class) (1)
annotation class Services

@DIModule(sets = [Services::class]) (2)
interface AppModule {
    @Services val database: Database (3)
    @Services val server: HttpServer
    @Services fun scheduler(): Scheduler? = null (4)
    val port: Int
}
1 Every member of the Services set must be a Service.
2 The module generates a function for every set it lists in sets.
3 Database, HttpServer and Scheduler all implement Service.
4 A member of a set may be nullable: null is left out of the set.

The processor generates an extension function named setOf followed by the name of the annotation:

InaraAppModule.kt
public fun AppModule.setOfServices(): Set<Service>

It reads each member off the module, so the set always holds what the module’s bindings currently provide:

val app = AppModule(
    database = Binding.single { Database() },
    server = Binding.single { HttpServer(port) },
    port = Binding.value(8080),
)

app.setOfServices().forEach { it.start() } (1)
1 Starts the database and the server: scheduler() keeps its default implementation, which returns null.

The function has the visibility of the module: an internal module gets an internal function.

What a set holds

A set holds every member of the module that carries its annotation, inherited members included, in the order the module declares them: inherited members first, in the order of the supertypes, then the module’s own.

Since the result is a Set, two members that provide the same value, or two equal values, appear in it once.

A member also belongs to a set when the annotation is on a declaration it overrides. Kotlin does not carry an annotation over to an override, but Inara does:

interface ServiceHolder {
    @Services val service: Service
}

interface ServerHolder : ServiceHolder {
    override val service: HttpServer (1)
}
1 Still a member of Services, without repeating the annotation.

A function is called without arguments, so all of its parameters must have a default value or be vararg. A default value declared on an overridden declaration counts, since an override cannot declare one of its own.

A member may belong to several sets, by carrying several set annotations.

Gathering the members of descendants

The function always answers for the module it is called on. Called on a module that extends the one listing the set, it collects the members of that module too, even when the module is typed as its ancestor:

@DIModule
interface ServerAppModule : AppModule {
    @Services val metrics: MetricsReporter
}

val asAppModule: AppModule = serverApp
asAppModule.setOfServices() // database, server and metrics, plus scheduler if it is not null

A module may therefore list a set that none of its own members belongs to, as the place where the members of its descendants are gathered. A framework can list the set on the module its code receives, and let every module of the application contribute:

@DIModule(sets = [Services::class])
interface FrameworkModule {
    val config: FrameworkConfig
}

fun boot(module: FrameworkModule) {
    module.setOfServices().forEach { it.start() } (1)
}
1 Every @Services member of the module given to boot, whichever library it comes from.

Listing an inherited set again in sets is allowed, and changes nothing.

An annotated member does not require its module to list the set: a parent can annotate its members, and leave it to the modules extending it to gather them. This is how a composed module gathers the members of the modules it is built from, partial modules included:

@DIModule
interface DatabaseModule {
    @Services val database: Database
}

@DIModule
interface ServerModule {
    @Services val server: HttpServer
}

@DIModule(composed = true, sets = [Services::class])
interface ApplicationModule : DatabaseModule, ServerModule
A module that you implement by hand, rather than build with its generated builder, only answers with the members of the module listing the set.

Asynchronous members

By default, the generated function is not suspend, and no suspend member may belong to the set. Pass suspend = true to @DISet to make it suspend, and allow suspend members:

@DISet(of = Service::class, suspend = true)
annotation class RemoteServices

The set decides, never its members: the function is declared on the module listing the set, while the members it collects may come from modules extending it, compiled later.

Generic element types

A generic element type is star-projected:

interface Plugin<C>

@DISet(of = Plugin::class)
annotation class Plugins (1)
1 setOfPlugins() returns a Set<Plugin<*>>, which holds a Plugin<String> as well as a Plugin<Int>.

Restrictions

The processor rejects a set annotation that:

  • has a SOURCE retention, which would hide it on the members of a module compiled in another Gradle module;

  • declares a @Target that includes neither FUNCTION nor PROPERTY;

  • names an of type that is neither public nor internal, or that is declared inside a declaration that is neither.

It rejects a sets argument that:

  • lists an annotation that is not annotated with @DISet, or lists the same annotation twice;

  • gives the module two sets with the same simple name, since both would generate the same function;

  • gives the module a set whose function would have the name of one of its members, which would hide it;

  • gives a public module a set whose of type is internal, or whose of type is internal to another Gradle module.

It rejects a member that carries a set annotation, directly or through a declaration it overrides, when it is:

  • ignored by Inara: a var, an extension member, or a generic function;

  • a function that cannot be called without arguments;

  • of a type that is not a subtype of the set’s of type, nullability aside;

  • suspend, while the set is not @DISet(suspend = true).

Finally, a set annotation may only annotate a function or a property declared in an interface, and never a private one.

Changing a set

The code generated for a module lists the members of its sets, inherited ones included, as they are when it is compiled. Adding a member to a set, or removing one, is therefore a change to the module’s binary interface, like adding a member: every module extending it must be recompiled to see it.

Gradle does so when it builds your application, since the classpath changed. Only a module published in a library, then used with a newer version of a module it extends, can miss the change: see multi-module projects.

A set of AutoCloseable members closes every resource of a module at once, for instance in the ApplicationStopped event of the Ktor guide.