0
# Domain Management
1

2
Create and manage custom domains for organizing annotations and achieving better performance through domain-specific API usage. Domains provide namespace separation and optimized APIs for high-frequency annotation scenarios.
3

4
## Capabilities
5

6
### Domain Creation and Access
7

8
Use `nvtx.get_domain` to create or retrieve domain objects for organized and high-performance annotation.
9

10
```python { .api }
11
def get_domain(name: str = None) -> Union[Domain, DummyDomain]:
12
    """
13
    Get or create a Domain object for a domain name.
14
    
15
    Parameters:
16
    - name: Domain name (default creates default "NVTX" domain)
17
    
18
    Returns:
19
    - Domain object if NVTX is enabled
20
    - DummyDomain object if NVTX is disabled (no-op operations)
21
    """
22
```
23

24
**Usage Example:**
25

26
```python
27
import nvtx
28

29
# Create custom domains for different components
30
ui_domain = nvtx.get_domain("UI")
31
network_domain = nvtx.get_domain("Network") 
32
compute_domain = nvtx.get_domain("Compute")
33

34
# Default domain
35
default_domain = nvtx.get_domain()  # or nvtx.get_domain(None)
36
```
37

38
### Domain-Specific API
39

40
Domain objects provide optimized methods for high-frequency annotation scenarios with reduced overhead compared to global functions.
41

42
```python { .api }
43
class Domain:
44
    def get_registered_string(self, string: str) -> RegisteredString:
45
        """
46
        Register a string for efficient reuse within this domain.
47
        
48
        Parameters:
49
        - string: String to register
50
        
51
        Returns:
52
        - RegisteredString object for efficient reuse
53
        """
54
    
55
    def get_category_id(self, name: str) -> int:
56
        """
57
        Get or create a category ID for the given name.
58
        
59
        Parameters:
60
        - name: Category name
61
        
62
        Returns:
63
        - Numeric category ID for use in annotations
64
        """
65
    
66
    def get_event_attributes(self, message: str = None, 
67
                           color: Union[str, int] = None,
68
                           category: Union[str, int] = None, 
69
                           payload: Union[int, float] = None) -> EventAttributes:
70
        """
71
        Create an EventAttributes object for this domain.
72
        
73
        Parameters:
74
        - message: Event message (auto-registered if string)
75
        - color: Color specification
76
        - category: Category name (auto-converted to ID) or ID
77
        - payload: Numeric payload value
78
        
79
        Returns:
80
        - EventAttributes object for use with domain methods
81
        """
82
    
83
    def mark(self, attributes: EventAttributes):
84
        """
85
        Mark an instantaneous event using pre-created attributes.
86
        
87
        Parameters:
88
        - attributes: EventAttributes from get_event_attributes()
89
        """
90
    
91
    def push_range(self, attributes: EventAttributes):
92
        """
93
        Start a code range using pre-created attributes.
94
        
95
        Parameters:
96
        - attributes: EventAttributes from get_event_attributes()
97
        """
98
    
99
    def pop_range(self):
100
        """
101
        End the most recent code range started with push_range().
102
        """
103
    
104
    def start_range(self, attributes: EventAttributes) -> int:
105
        """
106
        Start a process range using pre-created attributes.
107
        
108
        Parameters:
109
        - attributes: EventAttributes from get_event_attributes()
110
        
111
        Returns:
112
        - Range ID for use with end_range()
113
        """
114
    
115
    def end_range(self, range_id: int):
116
        """
117
        End a process range started with start_range().
118
        
119
        Parameters:
120
        - range_id: Range ID returned by start_range()
121
        """
122
```
123

124
**Usage Example:**
125

126
```python
127
import nvtx
128

129
# Create domain for high-frequency annotations
130
compute_domain = nvtx.get_domain("Compute")
131

132
# Pre-create attributes for reuse
133
loop_attrs = compute_domain.get_event_attributes("inner_loop", color="blue")
134
checkpoint_attrs = compute_domain.get_event_attributes("checkpoint", color="green")
135

136
def high_frequency_function():
137
    # High-performance annotation using domain API
138
    compute_domain.push_range(loop_attrs)
139
    
140
    for i in range(1000000):
141
        if i % 100000 == 0:
142
            compute_domain.mark(checkpoint_attrs)
143
        # ... computation ...
144
    
145
    compute_domain.pop_range()
146
```
147

148
### String and Category Management
149

150
Domains provide efficient management of strings and categories through registration and caching.
151

152
```python { .api }
153
class RegisteredString:
154
    """
155
    Registered string handle for efficient reuse within a domain.
156
    
157
    Attributes:
158
    - string: The original string value
159
    - domain: Domain object this string is registered with
160
    - handle: Low-level string handle for C API
161
    """
162
    string: str
163
    domain: Domain
164
    handle: StringHandle
165
```
166

167
**Usage Example:**
168

169
```python
170
import nvtx
171

172
# Create domain and register frequently used strings
173
domain = nvtx.get_domain("MyApp")
174

175
# Register strings for efficient reuse
176
func_name = domain.get_registered_string("process_data")
177
loop_name = domain.get_registered_string("inner_loop")
178

179
# Register categories
180
data_category = domain.get_category_id("DataProcessing")
181
ui_category = domain.get_category_id("UserInterface")
182

183
# Use registered strings and categories efficiently
184
attrs = domain.get_event_attributes(
185
    message=func_name.string,
186
    color="blue", 
187
    category=data_category
188
)
189
domain.push_range(attrs)
190
# ... work ...
191
domain.pop_range()
192
```
193

194
### Disabled Domain Handling
195

196
When NVTX is disabled, `get_domain` returns a `DummyDomain` that provides no-op implementations of all methods.
197

198
```python { .api }
199
class DummyDomain:
200
    """
201
    No-op domain replacement when NVTX is disabled.
202
    All methods are safe to call but perform no operations.
203
    """
204
    def get_registered_string(self, string: str): ...
205
    def get_category_id(self, name: str): ...
206
    def get_event_attributes(self, message: str = None, 
207
                           color: Union[str, int] = None,
208
                           category: Union[str, int] = None, 
209
                           payload: Union[int, float] = None): ...
210
    def mark(self, attributes: EventAttributes): ...
211
    def push_range(self, attributes: EventAttributes): ...
212
    def pop_range(self): ...
213
    def start_range(self, attributes: EventAttributes) -> int: ...
214
    def end_range(self, range_id: int): ...
215
```
216

217
## Performance Optimization Patterns
218

219
### Attribute Pre-creation
220

221
For maximum performance in high-frequency scenarios, pre-create `EventAttributes` objects:
222

223
```python
224
import nvtx
225

226
# Setup phase
227
domain = nvtx.get_domain("HighFreq")
228
attrs = domain.get_event_attributes("hot_path", color="red")
229

230
# Hot path - minimal overhead
231
def hot_function():
232
    domain.push_range(attrs)
233
    # ... critical code ...
234
    domain.pop_range()
235
```
236

237
### Batch Registration
238

239
Register all strings and categories during initialization:
240

241
```python
242
import nvtx
243

244
class PerformanceCritical:
245
    def __init__(self):
246
        self.domain = nvtx.get_domain("Critical")
247
        
248
        # Pre-register all strings and categories
249
        self.strings = {
250
            'init': self.domain.get_registered_string("initialization"),
251
            'compute': self.domain.get_registered_string("computation"),
252
            'cleanup': self.domain.get_registered_string("cleanup")
253
        }
254
        
255
        self.categories = {
256
            'setup': self.domain.get_category_id("Setup"),
257
            'work': self.domain.get_category_id("Work"),
258
            'teardown': self.domain.get_category_id("Teardown")
259
        }
260
        
261
        # Pre-create attributes
262
        self.attrs = {
263
            'init': self.domain.get_event_attributes(
264
                message=self.strings['init'].string,
265
                category=self.categories['setup']
266
            ),
267
            'compute': self.domain.get_event_attributes(
268
                message=self.strings['compute'].string,
269
                category=self.categories['work']
270
            )
271
        }
272
    
273
    def run(self):
274
        # Maximum performance annotation
275
        self.domain.push_range(self.attrs['init'])
276
        self.initialize()
277
        self.domain.pop_range()
278
        
279
        self.domain.push_range(self.attrs['compute'])
280
        self.compute()
281
        self.domain.pop_range()
282
```
283

284
## Domain Organization Strategies
285

286
### Component-Based Domains
287

288
Organize domains by major application components:
289

290
```python
291
import nvtx
292

293
# Create domains for different components
294
ui_domain = nvtx.get_domain("UI")
295
database_domain = nvtx.get_domain("Database")
296
network_domain = nvtx.get_domain("Network")
297
compute_domain = nvtx.get_domain("Compute")
298

299
def handle_request():
300
    # UI layer
301
    ui_attrs = ui_domain.get_event_attributes("request_handling")
302
    ui_domain.push_range(ui_attrs)
303
    
304
    # Database layer
305
    db_attrs = database_domain.get_event_attributes("query_execution")
306
    database_domain.push_range(db_attrs)
307
    execute_query()
308
    database_domain.pop_range()
309
    
310
    ui_domain.pop_range()
311
```
312

313
### Layer-Based Domains
314

315
Organize domains by architectural layers:
316

317
```python
318
import nvtx
319

320
# Architectural layer domains
321
presentation_domain = nvtx.get_domain("Presentation")
322
business_domain = nvtx.get_domain("Business")
323
data_domain = nvtx.get_domain("Data")
324
```
325

326
### Thread-Based Domains
327

328
Use domains to track work across different threads:
329

330
```python
331
import nvtx
332
import threading
333

334
# Thread-specific domains
335
main_domain = nvtx.get_domain("MainThread")
336
worker_domain = nvtx.get_domain("WorkerThread")
337
io_domain = nvtx.get_domain("IOThread")
338
```
339

340
## Error Handling and Edge Cases
341

342
- **Disabled NVTX**: All domain methods become no-ops when NVTX_DISABLE is set
343
- **Invalid Attributes**: Passing None attributes to domain methods is safe (no-op)
344
- **Thread Safety**: Domain objects and their methods are thread-safe
345
- **Memory Management**: Registered strings and categories are cached efficiently
346
- **Domain Reuse**: Multiple calls to `get_domain` with same name return the same object