0
# Runtime Management
1

2
Core functions for initializing, managing, and shutting down Xorbits runtime environments. These functions handle both local runtime creation and connection to distributed Xorbits clusters.
3

4
## Capabilities
5

6
### Initialization
7

8
Initialize Xorbits runtime locally or connect to an existing Xorbits cluster. This is typically the first function called when using Xorbits.
9

10
```python { .api }
11
def init(
12
    address: Optional[str] = None,
13
    init_local: bool = no_default,
14
    session_id: Optional[str] = None,
15
    timeout: Optional[float] = None,
16
    n_worker: int = 1,
17
    n_cpu: Union[int, str] = "auto",
18
    mem_bytes: Union[int, str] = "auto",
19
    cuda_devices: Union[List[int], List[List[int]], str] = "auto",
20
    web: Union[bool, str] = "auto",
21
    new: bool = True,
22
    storage_config: Optional[Dict] = None,
23
    **kwargs
24
) -> None:
25
    """
26
    Init Xorbits runtime locally or connect to an Xorbits cluster.
27

28
    Parameters:
29
    - address: str, optional
30
        - if None (default), address will be "127.0.0.1", a local runtime will be initialized
31
        - if specify an address for creating a new local runtime, specify like `<ip>:<port>`
32
        - if connect to a Xorbits cluster address, e.g. `http://<supervisor_ip>:<supervisor_web_port>`
33
    - init_local: bool, no default value
34
        Indicates if creating a new local runtime.
35
        - If has initialized, `init_local` cannot be True, it will skip creating
36
        - When address is None and not initialized, `init_local` will be True
37
        - Otherwise, if it's not specified, False will be set
38
    - session_id: str, optional
39
        Session ID, if not specified, a new ID will be auto generated
40
    - timeout: float
41
        Timeout about creating a new runtime or connecting to an existing cluster
42
    - n_worker: int, optional
43
        How many workers to start when creating a local runtime (takes effect only when `init_local` is True)
44
    - n_cpu: int, str
45
        Number of CPUs, if "auto", the number of cores will be specified (takes effect only when `init_local` is True)
46
    - mem_bytes: int, str
47
        Memory to use, in bytes, if "auto", total memory bytes will be specified (takes effect only when `init_local` is True)
48
    - cuda_devices: list of int, list of list
49
        - when "auto" (default), all visible GPU devices will be used
50
        - When n_worker is 1, list of int can be specified, means the device indexes to use
51
        - When n_worker > 1, list of list can be specified for each worker
52
        (takes effect only when `init_local` is True)
53
    - web: bool, str
54
        If creating a web UI (takes effect only when `init_local` is True)
55
    - new: bool
56
        If creating a new session when connecting to an existing cluster (takes effect only when `init_local` is False)
57
    - storage_config: dict, optional
58
        Storage backend and its configuration when init a new local cluster.
59
        Using `shared_memory` storage backend by default.
60
        Currently, support `shared_memory` and `mmap` two options.
61
        (takes effect only when `init_local` is True)
62
    """
63
```
64

65
**Usage Examples:**
66

67
```python
68
# Initialize local runtime with default settings
69
import xorbits
70
xorbits.init()
71

72
# Initialize local runtime with custom settings
73
xorbits.init(n_worker=4, n_cpu=8, mem_bytes="8GB")
74

75
# Connect to existing cluster
76
xorbits.init(address="http://192.168.1.100:7103")
77

78
# Initialize with GPU support
79
xorbits.init(cuda_devices=[0, 1])
80

81
# Initialize with custom storage backend
82
xorbits.init(storage_config={"mmap": {"root_dirs": "/tmp/xorbits"}})
83
```
84

85
### Shutdown
86

87
Shutdown the current local runtime and clean up resources.
88

89
```python { .api }
90
def shutdown(**kw) -> None:
91
    """
92
    Shutdown current local runtime.
93
    
94
    Parameters:
95
    - **kw: Additional keyword arguments passed to the shutdown process
96
    """
97
```
98

99
**Usage Examples:**
100

101
```python
102
# Basic shutdown
103
xorbits.shutdown()
104

105
# Shutdown when connecting to cluster releases session resources
106
# but doesn't affect the cluster itself
107
```
108

109
### Execution
110

111
Manually trigger execution of DataRef objects. Xorbits uses lazy evaluation by default, so computations are not executed until explicitly triggered.
112

113
```python { .api }
114
def run(obj, **kwargs):
115
    """
116
    Manually trigger execution of DataRef objects.
117
    
118
    Parameters:
119
    - obj: DataRef or collection of DataRefs to execute
120
    - **kwargs: Additional execution parameters
121
    
122
    Returns:
123
    - Computed results as concrete objects (pandas DataFrame/Series, numpy arrays, etc.)
124
    """
125
```
126

127
**Usage Examples:**
128

129
```python
130
import xorbits
131
import xorbits.pandas as pd
132
import xorbits.numpy as np
133

134
xorbits.init()
135

136
# Create lazy computations
137
df = pd.DataFrame({'A': [1, 2, 3], 'B': [4, 5, 6]})
138
result = df.sum()
139

140
# Execute computation
141
computed_result = xorbits.run(result)
142
print(computed_result)  # Actual pandas Series
143

144
# Execute multiple objects
145
arr = np.array([1, 2, 3])
146
df_mean = df.mean()
147
computed_arr, computed_mean = xorbits.run(arr, df_mean)
148

149
xorbits.shutdown()
150
```