Skip to content

Alignment

provide.foundation.file.alignment

Memory and file alignment utilities for binary I/O and mmap operations.

Provides functions for aligning offsets to power-of-2 boundaries, which is critical for: - Memory-mapped file operations (mmap requires page alignment) - Binary file formats and protocols - Database and index structures - Network packet alignment

Functions

align_offset 

align_offset(
    offset: int, alignment: int = DEFAULT_ALIGNMENT
) -> int

Align offset to specified boundary.

Aligns an offset up to the next boundary. The alignment must be a power of 2.

Parameters:

Name Type Description Default
offset int

The offset to align (in bytes)

 required
alignment int

Alignment boundary in bytes (must be power of 2)

 DEFAULT_ALIGNMENT

Returns:

Type Description
int

Aligned offset (>= input offset)

Raises:

Type Description
ValueError

If alignment is not a power of 2 or is <= 0

Examples:

>>> align_offset(10, 16)
16
>>> align_offset(16, 16)
16
>>> align_offset(17, 16)
32
>>> align_offset(0, 16)
0
Notes

Uses bit manipulation for efficiency: aligned = (offset + alignment - 1) & ~(alignment - 1)

Source code in provide/foundation/file/alignment.py 
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
def align_offset(offset: int, alignment: int = DEFAULT_ALIGNMENT) -> int:
    """Align offset to specified boundary.

    Aligns an offset up to the next boundary. The alignment must be a power of 2.

    Args:
        offset: The offset to align (in bytes)
        alignment: Alignment boundary in bytes (must be power of 2)

    Returns:
        Aligned offset (>= input offset)

    Raises:
        ValueError: If alignment is not a power of 2 or is <= 0

    Examples:
        >>> align_offset(10, 16)
        16
        >>> align_offset(16, 16)
        16
        >>> align_offset(17, 16)
        32
        >>> align_offset(0, 16)
        0

    Notes:
        Uses bit manipulation for efficiency:
        aligned = (offset + alignment - 1) & ~(alignment - 1)
    """
    if alignment <= 0 or (alignment & (alignment - 1)) != 0:
        raise ValueError(f"Alignment must be a positive power of 2, got {alignment}")

    return (offset + alignment - 1) & ~(alignment - 1)

align_to_page 

align_to_page(
    offset: int, page_size: int = PAGE_SIZE_4K
) -> int

Align offset to page boundary for optimal mmap performance.

Page alignment is required for memory-mapped file operations on most systems. Common page sizes: - 4KB (4096 bytes): Most x86_64 systems, Linux, Windows - 16KB (16384 bytes): Apple Silicon (M1/M2/M3), some ARM64 systems

Parameters:

Name Type Description Default
offset int

The offset to align (in bytes)

 required
page_size int

Page size in bytes (default: 4096)

 PAGE_SIZE_4K

Returns:

Type Description
int

Page-aligned offset (>= input offset)

Raises:

Type Description
ValueError

If page_size is not a power of 2

Examples:

>>> align_to_page(100)
4096
>>> align_to_page(4096)
4096
>>> align_to_page(4097)
8192
>>> align_to_page(100, page_size=16384)
16384
See Also

get_system_page_size() for detecting the system's page size

Source code in provide/foundation/file/alignment.py 
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
def align_to_page(offset: int, page_size: int = PAGE_SIZE_4K) -> int:
    """Align offset to page boundary for optimal mmap performance.

    Page alignment is required for memory-mapped file operations on most systems.
    Common page sizes:
    - 4KB (4096 bytes): Most x86_64 systems, Linux, Windows
    - 16KB (16384 bytes): Apple Silicon (M1/M2/M3), some ARM64 systems

    Args:
        offset: The offset to align (in bytes)
        page_size: Page size in bytes (default: 4096)

    Returns:
        Page-aligned offset (>= input offset)

    Raises:
        ValueError: If page_size is not a power of 2

    Examples:
        >>> align_to_page(100)
        4096
        >>> align_to_page(4096)
        4096
        >>> align_to_page(4097)
        8192
        >>> align_to_page(100, page_size=16384)
        16384

    See Also:
        get_system_page_size() for detecting the system's page size
    """
    return align_offset(offset, page_size)

calculate_padding 

calculate_padding(
    current_offset: int, alignment: int = DEFAULT_ALIGNMENT
) -> int

Calculate padding bytes needed to align to boundary.

Parameters:

Name Type Description Default
current_offset int

Current offset position (in bytes)

 required
alignment int

Desired alignment boundary (in bytes)

 DEFAULT_ALIGNMENT

Returns:

Type Description
int

Number of padding bytes needed (0 if already aligned)

Raises:

Type Description
ValueError

If alignment is not a power of 2 or is <= 0

Examples:

>>> calculate_padding(10, 16)
6
>>> calculate_padding(16, 16)
0
>>> calculate_padding(17, 16)
15
>>> calculate_padding(100, 64)
28
Notes

This is useful when writing binary formats where you need to insert padding bytes to maintain alignment.

Source code in provide/foundation/file/alignment.py 
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
def calculate_padding(current_offset: int, alignment: int = DEFAULT_ALIGNMENT) -> int:
    """Calculate padding bytes needed to align to boundary.

    Args:
        current_offset: Current offset position (in bytes)
        alignment: Desired alignment boundary (in bytes)

    Returns:
        Number of padding bytes needed (0 if already aligned)

    Raises:
        ValueError: If alignment is not a power of 2 or is <= 0

    Examples:
        >>> calculate_padding(10, 16)
        6
        >>> calculate_padding(16, 16)
        0
        >>> calculate_padding(17, 16)
        15
        >>> calculate_padding(100, 64)
        28

    Notes:
        This is useful when writing binary formats where you need to insert
        padding bytes to maintain alignment.
    """
    if alignment <= 0 or (alignment & (alignment - 1)) != 0:
        raise ValueError(f"Alignment must be a positive power of 2, got {alignment}")

    aligned = align_offset(current_offset, alignment)
    return aligned - current_offset

get_system_page_size 

get_system_page_size() -> int

Get the system's page size.

Returns:

Type Description
int

Page size in bytes (typically 4096 or 16384)

Examples:

>>> size = get_system_page_size()
>>> size in (4096, 16384, 8192, 65536)
True
Notes

Uses os.sysconf('SC_PAGE_SIZE') on Unix-like systems. Falls back to PAGE_SIZE_4K if detection fails.

Source code in provide/foundation/file/alignment.py 
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
def get_system_page_size() -> int:
    """Get the system's page size.

    Returns:
        Page size in bytes (typically 4096 or 16384)

    Examples:
        >>> size = get_system_page_size()
        >>> size in (4096, 16384, 8192, 65536)
        True

    Notes:
        Uses os.sysconf('SC_PAGE_SIZE') on Unix-like systems.
        Falls back to PAGE_SIZE_4K if detection fails.
    """
    import os

    try:
        # Unix-like systems
        return os.sysconf("SC_PAGE_SIZE")
    except (AttributeError, ValueError, OSError):
        # Fallback to common default
        return PAGE_SIZE_4K

is_aligned 

is_aligned(
    offset: int, alignment: int = DEFAULT_ALIGNMENT
) -> bool

Check if offset is aligned to boundary.

Parameters:

Name Type Description Default
offset int

The offset to check (in bytes)

 required
alignment int

Alignment boundary in bytes

 DEFAULT_ALIGNMENT

Returns:

Type Description
bool

True if offset is aligned to the boundary

Raises:

Type Description
ValueError

If alignment is not a power of 2 or is <= 0

Examples:

>>> is_aligned(16, 16)
True
>>> is_aligned(17, 16)
False
>>> is_aligned(0, 16)
True
>>> is_aligned(4096, 4096)
True
Notes

Uses bit manipulation for efficiency: is_aligned = (offset & (alignment - 1)) == 0

Source code in provide/foundation/file/alignment.py 
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
def is_aligned(offset: int, alignment: int = DEFAULT_ALIGNMENT) -> bool:
    """Check if offset is aligned to boundary.

    Args:
        offset: The offset to check (in bytes)
        alignment: Alignment boundary in bytes

    Returns:
        True if offset is aligned to the boundary

    Raises:
        ValueError: If alignment is not a power of 2 or is <= 0

    Examples:
        >>> is_aligned(16, 16)
        True
        >>> is_aligned(17, 16)
        False
        >>> is_aligned(0, 16)
        True
        >>> is_aligned(4096, 4096)
        True

    Notes:
        Uses bit manipulation for efficiency:
        is_aligned = (offset & (alignment - 1)) == 0
    """
    if alignment <= 0 or (alignment & (alignment - 1)) != 0:
        raise ValueError(f"Alignment must be a positive power of 2, got {alignment}")

    return (offset & (alignment - 1)) == 0

is_power_of_two 

is_power_of_two(value: int) -> bool

Check if a value is a power of 2.

Parameters:

Name Type Description Default
value int

Value to check

 required

Returns:

Type Description
bool

True if value is a power of 2

Examples:

>>> is_power_of_two(16)
True
>>> is_power_of_two(17)
False
>>> is_power_of_two(4096)
True
>>> is_power_of_two(0)
False
Notes

Uses bit manipulation: (value & (value - 1)) == 0

Source code in provide/foundation/file/alignment.py 
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
def is_power_of_two(value: int) -> bool:
    """Check if a value is a power of 2.

    Args:
        value: Value to check

    Returns:
        True if value is a power of 2

    Examples:
        >>> is_power_of_two(16)
        True
        >>> is_power_of_two(17)
        False
        >>> is_power_of_two(4096)
        True
        >>> is_power_of_two(0)
        False

    Notes:
        Uses bit manipulation: (value & (value - 1)) == 0
    """
    return value > 0 and (value & (value - 1)) == 0