0
# Daemon Connection Management
1

2
Core functionality for finding, connecting to, and managing Kotlin compiler daemon processes. This includes daemon discovery, startup, connection lifecycle management, and session handling.
3

4
## Capabilities
5

6
### Connect to Compile Service
7

8
Connects to an existing Kotlin compiler daemon or starts a new one if needed.
9

10
```kotlin { .api }
11
/**
12
 * Connect to a Kotlin compiler daemon service
13
 * @param compilerId Identifies the compiler version and classpath
14
 * @param daemonJVMOptions JVM configuration for the daemon
15
 * @param daemonOptions Daemon-specific configuration options
16
 * @param reportingTargets Where to send diagnostic and status messages
17
 * @param autostart Whether to start a new daemon if none found
18
 * @param checkId Whether to verify compiler ID matches
19
 * @return CompileService instance or null if connection failed
20
 */
21
fun connectToCompileService(
22
    compilerId: CompilerId,
23
    daemonJVMOptions: DaemonJVMOptions,
24
    daemonOptions: DaemonOptions,
25
    reportingTargets: DaemonReportingTargets,
26
    autostart: Boolean = true,
27
    checkId: Boolean = true
28
): CompileService?
29
```
30

31
**Usage Example:**
32

33
```kotlin
34
import org.jetbrains.kotlin.daemon.client.KotlinCompilerClient
35
import org.jetbrains.kotlin.daemon.common.*
36

37
val compilerId = CompilerId().apply {
38
    compilerClasspath = listOf("/path/to/kotlin-compiler.jar")
39
}
40

41
val daemonJVMOptions = DaemonJVMOptions().apply {
42
    maxMemory = "2g"
43
    maxPermSize = "512m"
44
}
45

46
val daemonOptions = DaemonOptions().apply {
47
    runFilesPath = "/tmp/kotlin-daemon"
48
}
49

50
val reportingTargets = DaemonReportingTargets(out = System.out)
51

52
val compileService = KotlinCompilerClient.connectToCompileService(
53
    compilerId = compilerId,
54
    daemonJVMOptions = daemonJVMOptions,
55
    daemonOptions = daemonOptions,
56
    reportingTargets = reportingTargets,
57
    autostart = true
58
)
59
```
60

61
### Connect with Client Flag File
62

63
Connects to daemon using an explicit client alive flag file for process lifecycle management.
64

65
```kotlin { .api }
66
/**
67
 * Connect to daemon with explicit client flag file
68
 * @param compilerId Compiler identification
69
 * @param clientAliveFlagFile File indicating client is alive
70
 * @param daemonJVMOptions JVM options for daemon
71
 * @param daemonOptions Daemon configuration
72
 * @param reportingTargets Diagnostic reporting targets
73
 * @param autostart Whether to start daemon if not found
74
 * @return CompileService instance or null
75
 */
76
fun connectToCompileService(
77
    compilerId: CompilerId,
78
    clientAliveFlagFile: File,
79
    daemonJVMOptions: DaemonJVMOptions,
80
    daemonOptions: DaemonOptions,
81
    reportingTargets: DaemonReportingTargets,
82
    autostart: Boolean = true
83
): CompileService?
84
```
85

86
### Connect and Lease Session
87

88
Connects to daemon and optionally leases a compilation session for exclusive use.
89

90
```kotlin { .api }
91
/**
92
 * Connect to daemon and lease a compilation session
93
 * @param compilerId Compiler identification
94
 * @param clientAliveFlagFile Client lifecycle flag file
95
 * @param daemonJVMOptions JVM configuration
96
 * @param daemonOptions Daemon configuration
97
 * @param reportingTargets Diagnostic targets
98
 * @param autostart Whether to start daemon automatically
99
 * @param leaseSession Whether to lease an exclusive session
100
 * @param sessionAliveFlagFile Session lifecycle flag file
101
 * @return CompileServiceSession with service and session ID
102
 */
103
fun connectAndLease(
104
    compilerId: CompilerId,
105
    clientAliveFlagFile: File,
106
    daemonJVMOptions: DaemonJVMOptions,
107
    daemonOptions: DaemonOptions,
108
    reportingTargets: DaemonReportingTargets,
109
    autostart: Boolean,
110
    leaseSession: Boolean,
111
    sessionAliveFlagFile: File? = null
112
): CompileServiceSession?
113
```
114

115
### Daemon Shutdown
116

117
Shuts down a running Kotlin compiler daemon.
118

119
```kotlin { .api }
120
/**
121
 * Shutdown a compiler daemon
122
 * @param compilerId Identifies which daemon to shut down
123
 * @param daemonOptions Daemon configuration for finding the daemon
124
 */
125
fun shutdownCompileService(compilerId: CompilerId, daemonOptions: DaemonOptions): Unit
126

127
/**
128
 * Shutdown daemon with default options
129
 * @param compilerId Identifies which daemon to shut down
130
 */
131
fun shutdownCompileService(compilerId: CompilerId): Unit
132
```
133

134
### Session Management
135

136
Lease and release compilation sessions for exclusive daemon access.
137

138
```kotlin { .api }
139
/**
140
 * Lease a compilation session from the daemon
141
 * @param compilerService The daemon service
142
 * @param aliveFlagPath Path to session alive flag file
143
 * @return Session ID for the leased session
144
 */
145
fun leaseCompileSession(compilerService: CompileService, aliveFlagPath: String?): Int
146

147
/**
148
 * Release a previously leased compilation session
149
 * @param compilerService The daemon service
150
 * @param sessionId Session ID to release
151
 */
152
fun releaseCompileSession(compilerService: CompileService, sessionId: Int): Unit
153
```
154

155
### Client Flag File Management
156

157
Creates and manages client alive flag files for daemon communication.
158

159
```kotlin { .api }
160
/**
161
 * Get or create a client flag file for daemon communication
162
 * @param daemonOptions Daemon configuration containing flag file path
163
 * @return File representing the client alive flag
164
 */
165
fun getOrCreateClientFlagFile(daemonOptions: DaemonOptions): File
166
```
167

168
### Compiler Classpath Detection
169

170
Automatically detects the Kotlin compiler classpath from the current environment.
171

172
```kotlin { .api }
173
/**
174
 * Detect compiler classpath automatically
175
 * @return List of classpath entries or null if detection failed
176
 */
177
fun detectCompilerClasspath(): List<String>?
178
```
179

180
## Types
181

182
### CompileServiceSession
183

184
```kotlin { .api }
185
/**
186
 * Represents a daemon service with an associated session
187
 * @param compileService The daemon service instance
188
 * @param sessionId The session ID (CompileService.NO_SESSION for no session)
189
 */
190
data class CompileServiceSession(
191
    val compileService: CompileService,
192
    val sessionId: Int
193
)
194
```
195

196
### Client Options
197

198
```kotlin { .api }
199
/**
200
 * Configuration options for the daemon client
201
 * @param stop Whether to stop/shutdown mode
202
 */
203
data class ClientOptions(
204
    var stop: Boolean = false
205
) : OptionsGroup
206
```
207

208
## Usage Patterns
209

210
### Basic Connection
211

212
```kotlin
213
val compileService = KotlinCompilerClient.connectToCompileService(
214
    compilerId, daemonJVMOptions, daemonOptions, reportingTargets
215
)
216

217
compileService?.let { service ->
218
    // Use the service for compilation
219
    // ...
220
    
221
    // Optionally shutdown when done
222
    KotlinCompilerClient.shutdownCompileService(compilerId, daemonOptions)
223
}
224
```
225

226
### Session-Based Usage
227

228
```kotlin
229
val session = KotlinCompilerClient.connectAndLease(
230
    compilerId, clientFlagFile, daemonJVMOptions, daemonOptions,
231
    reportingTargets, autostart = true, leaseSession = true, sessionFlagFile
232
)
233

234
session?.let { (service, sessionId) ->
235
    try {
236
        // Use service with sessionId for exclusive access
237
        // ...
238
    } finally {
239
        KotlinCompilerClient.releaseCompileSession(service, sessionId)
240
    }
241
}
242
```
243

244
### Auto-Detection Setup
245

246
```kotlin
247
val compilerId = CompilerId().apply {
248
    val detectedClasspath = KotlinCompilerClient.detectCompilerClasspath()
249
    if (detectedClasspath != null) {
250
        compilerClasspath = detectedClasspath
251
    } else {
252
        throw IllegalStateException("Could not detect Kotlin compiler classpath")
253
    }
254
}
255
```