Parallel gadget scan with --jobs (#23, part 2)

[ricardojrdez]

Second and final part of #23 (the on-disk cache landed in #27). Closes #23.

--jobs N

Distributes the gadget scan over N worker processes. Each executable section is split into chunks scanned independently, then merged and deduplicated. The output is identical to a serial run.

How correctness is kept:

• A chunk emits only the gadgets whose termination offset falls inside its window. The slice handed to a worker extends depth bytes before the window so gadgets straddling a boundary are still complete, and the final chunk owns the closing offset of the section. No cross-chunk duplicates, none missed.
• The duplicate tie-break is now deterministic (fewest canary bytes, then lowest address), so serial and parallel produce byte-identical output (verified on a 32-bit busybox: same (vaddr, gadget, count) set for jobs 2/4/8).

Implementation:

• _scan_worker (module level, picklable) re-initialises the architecture in its own process and reuses the existing validity checks. Capstone decode objects are not picklable, so workers return raw [vaddr, hex] records and the parent rebuilds decodes/symbols (the same path as the cache).
• _scan_parallel builds the chunk tasks and runs a multiprocessing.Pool; results feed the existing reconstruct / dedup / cache path, so --jobs composes with --cache.
• utils.TOOL_NAME tolerates a __main__ without __file__ (needed for spawned workers and library use).
• Wired through GadFinder, the Rop3 API (jobs=) and the CLI (--jobs, validated >= 1).

Performance (honest numbers)

The speedup is sublinear: the merge, deduplication and sort run in the parent, plus per-process start-up cost. On a 1 MB busybox:

workload	serial	jobs=4	jobs=8
depth 10	1.46s	1.30s (1.12x)	1.16s (1.26x)
depth 20	3.78s	2.75s (1.38x)	2.21s (1.71x)

It is worth it for large binaries and/or high --depth; on small inputs the default --jobs 1 is faster. README documents this.

Testing

• 94 tests pass on Python 3.11 and 3.13 (+4).
• test_parallel.py: parallel output equals serial (including with --badchar-bytes/--depth and a ret as the last byte to exercise the closing boundary), and parallel results are cacheable.

Closes #23.