0
# smmap
1

2
A pure Python implementation of a sliding window memory map manager that efficiently handles memory-mapped file access for large files. It automatically manages system resources by tracking mapped files and client usage, unloading unused maps when resources become scarce or memory limits are reached.
3

4
## Package Information
5

6
- **Package Name**: smmap
7
- **Language**: Python
8
- **Installation**: `pip install smmap`
9
- **Python Requirements**: >=3.8
10
- **License**: BSD
11

12
## Core Imports
13

14
```python
15
import smmap
16
```
17

18
Import specific components:
19

20
```python
21
from smmap import SlidingWindowMapManager, StaticWindowMapManager
22
from smmap import WindowCursor, SlidingWindowMapBuffer
23
from smmap import align_to_mmap, is_64_bit, ALLOCATIONGRANULARITY
24
```
25

26
## Basic Usage
27

28
```python
29
import smmap
30

31
# Create a memory manager (recommended for most uses)
32
manager = smmap.SlidingWindowMapManager()
33

34
# Create a cursor to access a file
35
cursor = manager.make_cursor('/path/to/large/file.dat')
36

37
# Map a region of the file into memory
38
cursor.use_region(offset=0, size=1024*1024)  # Map 1MB starting at offset 0
39

40
if cursor.is_valid():
41
    # Access the mapped memory as a buffer
42
    buffer = cursor.buffer()
43
    first_byte = buffer[0]
44
    first_chunk = buffer[:100]
45
    
46
    # Clean up when done
47
    cursor.unuse_region()
48

49
# Alternative: Use the buffer interface for easier access
50
with smmap.SlidingWindowMapBuffer(manager.make_cursor('/path/to/file.dat')) as buf:
51
    # Direct byte-level access with automatic windowing
52
    first_byte = buf[0]
53
    last_10_bytes = buf[-10:]
54
    chunk = buf[1000:2000]
55
```
56

57
## Architecture
58

59
smmap uses a sliding window approach to efficiently manage memory-mapped file access:
60

61
- **Memory Managers**: Control memory allocation, handle limits, and manage resource cleanup using LRU algorithms
62
- **Window Cursors**: Provide low-level access to mapped memory regions with precise control over mapping and unmapping
63
- **Buffers**: Offer a high-level string-like interface that automatically handles windowing behind the scenes
64
- **Utility Classes**: Support memory alignment, region tracking, and cross-platform compatibility
65

66
The library automatically handles resource management, preventing file descriptor leaks and managing memory usage within configurable limits. On 32-bit systems, it maps only portions of large files as needed, while 64-bit systems can optionally map entire files for maximum performance.
67

68
## Capabilities
69

70
### Memory Managers
71

72
Core memory management classes that control resource allocation, handle system limits, and provide configurable memory mapping strategies for different system architectures and use cases.
73

74
```python { .api }
75
class SlidingWindowMapManager:
76
    def __init__(self, window_size=-1, max_memory_size=0, max_open_handles=sys.maxsize): ...
77
    def make_cursor(self, path_or_fd): ...
78
    def collect(self): ...
79

80
class StaticWindowMapManager:
81
    def __init__(self, window_size=0, max_memory_size=0, max_open_handles=sys.maxsize): ...
82
    def make_cursor(self, path_or_fd): ...
83
    def collect(self): ...
84
```
85

86
[Memory Managers](./memory-managers.md)
87

88
### Window Access
89

90
Low-level cursor interface for precise memory region control and high-level buffer interface providing automatic windowing with string-like access patterns.
91

92
```python { .api }
93
class WindowCursor:
94
    def use_region(self, offset=0, size=0, flags=0): ...
95
    def unuse_region(self): ...
96
    def buffer(self): ...
97
    def is_valid(self): ...
98

99
class SlidingWindowMapBuffer:
100
    def __init__(self, cursor=None, offset=0, size=sys.maxsize, flags=0): ...
101
    def begin_access(self, cursor=None, offset=0, size=sys.maxsize, flags=0): ...
102
    def end_access(self): ...
103
```
104

105
[Window Access](./window-access.md)
106

107
### Utilities
108

109
Memory alignment functions, system architecture detection, and utility classes for window management and memory region tracking.
110

111
```python { .api }
112
def align_to_mmap(num, round_up): ...
113
def is_64_bit(): ...
114

115
class MapWindow:
116
    def __init__(self, offset, size): ...
117
    def align(self): ...
118

119
class MapRegion:
120
    def __init__(self, path_or_fd, ofs, size, flags=0): ...
121
    def buffer(self): ...
122
```
123

124
[Utilities](./utilities.md)
125

126
## Constants
127

128
```python { .api }
129
ALLOCATIONGRANULARITY: int  # System memory allocation granularity (page size)
130
```
131

132
## Package Metadata
133

134
```python { .api }
135
__version__: str = "6.0.0"
136
version_info: tuple = (6, 0, 0)
137
__author__: str = "Sebastian Thiel"
138
__contact__: str = "byronimo@gmail.com"
139
__homepage__: str = "https://github.com/gitpython-developers/smmap"
140
```