0
# Constants and Platform Support
1

2
The posix_ipc module provides various constants for IPC object creation, platform capability detection, system limits, and version information. These constants enable portable code that adapts to different platform capabilities and provides access to system-specific limits.
3

4
## Capabilities
5

6
### Creation and Access Flags
7

8
Constants for controlling IPC object creation and access modes.
9

10
```python { .api }
11
# Creation flags (used with all IPC objects)
12
O_CREAT: int       # Create object if it doesn't exist
13
O_EXCL: int        # Fail if object already exists (exclusive creation)
14
O_CREX: int        # Convenience constant: O_CREAT | O_EXCL
15
O_TRUNC: int       # Truncate shared memory to zero bytes (not supported on macOS)
16

17
# Message queue access flags
18
O_RDONLY: int      # Read-only access
19
O_WRONLY: int      # Write-only access  
20
O_RDWR: int        # Read-write access
21
O_NONBLOCK: int    # Non-blocking operations
22
```
23

24
### Platform Capability Detection
25

26
Boolean constants indicating platform support for optional POSIX IPC features.
27

28
```python { .api }
29
MESSAGE_QUEUES_SUPPORTED: bool       # True if platform supports message queues
30
SEMAPHORE_TIMEOUT_SUPPORTED: bool    # True if platform supports sem_timedwait()
31
SEMAPHORE_VALUE_SUPPORTED: bool      # True if platform supports sem_getvalue()
32
```
33

34
### System Limits and Defaults
35

36
Constants providing default values and system limits for IPC objects.
37

38
```python { .api }
39
# Message queue defaults and limits
40
QUEUE_MESSAGES_MAX_DEFAULT: int      # Default maximum messages per queue
41
QUEUE_MESSAGE_SIZE_MAX_DEFAULT: int  # Default maximum message size in bytes
42
QUEUE_PRIORITY_MAX: int              # Maximum message priority value
43

44
# Signal constants (available on systems with POSIX Realtime Signals)
45
USER_SIGNAL_MIN: int                 # Minimum user signal number
46
USER_SIGNAL_MAX: int                 # Maximum user signal number
47

48
# Deprecated constants (use os.sysconf() alternatives instead)
49
PAGE_SIZE: int                       # Memory page size (deprecated in v1.3.0)
50
SEMAPHORE_VALUE_MAX: int            # Maximum semaphore value (deprecated in v1.3.0)
51
```
52

53
### Version and Metadata
54

55
String constants providing module version and metadata information.
56

57
```python { .api }
58
VERSION: str         # Module version string (e.g., "1.3.0")
59
__version__: str     # Alias for VERSION  
60
__author__: str      # Module author
61
__license__: str     # License information
62
__copyright__: str   # Copyright notice
63
```
64

65
## Platform-Specific Behavior
66

67
### Message Queue Support
68

69
```python
70
import posix_ipc
71

72
if posix_ipc.MESSAGE_QUEUES_SUPPORTED:
73
    # Safe to use MessageQueue class
74
    mq = posix_ipc.MessageQueue('/my_queue', posix_ipc.O_CREAT)
75
    # ... use message queue ...
76
    mq.close()
77
    mq.unlink()
78
else:
79
    print("Message queues not supported on this platform (e.g., macOS)")
80
```
81

82
### Semaphore Timeout Support
83

84
```python
85
import posix_ipc
86

87
sem = posix_ipc.Semaphore('/my_sem', posix_ipc.O_CREAT, initial_value=0)
88

89
if posix_ipc.SEMAPHORE_TIMEOUT_SUPPORTED:
90
    # Can use timeout > 0 effectively
91
    try:
92
        sem.acquire(timeout=5.0)
93
        print("Semaphore acquired within timeout")
94
    except posix_ipc.BusyError:
95
        print("Timeout expired")
96
else:
97
    print("Timeout not supported - timeout > 0 treated as infinite")
98
    # On macOS, timeout > 0 is treated as infinite wait
99

100
sem.close()
101
sem.unlink()
102
```
103

104
### Semaphore Value Access
105

106
```python
107
import posix_ipc
108

109
sem = posix_ipc.Semaphore('/value_sem', posix_ipc.O_CREAT, initial_value=5)
110

111
if posix_ipc.SEMAPHORE_VALUE_SUPPORTED:
112
    print(f"Current semaphore value: {sem.value}")
113
else:
114
    print("Semaphore value access not supported on this platform (e.g., macOS)")
115
    # Attempting to access sem.value would raise AttributeError
116

117
sem.close()
118
sem.unlink()
119
```
120

121
## Working with System Limits
122

123
### Message Queue Limits
124

125
The default values for message queue parameters may be quite restrictive on some systems:
126

127
```python
128
import posix_ipc
129

130
print(f"Default max messages: {posix_ipc.QUEUE_MESSAGES_MAX_DEFAULT}")
131
print(f"Default max message size: {posix_ipc.QUEUE_MESSAGE_SIZE_MAX_DEFAULT}")
132
print(f"Max priority: {posix_ipc.QUEUE_PRIORITY_MAX}")
133

134
# Default max messages might be as low as 10 on Linux
135
# Consider providing explicit values for production use
136
mq = posix_ipc.MessageQueue('/prod_queue', posix_ipc.O_CREAT,
137
                           max_messages=100,           # Explicit value
138
                           max_message_size=8192)      # Explicit value
139
```
140

141
### Deprecated Constants
142

143
Some constants are deprecated and should be replaced with standard library alternatives:
144

145
```python
146
import posix_ipc
147
import os
148

149
# Deprecated (will be removed in future version)
150
# page_size = posix_ipc.PAGE_SIZE
151
# max_sem_value = posix_ipc.SEMAPHORE_VALUE_MAX
152

153
# Recommended alternatives
154
page_size = os.sysconf('SC_PAGE_SIZE')
155
max_sem_value = os.sysconf('SC_SEM_VALUE_MAX')
156

157
print(f"Page size: {page_size}")
158
print(f"Max semaphore value: {max_sem_value}")
159
```
160

161
### Signal Range for Notifications
162

163
When using message queue notifications with signals, use the provided signal range:
164

165
```python
166
import posix_ipc
167
import signal
168

169
# Check if realtime signals are available
170
if hasattr(posix_ipc, 'USER_SIGNAL_MIN'):
171
    # Use signal within the safe range
172
    notify_signal = posix_ipc.USER_SIGNAL_MIN + 1
173
    
174
    mq = posix_ipc.MessageQueue('/signal_queue', posix_ipc.O_CREAT)
175
    
176
    def signal_handler(signum, frame):
177
        print(f"Notification received on signal {signum}")
178
    
179
    signal.signal(notify_signal, signal_handler)
180
    mq.request_notification(notify_signal)
181
    
182
    # ... rest of application ...
183
else:
184
    print("Realtime signals not available")
185
```
186

187
## Creation Flag Combinations
188

189
### Common Flag Patterns
190

191
```python
192
import posix_ipc
193

194
# Open existing object (fail if doesn't exist)
195
flags = 0
196

197
# Create if doesn't exist, open if exists  
198
flags = posix_ipc.O_CREAT
199

200
# Create new object (fail if already exists)
201
flags = posix_ipc.O_CREAT | posix_ipc.O_EXCL
202
# Or use the convenience constant:
203
flags = posix_ipc.O_CREX
204

205
# Create shared memory and truncate if exists (not supported on macOS)
206
flags = posix_ipc.O_CREAT | posix_ipc.O_TRUNC
207
```
208

209
### Message Queue Access Modes
210

211
```python
212
import posix_ipc
213

214
if posix_ipc.MESSAGE_QUEUES_SUPPORTED:
215
    # Read-only message queue
216
    mq_reader = posix_ipc.MessageQueue('/data_queue', read=True, write=False)
217
    
218
    # Write-only message queue  
219
    mq_writer = posix_ipc.MessageQueue('/data_queue', read=False, write=True)
220
    
221
    # Full access (default)
222
    mq_full = posix_ipc.MessageQueue('/data_queue', read=True, write=True)
223
    
224
    # Using flag constants (alternative approach)
225
    mq_readonly = posix_ipc.MessageQueue('/flag_queue', posix_ipc.O_CREAT | posix_ipc.O_RDONLY)
226
```
227

228
## Version and Compatibility
229

230
### Checking Module Version
231

232
```python
233
import posix_ipc
234

235
print(f"posix_ipc version: {posix_ipc.VERSION}")
236
print(f"Author: {posix_ipc.__author__}")
237
print(f"License: {posix_ipc.__license__}")
238

239
# Version comparison for feature detection
240
version_parts = posix_ipc.VERSION.split('.')
241
major, minor = int(version_parts[0]), int(version_parts[1])
242

243
if (major, minor) >= (1, 3):
244
    print("Using modern version - PAGE_SIZE and SEMAPHORE_VALUE_MAX are deprecated")
245
else:
246
    print("Using older version - PAGE_SIZE and SEMAPHORE_VALUE_MAX still supported")
247
```
248

249
### Comprehensive Platform Detection
250

251
```python
252
import posix_ipc
253
import sys
254

255
def print_platform_support():
256
    print(f"Platform: {sys.platform}")
257
    print(f"posix_ipc version: {posix_ipc.VERSION}")
258
    print()
259
    print("Feature Support:")
260
    print(f"  Message Queues: {posix_ipc.MESSAGE_QUEUES_SUPPORTED}")
261
    print(f"  Semaphore Timeouts: {posix_ipc.SEMAPHORE_TIMEOUT_SUPPORTED}")
262
    print(f"  Semaphore Values: {posix_ipc.SEMAPHORE_VALUE_SUPPORTED}")
263
    print()
264
    print("System Limits:")
265
    print(f"  Default Max Messages: {posix_ipc.QUEUE_MESSAGES_MAX_DEFAULT}")
266
    print(f"  Default Max Message Size: {posix_ipc.QUEUE_MESSAGE_SIZE_MAX_DEFAULT}")
267
    print(f"  Max Message Priority: {posix_ipc.QUEUE_PRIORITY_MAX}")
268
    
269
    if hasattr(posix_ipc, 'USER_SIGNAL_MIN'):
270
        print(f"  User Signal Range: {posix_ipc.USER_SIGNAL_MIN}-{posix_ipc.USER_SIGNAL_MAX}")
271

272
print_platform_support()
273
```