synology_apm_repo.sdk.dedup.presized_file module

Creating and opening the destination file an out-of-order export writes into.

Export writes land at bucket-major, non-monotonic offsets (export_scheduler.py), so the destination is created at its full logical size before any of them run and every write is positional.

On POSIX that is one ftruncate. On Windows it is up to three Win32 calls (two when not marking the file sparse), because the CRT’s own file-extending truncate writes the zeros for real rather than recording a size — a cost proportional to the export’s whole logical size, paid before the first byte of real data.

synology_apm_repo.sdk.dedup.presized_file.create_presized(dst, size, *, sparse)

Create or replace dst as an all-zero file of exactly size bytes.

Kept as one synchronous helper so a single asyncio.to_thread() covers the whole open/size/close, rather than three separate thread hops.

Parameters:

  • dst (Path) – Destination path. Replaced outright if it already exists.

  • size (int) – Final logical size, in bytes.

  • sparse (bool) – Whether unwritten regions may stay unallocated, mirroring the caller’s own sparse export option. This only ever affects whether the file is marked sparse on Windows, where that mark is what stops NTFS zero-filling behind an out-of-order write; POSIX gets an ordinary ftruncate either way. Neither branch reserves space up front — with sparse=False the allocation matches the logical size only once the export has written every hole’s zeros itself.

synology_apm_repo.sdk.dedup.presized_file.open_destination(dst)

Open an already-created dst for positional writes, returning its fd.

The one place the export’s destination fd is opened, so its flags are stated once. O_BINARY (0 off Windows) is not optional: Windows opens in text mode by default, which rewrites every \n in the exported bytes as \r\n.

Parameters:

dst (Path | str) – Path to an existing file, normally one create_presized() just sized.

Returns:

A writable file descriptor the caller owns and must close.

Return type:

int