PipelineDependenciesResolver.kt

package kotlin.script.dependencies.experimental

import kotlinx.coroutines.experimental.Unconfined
import kotlinx.coroutines.experimental.channels.ReceiveChannel
import kotlinx.coroutines.experimental.channels.produce
import kotlin.script.dependencies.Environment
import kotlin.script.dependencies.ScriptContents

interface PipelineDependenciesResolver : AsyncDependenciesResolver {

    /**
     * Starts resolution pipeline and returns output channel that client can read responses from.
     *
     * The resolver must take requests from the [input] channel and place matching responses in the output channel.
     *
     * Only the most recent request for a particular script (as identified by `script.file`) is guaranteed to get
     * a matching response to allow for debouncing.
     *
     * A single request can yield multiple responses so as to allow the resolver to react to changes in the external environment.
     *
     * The client *must* close the given [input] channel when no more requests are to be expected to allow for the disposal of resources.
     *
     * The coroutine completes when the [input] channel is closed or when a fatal error occurs.
     */
    suspend fun startPipeline(input: ReceiveChannel<Request>): ReceiveChannel<Response>

    data class Request(
        /**
         * The contents of the script. `script.file` is *not guaranteed* to be in sync with `script.text`.
         */
        val script: ScriptContents,
        val environment: ScriptEnvironment
    )

    data class Response(

        /**
         * The request that caused this response.
         */
        val request: Request,

        /**
         * Contains ScriptDependencies and diagnostics
         */
        val result: ResolutionResult
    )

    suspend override fun resolveAsync(scriptContents: ScriptContents, environment: Environment): ResolutionResult {
        val request = Request(scriptContents, environment)
        val input = produce(Unconfined) {
            send(request)
            close()
        }
        val output = startPipeline(input)
        val response = output.receive()
        assert(response.request == request)
        return response.result
    }
}

startPipeline needs to also take the SendChannel as an argument otherwise the coroutine termination semantics cannot be honored:

• The coroutine completes when the [input] channel is closed or when a fatal error occurs.

Request should be an interface to allow for extra data to be stored in case the implementation requires it.

startPipeline should be called only once per process per Gradle distribution since it can handle multiple requests (and monitor external resources).

Request should be an interface to allow for extra data to be stored in case the implementation requires it.

We have environment in case we need to share additional information specific to an implementation. Is it not enough?

startPipeline should be called only once per process per Gradle distribution since it can handle multiple requests (and monitor external resources).

Is this regarding resolveAsync implementation? I think we need a clear way to conform to previous(simpler) versions of API because this is what compiler is going to call (and older versions of plugin as well). Would multiple calls of startPipeline be a problem?

When we release a plugin that supports that API it should call startPipeline once (and whenever it needs to restart the connection afterwards).

startPipeline needs to also take the SendChannel as an argument otherwise the coroutine termination semantics cannot be honored:

I need to try get a toy implementation of the API going to see if that would be a problem.

We have environment in case we need to share additional information specific to an implementation. Is it not enough?

Right.

Is this regarding resolveAsync implementation?

Yes, that's what triggered my comment about startPipeline.

Multiple calls wouldn't be a problem as long as the protocol is fully respected, termination semantics and all.