spill / docs · v0.7.3 · Source · Release notes

Limits and performance

Hard limits

Torrents beyond these limits are refused when added.

LimitValue
.torrent / metadata size16 MiB
Pieces per torrent1,048,576
Piece size512 MiB
Data files per torrent (excluding padding)100,000

V2 expanded piece commitments, cached proof-tree nodes above the piece layer, and expanded paths share a separate 16 MiB admission budget. Proof trees are cached per file root on first use. For one large file this allows approximately 262,000 pieces (256K), fewer when expanded paths consume part of the budget. Magnet size admission includes its trackers and required piece layers and runs before layer acquisition.

Only the first 32 web seeds of a torrent are used.

Offline torrent creation uses the same file, piece count, and metainfo-size ceilings. It accepts power-of-two piece sizes from 32 KiB to 256 MiB (default 256 KiB), follows symlinks, and limits paths to 32 levels including the torrent root. It rejects entirely empty directories; zero-length files are supported. A fixed piece size that would exceed the piece count or metainfo-size limit must be increased explicitly.

Daemon-wide limits:

LimitValue
Running torrents (active_downloads + active_seeds)64
Connections per torrent (peers)4096 (default 50)
Peers uploaded to at once, per torrent8
Config file size64 KiB

There is no limit on how many torrents the catalog holds; torrents beyond the active slots wait as queued.

Library callers have the same per-torrent resource bounds: Profile.peers must be 1–4096, and cache_bytes and write_queue_bytes must each be 16 KiB–1 GiB. Admission and magnet metadata resolution reject invalid profiles with InvalidInput before starting work. Profile::validate() checks these bounds without starting an execution.

Canonical peer replacement (BEP 40) may retain one waiting socket per torrent while the evicted peer task joins. The waiting socket starts no peer task until capacity is released; peers and session peer reservations remain unchanged.

Holepunch coordination

BEP 55 uses the ordinary session dial-token, pending-dial, peer and uTP limits; it has no reserved dial capacity or guaranteed admission latency.

BoundValue
Pending rendezvous per torrent8, at most one per target and introducer
Rendezvous lifetime, including output queueing10 seconds
Queued holepunch messages per connection8
Queued punch dial lifetime3 seconds
Incoming rendezvous processed per connection4 per 10-second window
Incoming connect messages processed per connection4 per 10-second window
Retained PEX introductions per connection200

Each incoming-message window starts on its first message. Rejected and duplicate requests consume the allowance too; excess requests are ignored without a reply. The next message after the window expires starts a new one. Relay pairs are queued only if both connections’ output queues have room. Expired punch-only dials are dropped. Upgraded ordinary contacts return to their original source and schedule. Duplicate introductions do not extend a queued punch’s lifetime. PEX introductions follow the existing one-minute receive gate and disappear when the connection closes or disables PEX.

Resource use

  • Memory: each running torrent may buffer up to cache_bytes + write_queue_bytes (32 MiB by default) at peak. Typical use is far lower.
  • Open files: spill keeps every file of a running torrent open while it runs. A torrent with 100,000 files uses about 100,000 file descriptors. The daemon raises its soft descriptor limit to the hard limit at startup on Linux. On macOS it uses the smaller of the hard limit and kern.maxfilesperproc; see Troubleshooting.
  • Threads: one async thread runs the daemon; disk I/O and hashing run on a blocking thread pool.

Measured baselines

Measured on a Linux desktop (Intel Core Ultra 7 265, ext4) on a local network, against Transmission 4.1. These are historical workload measurements, not rankings or guarantees for the current release. Raw summaries, source revisions, and workload details are in the baseline records.

ScenarioResult
1 GiB from one Transmission seedspill 11.2 s, Transmission 19.5 s
8 leechers × 256 MiB from one Transmission seedspill ~10.6 s (p50 of 10 runs), Transmission 13.7 s
33 torrents, 768 MiB, 4 download slots35 MiB peak memory, 118 open files, 1.5 ms p95 control latency
Restart with 33 complete torrents0.1 s, nothing downloaded again
One torrent with 100,000 files184 MiB peak memory, 100,018 open files; restart 9.7 s

The peer-wire comparisons include startup and choking delays. Filesystem caches were not dropped, some recorded source trees were dirty, and completion is not defined identically: spill includes its durability barrier; Transmission is observed through RPC progress. The 33-torrent workload uses local web seeds, not a peer-wire swarm. See the measurement methodology and per-run notes before drawing comparisons.

Known gaps

  • Automatic mapping supports NAT-PMP and UPnP IGD, not PCP or IPv6 pinholes.
  • V2 and hybrid interoperability has been checked only against libtorrent 2.1.2.0 on a controlled network; see Scope and v2 and hybrid torrents. Web-seed checks do not cover public-swarm capacity or HTTPS certificate interoperability.
  • Files of a running torrent stay open; torrents with very many files are costly (see above).