0
# POSIX IPC
1

2
A Python C extension module that provides POSIX inter-process communication primitives including semaphores, shared memory, and message queues. The module enables efficient IPC between processes on Unix-like systems supporting POSIX Realtime Extensions (POSIX 1003.1b-1993), including Linux, macOS, FreeBSD, and Windows with Cygwin.
3

4
## Package Information
5

6
- **Package Name**: posix-ipc
7
- **Language**: Python (C Extension)
8
- **Installation**: `pip install posix-ipc`
9

10
## Core Imports
11

12
```python
13
import posix_ipc
14
```
15

16
Common usage patterns:
17

18
```python
19
from posix_ipc import Semaphore, SharedMemory, MessageQueue
20
from posix_ipc import O_CREAT, O_EXCL, O_CREX
21
```
22

23
## Basic Usage
24

25
```python
26
import posix_ipc
27
import os
28

29
# Create a named semaphore
30
sem = posix_ipc.Semaphore('/my_semaphore', posix_ipc.O_CREAT, initial_value=1)
31

32
# Acquire and release
33
sem.acquire()
34
# ... critical section ...
35
sem.release()
36

37
# Clean up
38
sem.close()
39
sem.unlink()
40

41
# Create shared memory
42
shm = posix_ipc.SharedMemory('/my_shm', posix_ipc.O_CREAT, size=1024)
43
os.write(shm.fd, b'Hello, shared memory!')
44
shm.close_fd()
45
shm.unlink()
46

47
# Create message queue (if supported)
48
if posix_ipc.MESSAGE_QUEUES_SUPPORTED:
49
    mq = posix_ipc.MessageQueue('/my_queue', posix_ipc.O_CREAT)
50
    mq.send(b'Hello, message queue!')
51
    message, priority = mq.receive()
52
    mq.close()
53
    mq.unlink()
54
```
55

56
## Architecture
57

58
POSIX IPC objects are persistent kernel resources that exist independently of the creating process. Key design principles:
59

60
- **Named Objects**: All IPC objects are identified by filesystem-like names (e.g., `/my_semaphore`)
61
- **Process Independence**: Objects persist until explicitly unlinked, even after creating process exits
62
- **Permissions**: Objects respect Unix file permissions for access control
63
- **Platform Portability**: Consistent API across POSIX-compliant systems with platform-specific feature detection
64

65
The module provides both object-oriented interfaces (classes) and convenience functions for managing IPC objects, with comprehensive error handling and platform compatibility checks.
66

67
## Capabilities
68

69
### Semaphores
70

71
POSIX named semaphores for process synchronization and resource counting. Supports blocking/non-blocking acquisition, timeouts (platform-dependent), and context manager protocol.
72

73
```python { .api }
74
class Semaphore:
75
    def __init__(self, name, flags=0, mode=0o600, initial_value=0): ...
76
    def acquire(self, timeout=None): ...
77
    def release(self): ...
78
    def close(self): ...
79
    def unlink(self): ...
80
    def __enter__(self): ...
81
    def __exit__(self, exc_type, exc_value, traceback): ...
82
    def __str__(self): ...
83
    def __repr__(self): ...
84
    @property
85
    def name(self): ...
86
    @property
87
    def mode(self): ...
88
    @property  
89
    def value(self): ...  # Not available on macOS
90

91
def unlink_semaphore(name): ...
92
```
93

94
[Semaphores](./semaphores.md)
95

96
### Shared Memory
97

98
POSIX named shared memory segments that appear as memory-mapped files. Supports creation, resizing, and memory mapping for high-performance inter-process data sharing.
99

100
```python { .api }
101
class SharedMemory:
102
    def __init__(self, name, flags=0, mode=0o600, size=0, read_only=False): ...
103
    def close_fd(self): ...
104
    def fileno(self): ...
105
    def unlink(self): ...
106
    def __str__(self): ...
107
    def __repr__(self): ...
108
    @property
109
    def name(self): ...
110
    @property
111
    def mode(self): ...
112
    @property
113
    def fd(self): ...
114
    @property
115
    def size(self): ...
116

117
def unlink_shared_memory(name): ...
118
```
119

120
[Shared Memory](./shared-memory.md)
121

122
### Message Queues
123

124
POSIX named message queues for reliable message passing between processes. Supports priority-based message ordering, blocking/non-blocking operations, and asynchronous notifications.
125

126
```python { .api }
127
class MessageQueue:
128
    def __init__(self, name, flags=0, mode=0o600, max_messages=QUEUE_MESSAGES_MAX_DEFAULT, 
129
                 max_message_size=QUEUE_MESSAGE_SIZE_MAX_DEFAULT, read=True, write=True): ...
130
    def send(self, message, timeout=None, priority=0): ...
131
    def receive(self, timeout=None): ...
132
    def request_notification(self, notification=None): ...
133
    def fileno(self): ...
134
    def close(self): ...
135
    def unlink(self): ...
136
    def __str__(self): ...
137
    def __repr__(self): ...
138
    @property
139
    def name(self): ...
140
    @property
141
    def mode(self): ...
142
    @property
143
    def mqd(self): ...
144
    @property
145
    def block(self): ...
146
    @block.setter  
147
    def block(self, value): ...
148
    @property
149
    def max_messages(self): ...
150
    @property
151
    def max_message_size(self): ...
152
    @property
153
    def current_messages(self): ...
154

155
def unlink_message_queue(name): ...
156
```
157

158
[Message Queues](./message-queues.md)
159

160
## Constants and Platform Support
161

162
Module constants for IPC object creation, platform capability detection, and system limits.
163

164
```python { .api }
165
# Creation flags
166
O_CREAT: int
167
O_EXCL: int
168
O_CREX: int  # O_CREAT | O_EXCL
169
O_TRUNC: int
170

171
# Message queue flags
172
O_RDONLY: int
173
O_WRONLY: int
174
O_RDWR: int
175
O_NONBLOCK: int
176

177
# Platform support detection
178
MESSAGE_QUEUES_SUPPORTED: bool
179
SEMAPHORE_TIMEOUT_SUPPORTED: bool
180
SEMAPHORE_VALUE_SUPPORTED: bool
181

182
# System limits and defaults
183
QUEUE_MESSAGES_MAX_DEFAULT: int
184
QUEUE_MESSAGE_SIZE_MAX_DEFAULT: int
185
QUEUE_PRIORITY_MAX: int
186
USER_SIGNAL_MIN: int
187
USER_SIGNAL_MAX: int
188

189
# Deprecated constants (use os.sysconf() instead)
190
PAGE_SIZE: int  # Deprecated as of v1.3.0
191
SEMAPHORE_VALUE_MAX: int  # Deprecated as of v1.3.0
192

193
# Version information
194
VERSION: str
195
__version__: str
196
__author__: str
197
__license__: str
198
__copyright__: str
199
```
200

201
[Constants and Platform Support](./constants.md)
202

203
## Exception Classes
204

205
Custom exceptions for IPC-specific error conditions.
206

207
```python { .api }
208
class Error(Exception): ...
209
class SignalError(Error): ...
210
class PermissionsError(Error): ...
211
class ExistentialError(Error): ...
212
class BusyError(Error): ...
213
```
214

215
All custom exceptions inherit from the base `Error` class, which itself inherits from Python's built-in `Exception`. These exceptions provide specific error handling for common IPC scenarios like permission denied, object existence conflicts, timeout conditions, and signal interruptions.