0
# Configuration
1

2
Global configuration functions that affect all pools and tasks created after the configuration change. These settings provide high-level control over multitasking behavior.
3

4
## Capabilities
5

6
### Thread Limit Configuration
7

8
Set the global maximum number of concurrent threads or processes.
9

10
```python { .api }
11
def set_max_threads(threads: Optional[int] = None) -> None:
12
    """
13
    Configure the maximum number of concurrent threads/processes.
14
    
15
    This function allows users to override the default CPU-based thread
16
    count. Setting this affects new pools but not existing ones.
17
    
18
    Args:
19
        threads: Maximum concurrent tasks. If None, uses CPU count.
20
                 Must be positive integer or None.
21
    """
22
```
23

24
**Usage Example:**
25

26
```python
27
import multitasking
28

29
# Check current configuration
30
print(f"CPU cores detected: {multitasking.config['CPU_CORES']}")
31
print(f"Current max threads: {multitasking.config['MAX_THREADS']}")
32

33
# Set custom thread limit
34
multitasking.set_max_threads(10)
35
print(f"New max threads: {multitasking.config['MAX_THREADS']}")
36

37
# Reset to CPU count
38
multitasking.set_max_threads()
39
print(f"Reset to: {multitasking.config['MAX_THREADS']}")
40

41
# Scale based on CPU cores for I/O-bound tasks
42
multitasking.set_max_threads(multitasking.config["CPU_CORES"] * 5)
43
print(f"I/O optimized: {multitasking.config['MAX_THREADS']} threads")
44

45
# Unlimited threading (use carefully!)
46
multitasking.set_max_threads(0)
47
```
48

49
### Engine Selection
50

51
Configure whether new pools use threading or multiprocessing by default.
52

53
```python { .api }
54
def set_engine(kind: str = "") -> None:
55
    """
56
    Configure the execution engine for new pools.
57
    
58
    This determines whether new tasks run in threads or separate
59
    processes. Threads share memory but processes are more isolated.
60
    Only affects pools created after this call.
61
    
62
    Args:
63
        kind: Engine type. Contains "process" for multiprocessing,
64
              anything else defaults to threading.
65
    
66
    Note:
67
        Threading: Faster startup, shared memory, GIL limitations
68
        Processing: Slower startup, isolated memory, true parallelism
69
    """
70
```
71

72
**Usage Example:**
73

74
```python
75
import multitasking
76

77
# Default is threading
78
print(f"Default engine: {multitasking.config['ENGINE']}")
79

80
# For I/O-bound tasks (default, recommended for most cases)
81
multitasking.set_engine("thread")
82
multitasking.createPool("io_pool", threads=20)
83

84
@multitasking.task
85
def fetch_data(url):
86
    # I/O-bound task - threading is efficient
87
    pass
88

89
# For CPU-bound tasks (avoids GIL limitations)
90
multitasking.set_engine("process")
91
multitasking.createPool("cpu_pool", threads=4)
92

93
@multitasking.task
94
def compute_heavy(data):
95
    # CPU-bound task - multiprocessing avoids GIL
96
    return sum(x*x for x in data)
97

98
# Check current configuration
99
print(f"Current engine: {multitasking.config['ENGINE']}")
100
```
101

102
## Configuration Guidelines
103

104
### Choosing Thread Counts
105

106
Different workload types benefit from different thread configurations:
107

108
```python
109
import multitasking
110

111
# I/O-bound tasks: High concurrency (network requests, file operations)
112
multitasking.set_max_threads(multitasking.config["CPU_CORES"] * 5)
113
multitasking.set_engine("thread")
114

115
# CPU-bound tasks: Match CPU cores (mathematical computations)
116
multitasking.set_max_threads(multitasking.config["CPU_CORES"])
117
multitasking.set_engine("process")
118

119
# Mixed workloads: Conservative approach
120
multitasking.set_max_threads(multitasking.config["CPU_CORES"] * 2)
121
multitasking.set_engine("thread")
122
```
123

124
### Engine Selection Guidelines
125

126
Choose the appropriate execution engine based on task characteristics:
127

128
```python
129
import multitasking
130

131
# Threading: Best for I/O-bound tasks
132
multitasking.set_engine("thread")
133
# - File operations
134
# - Network requests  
135
# - Database queries
136
# - Web scraping
137
# - API calls
138

139
# Multiprocessing: Best for CPU-intensive tasks  
140
multitasking.set_engine("process")
141
# - Mathematical computations
142
# - Image processing
143
# - Data analysis
144
# - Cryptographic operations
145
# - Scientific computing
146
```
147

148
## Global Configuration Access
149

150
The global configuration dictionary provides access to all settings:
151

152
```python
153
import multitasking
154

155
# Access configuration values
156
config = multitasking.config
157
print(f"CPU cores: {config['CPU_CORES']}")
158
print(f"Max threads: {config['MAX_THREADS']}")
159
print(f"Current engine: {config['ENGINE']}")
160
print(f"Active pool: {config['POOL_NAME']}")
161
print(f"Shutdown mode: {config['KILL_RECEIVED']}")
162

163
# View all pools
164
print(f"Available pools: {list(config['POOLS'].keys())}")
165

166
# View all tasks
167
print(f"Total tasks created: {len(config['TASKS'])}")
168
```