ktor-client-core/io.ktor.client.engine/HttpClientEngineFactory/create

create

abstract fun create(block: T.() -> Unit = {}): HttpClientEngine

Creates or retrieves an instance of HttpClientEngine, applying optional configurations.

This method is responsible for deciding whether to create a new engine instance or reuse an existing one, based on the factory's internal logic and the configuration provided in the block. This allows for efficient resource management by avoiding unnecessary engine instantiation when possible.

The block parameter enables users to customize the engine's T configuration during creation. If no block is provided, the factory should apply default configurations or reuse an engine with the default settings.

Typically, this method is invoked internally by the io.ktor.client.HttpClient constructor when the factory is passed to it. Users can, however, call it directly to explicitly control engine instantiation.

Return

An HttpClientEngine instance, which may be newly created or reused.

Example with explicit engine creation:

val engine = MyCustomEngineFactory.create {
    timeout = 5_000
    customHeader = "example"
}

Example when used with HttpClient:

val client = HttpClient(MyCustomEngineFactory) {
    engine {
        timeout = 5_000
        customHeader = "example"
    }
}

Contracts for Implementors:

If reusing an existing engine, ensure its configuration matches the one provided in block.
Ensure thread safety when managing a shared engine instance across multiple create calls.
Provide meaningful default configurations when no block is provided.
Properly release resources of reused engines when the io.ktor.client.HttpClient] or engine is closed.

Parameters

block

A lambda that applies additional configurations to the engine's T object.