0
# Kernel Management
1
2
Comprehensive kernel lifecycle management including starting, stopping, restarting, and monitoring individual kernels or multiple kernels simultaneously. Supports both synchronous and asynchronous operations for different integration patterns.
3
4
## Capabilities
5
6
### Single Kernel Management
7
8
The `KernelManager` class provides complete lifecycle management for individual kernel instances, handling process management, connection setup, and kernel monitoring.
9
10
```python { .api }
11
class KernelManager:
12
"""Manages the lifecycle of a single kernel process."""
13
14
def start_kernel(self, **kwargs):
15
"""
16
Start a new kernel process.
17
18
Parameters:
19
- kernel_name (str): Name of kernel to start
20
- cwd (str): Working directory for kernel
21
- env (dict): Environment variables
22
- **kwargs: Additional kernel arguments
23
24
Returns:
25
None
26
"""
27
28
def shutdown_kernel(self, now=False, restart=False):
29
"""
30
Shutdown the kernel process.
31
32
Parameters:
33
- now (bool): Force immediate shutdown if True
34
- restart (bool): Whether this is part of a restart
35
36
Returns:
37
None
38
"""
39
40
def restart_kernel(self, now=False, newports=False, **kwargs):
41
"""
42
Restart the kernel process.
43
44
Parameters:
45
- now (bool): Force immediate restart if True
46
- newports (bool): Use new ports for connection
47
- **kwargs: Additional arguments for new kernel
48
49
Returns:
50
None
51
"""
52
53
def kill_kernel(self):
54
"""
55
Force kill the kernel process.
56
57
Returns:
58
None
59
"""
60
61
def interrupt_kernel(self):
62
"""
63
Send interrupt signal to kernel.
64
65
Returns:
66
None
67
"""
68
69
def signal_kernel(self, signum):
70
"""
71
Send specific signal to kernel process.
72
73
Parameters:
74
- signum (int): Signal number to send
75
76
Returns:
77
None
78
"""
79
80
def is_alive(self):
81
"""
82
Check if kernel process is running.
83
84
Returns:
85
bool: True if kernel is alive
86
"""
87
88
def client(self, **kwargs):
89
"""
90
Create a client for communicating with this kernel.
91
92
Parameters:
93
- **kwargs: Client configuration options
94
95
Returns:
96
BlockingKernelClient: Client instance
97
"""
98
99
@property
100
def ready(self):
101
"""Future indicating when kernel is ready for communication."""
102
103
@property
104
def has_kernel(self):
105
"""Boolean indicating if kernel process exists."""
106
107
@property
108
def kernel_spec(self):
109
"""KernelSpec object for this kernel."""
110
```
111
112
### Async Kernel Management
113
114
The `AsyncKernelManager` provides async versions of kernel management operations for integration with asyncio-based applications.
115
116
```python { .api }
117
class AsyncKernelManager(KernelManager):
118
"""Async version of KernelManager."""
119
120
def client(self, **kwargs):
121
"""
122
Create an async client for this kernel.
123
124
Parameters:
125
- **kwargs: Client configuration options
126
127
Returns:
128
AsyncKernelClient: Async client instance
129
"""
130
```
131
132
### Multi-Kernel Management
133
134
The `MultiKernelManager` class manages multiple kernel instances simultaneously, providing APIs for starting, stopping, and tracking multiple kernels with unique identifiers.
135
136
```python { .api }
137
class MultiKernelManager:
138
"""Manages multiple kernel instances."""
139
140
def start_kernel(self, kernel_name=None, **kwargs):
141
"""
142
Start a new kernel and return its ID.
143
144
Parameters:
145
- kernel_name (str): Name of kernel to start
146
- **kwargs: Kernel configuration options
147
148
Returns:
149
str: Unique kernel ID
150
"""
151
152
def shutdown_kernel(self, kernel_id, now=False, restart=False):
153
"""
154
Shutdown a specific kernel.
155
156
Parameters:
157
- kernel_id (str): ID of kernel to shutdown
158
- now (bool): Force immediate shutdown
159
- restart (bool): Whether this is part of restart
160
161
Returns:
162
None
163
"""
164
165
def restart_kernel(self, kernel_id, now=False, **kwargs):
166
"""
167
Restart a specific kernel.
168
169
Parameters:
170
- kernel_id (str): ID of kernel to restart
171
- now (bool): Force immediate restart
172
- **kwargs: Additional kernel arguments
173
174
Returns:
175
None
176
"""
177
178
def kill_kernel(self, kernel_id):
179
"""
180
Force kill a specific kernel.
181
182
Parameters:
183
- kernel_id (str): ID of kernel to kill
184
185
Returns:
186
None
187
"""
188
189
def interrupt_kernel(self, kernel_id):
190
"""
191
Interrupt a specific kernel.
192
193
Parameters:
194
- kernel_id (str): ID of kernel to interrupt
195
196
Returns:
197
None
198
"""
199
200
def get_kernel(self, kernel_id):
201
"""
202
Get the KernelManager for a specific kernel.
203
204
Parameters:
205
- kernel_id (str): ID of kernel
206
207
Returns:
208
KernelManager: Manager instance for the kernel
209
"""
210
211
def list_kernel_ids(self):
212
"""
213
List all active kernel IDs.
214
215
Returns:
216
list: List of kernel ID strings
217
"""
218
219
def remove_kernel(self, kernel_id):
220
"""
221
Remove a kernel from management (must be shutdown first).
222
223
Parameters:
224
- kernel_id (str): ID of kernel to remove
225
226
Returns:
227
KernelManager: The removed kernel manager
228
"""
229
230
@property
231
def default_kernel_name(self):
232
"""Default kernel name for new kernels."""
233
234
@property
235
def kernel_manager_class(self):
236
"""Class used for individual kernel managers."""
237
```
238
239
### Async Multi-Kernel Management
240
241
```python { .api }
242
class AsyncMultiKernelManager(MultiKernelManager):
243
"""Async version of MultiKernelManager with same interface."""
244
```
245
246
### Kernel Utilities
247
248
```python { .api }
249
def run_kernel():
250
"""
251
Run a kernel in the current process.
252
253
Returns:
254
None
255
"""
256
```
257
258
## Usage Examples
259
260
### Basic Single Kernel Management
261
262
```python
263
from jupyter_client import KernelManager
264
265
# Create and configure kernel manager
266
km = KernelManager(kernel_name='python3')
267
268
# Start the kernel
269
km.start_kernel()
270
271
# Check if kernel is running
272
if km.is_alive():
273
print("Kernel is running")
274
275
# Create a client to communicate
276
kc = km.client()
277
kc.start_channels()
278
279
# Use the kernel...
280
281
# Clean shutdown
282
kc.stop_channels()
283
km.shutdown_kernel()
284
```
285
286
### Multi-Kernel Management
287
288
```python
289
from jupyter_client import MultiKernelManager
290
291
# Create multi-kernel manager
292
mkm = MultiKernelManager()
293
294
# Start multiple kernels
295
python_id = mkm.start_kernel(kernel_name='python3')
296
r_id = mkm.start_kernel(kernel_name='ir')
297
298
# List all kernels
299
kernel_ids = mkm.list_kernel_ids()
300
print(f"Running kernels: {kernel_ids}")
301
302
# Get individual managers
303
python_km = mkm.get_kernel(python_id)
304
r_km = mkm.get_kernel(r_id)
305
306
# Clean shutdown
307
mkm.shutdown_kernel(python_id)
308
mkm.shutdown_kernel(r_id)
309
```
310
311
### Async Kernel Management
312
313
```python
314
import asyncio
315
from jupyter_client import AsyncKernelManager
316
317
async def manage_kernel():
318
# Create async kernel manager
319
km = AsyncKernelManager()
320
321
# Start kernel
322
await km.start_kernel()
323
324
# Create async client
325
kc = km.client()
326
await kc.start_channels()
327
328
# Use kernel...
329
330
# Clean shutdown
331
await kc.stop_channels()
332
await km.shutdown_kernel()
333
334
# Run async function
335
asyncio.run(manage_kernel())
336
```