Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions src/pt_snap_cli/snapshot/PROVENANCE.md
Original file line number Diff line number Diff line change
Expand Up @@ -113,6 +113,10 @@ The upstream standalone split frontend is deliberately excluded, not deferred:
- On 2026-08-01, PR #81 follow-up deferred slice buffer and boundary-state
cleanup until serialization succeeds, preserving retryable state on I/O
failure.
- On 2026-08-06, PR #82 optimized snapshot replay mutation and adjacent
segment lookup by reusing discovered indices and standard-library keyed
binary search. This is a local performance change against the first-party
runtime; audited upstream source mappings and license terms are unchanged.

## Migration toolchain

Expand Down
59 changes: 46 additions & 13 deletions src/pt_snap_cli/snapshot/simulate/simulated_caching_allocator.py
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
import bisect
import copy

from ..base import Block, BlockState, Segment, TraceEntry
Expand All @@ -9,6 +10,46 @@
allocator_logger = get_logger("ALLOCATOR")


def _segment_address_key(segment: Segment) -> int:
return segment.address


def _find_adjacent_segment_indices(
segments: list[Segment], new_segment: Segment
) -> tuple[int, int]:
"""Find same-stream segments immediately adjacent to ``new_segment``.

Segment starts are sorted, so binary-search each endpoint and only inspect
neighboring ranges. Multiple streams can share an endpoint, which requires
scanning that small address group instead of assuming one fixed neighbor.
"""
new_start = new_segment.address
new_end = new_start + new_segment.total_size
stream = new_segment.stream

start_idx = bisect.bisect_left(segments, new_start, key=_segment_address_key)

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Finding 2 (low): this bisect-by-address assumes snapshot.segments stays address-sorted, which a left shrink can violate.

_shrink_segment(snapshot, ..., "left") in snapshot_mutator.py mutates segment.address = new_start in place without re-sorting the list. With overlapping cross-stream segments the list can become address-unsorted, and this new binary search then skips neighbors that the replaced linear scan still found. This is a latent dependency the PR adds rather than a new defect (_shrink_segment is unchanged), but the docstring's claim that "segment starts are sorted" is not enforced anywhere.

Suggested fix: re-insert/re-sort after a left shrink, or make the neighbor lookup ordering-insensitive (e.g. an endpoint index). A shrink-then-map regression test would pin the behavior.

left_adjacent_idx = -1
for idx in range(start_idx - 1, -1, -1):
segment = segments[idx]
segment_end = segment.address + segment.total_size
if segment.stream == stream and segment_end < new_start:
break
if segment_end == new_start and segment.stream == stream:
left_adjacent_idx = idx
break

end_idx = bisect.bisect_left(segments, new_end, key=_segment_address_key)
right_adjacent_idx = -1
for idx in range(end_idx, len(segments)):
segment = segments[idx]
if segment.address > new_end:
break
if segment.address == new_end and segment.stream == stream:
right_adjacent_idx = idx

return left_adjacent_idx, right_adjacent_idx


class SimulatedCachingAllocator:
def __init__(self, ctx: AllocatorContext):
self.ctx = ctx
Expand Down Expand Up @@ -80,7 +121,7 @@ def free_block(self, alloc_event: TraceEntry) -> bool:
return False
exist_block.alloc_event_idx = alloc_event.idx
self.dispatcher.pre_replay_free_block(exist_block, self.ctx.device_snapshot)
if not snapshot_mutator.detach_block(self.ctx.device_snapshot, exist_block):
if not snapshot_mutator.detach_block(self.ctx.device_snapshot, exist_block, block_idx):
allocator_logger.error(f"{_error}: block has no segment_ptr")
return False
self.dispatcher.post_replay_free_block(exist_block, self.ctx.device_snapshot, use_copy=True)
Expand Down Expand Up @@ -145,17 +186,9 @@ def alloc_or_map_segment(self, new_segment: Segment, merge: bool = False) -> boo
snapshot_mutator.insert_segment(self.ctx.device_snapshot, new_segment)
self.dispatcher.post_replay_map_or_alloc_segment(new_segment, self.ctx.device_snapshot)
return True
new_seg_start = new_segment.address
new_seg_end = new_seg_start + new_segment.total_size
left_adjacent_idx = -1
right_adjacent_idx = -1
for i, seg in enumerate(segments):
if seg.stream != new_segment.stream:
continue
if seg.address + seg.total_size == new_seg_start:
left_adjacent_idx = i
elif new_seg_end == seg.address:
right_adjacent_idx = i
left_adjacent_idx, right_adjacent_idx = _find_adjacent_segment_indices(
segments, new_segment
)
if left_adjacent_idx == -1 and right_adjacent_idx == -1:
snapshot_mutator.insert_segment(self.ctx.device_snapshot, new_segment)
self.dispatcher.post_replay_map_or_alloc_segment(new_segment, self.ctx.device_snapshot)
Expand Down Expand Up @@ -204,7 +237,7 @@ def free_segment(self, alloc_seg_event: TraceEntry) -> bool:

exist_seg.alloc_or_map_event_idx = alloc_seg_event.idx
self.dispatcher.pre_replay_unmap_or_free_segment(exist_seg, self.ctx.device_snapshot)
snapshot_mutator.remove_segment(self.ctx.device_snapshot, exist_seg)
snapshot_mutator.remove_segment(self.ctx.device_snapshot, exist_seg, exist_seg_idx)
self.dispatcher.post_replay_unmap_or_free_segment(exist_seg, self.ctx.device_snapshot)
return True

Expand Down
41 changes: 30 additions & 11 deletions src/pt_snap_cli/snapshot/simulate/snapshot_mutator.py
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,10 @@
snapshot_mutator_logger = get_logger("ALLOCATOR")


def _segment_sort_key(segment: Segment) -> tuple[int, int]:
return segment.address, segment.stream


# Public API: block mutation helpers


Expand All @@ -24,11 +28,13 @@ def attach_block(snapshot: DeviceSnapshot, segment: Segment, block: Block, inser
snapshot.total_allocated += block.size


def detach_block(snapshot: DeviceSnapshot, block: Block) -> bool:
def detach_block(snapshot: DeviceSnapshot, block: Block, block_idx: int | None = None) -> bool:
"""Detach a block from its owning segment.

Mutates the block, its segment, and snapshot totals in place.
Returns `True` on success, otherwise `False` when the block has no segment.
``block_idx`` can be supplied by callers that already searched for the block
to avoid a second linear lookup.
"""
segment = block.segment_ptr
if segment is None:
Expand All @@ -38,7 +44,9 @@ def detach_block(snapshot: DeviceSnapshot, block: Block) -> bool:
if block.state == BlockState.ACTIVE_ALLOCATED:
segment.allocated_size -= block.size
snapshot.total_allocated -= block.size
segment.blocks.remove(block)
if block_idx is None:
block_idx = segment.blocks.index(block)
del segment.blocks[block_idx]
block.segment_ptr = None
return True

Expand Down Expand Up @@ -70,14 +78,16 @@ def insert_segment(snapshot: DeviceSnapshot, segment: Segment):
snapshot.total_reserved += segment.total_size


def remove_segment(snapshot: DeviceSnapshot, segment: Segment):
def remove_segment(snapshot: DeviceSnapshot, segment: Segment, segment_idx: int | None = None):
"""Remove a segment from the snapshot and decrease reserved memory.

Clears every block's `segment_ptr` and mutates `snapshot.total_reserved`
in place.
"""
snapshot.total_reserved -= segment.total_size
snapshot.segments.remove(segment)
if segment_idx is None:
segment_idx = snapshot.segments.index(segment)
del snapshot.segments[segment_idx]
for block in segment.blocks:
block.segment_ptr = None

Expand Down Expand Up @@ -115,9 +125,8 @@ def merge_mapped_segment(
return _merge_segments(snapshot, left_adjacent_idx, right_adjacent_idx)
return True

_insert_segment_sorted(snapshot, new_segment)
new_idx = segments.index(new_segment)
corrected_right_idx = new_idx + 1
new_idx = _insert_segment_sorted(snapshot, new_segment)
corrected_right_idx = right_adjacent_idx + (new_idx <= right_adjacent_idx)
if corrected_right_idx >= len(segments):
snapshot_mutator_logger.error(f"{_error}: right adjacent segment missing after insert")
segments.remove(new_segment)
Expand Down Expand Up @@ -171,12 +180,16 @@ def decrease_reserved(snapshot: DeviceSnapshot, size: int):
# Private helpers


def _insert_segment_sorted(snapshot: DeviceSnapshot, segment: Segment):
def _insert_segment_sorted(snapshot: DeviceSnapshot, segment: Segment) -> int:
"""Insert a segment into `snapshot.segments` while preserving sort order."""
segments = snapshot.segments
keys = [(seg.address, seg.stream) for seg in segments]
idx = bisect.bisect_left(keys, (segment.address, segment.stream))
idx = bisect.bisect_left(
segments,
(segment.address, segment.stream),
key=_segment_sort_key,
)
segments.insert(idx, segment)
return idx


def _merge_segments(snapshot: DeviceSnapshot, target_idx: int, source_idx: int) -> bool:
Expand Down Expand Up @@ -329,6 +342,7 @@ def _shrink_segment(
)
return False
segment = segments[seg_idx]
repositioned = False
seg_start = segment.address
seg_end = seg_start + segment.total_size
shrink_end = shrink_addr + shrink_size
Expand All @@ -351,6 +365,8 @@ def _shrink_segment(
f"{_error}: active block [{block_start}, {block_end}) in shrink range [{shrink_addr}, {shrink_end})"
)
return False
del segments[seg_idx]
repositioned = True
segment.address = new_start
segment.total_size = new_size
segment.blocks = [block for block in segment.blocks if block.address >= new_start]
Expand Down Expand Up @@ -381,5 +397,8 @@ def _shrink_segment(
)
segment.active_size = sum(b.size for b in segment.blocks)
if segment.total_size == 0:
del segments[seg_idx]
if not repositioned:
del segments[seg_idx]
elif repositioned:
_insert_segment_sorted(snapshot, segment)
return True
95 changes: 95 additions & 0 deletions tests/snapshot/test_snapshot_mutator.py
Original file line number Diff line number Diff line change
Expand Up @@ -68,6 +68,31 @@ def test_detach_block_returns_false_when_block_has_no_segment():
assert_valid_segments(snapshot.segments)


def test_detach_block_uses_supplied_index():
first = make_block(0x1000, 0x100)
second = make_block(0x1200, 0x100)
segment = make_segment(0x1000, 0x1000, blocks=[first, second])
snapshot = make_snapshot([segment])

assert snapshot_mutator.detach_block(snapshot, second, 1) is True
assert segment.blocks == [first]
assert second.segment_ptr is None
assert_valid_snapshot(snapshot)


def test_remove_segment_uses_supplied_index():
first = make_segment(0x1000, 0x100)
second_block = make_block(0x1200, 0x40)
second = make_segment(0x1200, 0x100, blocks=[second_block])
snapshot = make_snapshot([first, second])

snapshot_mutator.remove_segment(snapshot, second, 1)

assert snapshot.segments == [first]
assert second_block.segment_ptr is None
assert snapshot.total_reserved == 0x100


def test_promote_pending_free_block_returns_false_without_segment():
snapshot = make_snapshot()
block = make_block(state=BlockState.ACTIVE_PENDING_FREE)
Expand Down Expand Up @@ -277,6 +302,76 @@ def test_alloc_or_map_segment_merge_keeps_snapshot_invariants(self):
self.assertEqual(0x180, allocator.ctx.device_snapshot.total_reserved)
assert_valid_snapshot(allocator.ctx.device_snapshot)

def test_alloc_or_map_segment_merge_finds_neighbors_across_streams(self):
left = make_segment(0x1000, 0x100, stream=0)
same_start_other_stream = make_segment(0x1000, 0x100, stream=1)
right = make_segment(0x1200, 0x100, stream=0)
same_end_other_stream = make_segment(0x1200, 0x100, stream=1)
allocator = make_allocator([left, same_start_other_stream, right, same_end_other_stream])
new_segment = make_segment(0x1100, 0x100, stream=0)

assert allocator.alloc_or_map_segment(new_segment, merge=True) is True

stream_zero_segments = [
segment for segment in allocator.ctx.device_snapshot.segments if segment.stream == 0
]
assert len(stream_zero_segments) == 1
assert stream_zero_segments[0].address == 0x1000
assert stream_zero_segments[0].total_size == 0x300
assert len(allocator.ctx.device_snapshot.segments) == 3
assert allocator.ctx.device_snapshot.total_reserved == 0x500

def test_alloc_or_map_segment_merge_scans_past_shorter_cross_stream_segment(self):
left = make_segment(0x1000, 0x100, stream=0)
shorter_other_stream = make_segment(0x1000, 0x80, stream=1)
allocator = make_allocator([left, shorter_other_stream])
new_segment = make_segment(0x1100, 0x100, stream=0)

assert allocator.alloc_or_map_segment(new_segment, merge=True) is True

stream_zero_segments = [
segment for segment in allocator.ctx.device_snapshot.segments if segment.stream == 0
]
assert len(stream_zero_segments) == 1
assert stream_zero_segments[0].address == 0x1000
assert stream_zero_segments[0].total_size == 0x200

def test_alloc_or_map_segment_merge_scans_shared_right_endpoint_group(self):
other_stream = make_segment(0x1200, 0x100, stream=0)
right = make_segment(0x1200, 0x100, stream=1)
allocator = make_allocator([other_stream, right])
new_segment = make_segment(0x1100, 0x100, stream=1)

assert allocator.alloc_or_map_segment(new_segment, merge=True) is True

stream_one_segments = [
segment for segment in allocator.ctx.device_snapshot.segments if segment.stream == 1
]
assert len(stream_one_segments) == 1
assert stream_one_segments[0].address == 0x1100
assert stream_one_segments[0].total_size == 0x200

def test_left_shrink_reinserts_segment_in_address_order(self):
segment = make_segment(0x1000, 0x1000, stream=0)
first_later_segment = make_segment(0x1800, 0x100, stream=1)
second_later_segment = make_segment(0x1850, 0x100, stream=2)
snapshot = make_snapshot([segment, first_later_segment, second_later_segment])

assert snapshot_mutator.split_or_shrink_segment(snapshot, 0, 0x1000, 0x900) is True

assert [(item.address, item.stream) for item in snapshot.segments] == [
(0x1800, 1),
(0x1850, 2),
(0x1900, 0),
]

def test_left_shrink_removes_segment_when_fully_consumed(self):
segment = make_segment(0x1000, 0x100)
snapshot = make_snapshot([segment])

assert snapshot_mutator.split_or_shrink_segment(snapshot, 0, 0x1000, 0x100) is True
assert snapshot.segments == []

def test_unmap_segment_keeps_snapshot_invariants(self):
segment = make_segment(0x1000, 0x200)
allocator = make_allocator([segment])
Expand Down
Loading