Skip to content

Disconnect waits out a busy card, and Spotlight stays off it - #170

Merged
AliceLafox merged 4 commits into
mainfrom
fix/eject-busy-spotlight
Nov 5, 2026
Merged

AliceLafox merged 4 commits into
mainfrom
fix/eject-busy-spotlight

Conversation

@AliceLafox

Copy link
Copy Markdown
Member

Closes #169

The first Disconnect after a Connect was refused as busy while Spotlight indexed the card. This keeps Spotlight off the card from its next mount, waits out a busy card before the banner on all three platforms, and says why in words.

What changes

Spotlight stays off the card (core/.../Spotlight.hpp, CardClaim.hpp)

  • When the card's marker is found or minted, an empty .metadata_never_index is ensured at the volume root. Both places that reach a card's identity (the corner's name at Connect, the history's session for an operation) go through one claim.
  • The file is created only when nothing by that name exists, and exclusively (O_CREAT|O_EXCL|O_NOFOLLOW, CREATE_NEW). Whatever is already there (a file of any content, a directory, a link) is never rewritten, removed or followed. .Spotlight-V100 is not touched, and neither is the older loopercat-card.json.
  • A marker this build cannot read stops the claim before anything is written. A card that will not take the file (mounted read-only) is still known by its marker: the failure goes to operations.log instead of costing the card its name and history.
  • The write removes the one AppleDouble sidecar it causes (._.metadata_never_index, seen on macOS 26) and nothing else.

A busy card is waited out (app/EjectRetry.h)

  • One policy for the three DeviceWatcher backends: a busy answer is tried again, 5 tries 1 s apart. Any other refusal is reported at once. A success on a later try is a success.
  • Each backend keeps only what it alone knows: how to make one unmount try, and what busy looks like there. macOS: unix_err(EBUSY) or a busy dissenter. Linux: udisks2's DeviceBusy. Windows: a refused volume lock.
  • The old Linux and Windows ladders (5 × 400 ms) are folded into the policy, so tries do not multiply.
  • On macOS the disk is resolved once, on the caller's thread. The retries on DiskArbitration's queue never statfs a volume that might be wedged.
  • A volume someone else unmounted between two tries (kDAReturnNotMounted) counts as the eject done.
  • The quit bound goes from 5 s to 8 s, held above the longest eject by a static_assert.
  • While an eject is in flight, the worker stops scanning the card. Its own open files would otherwise be a holder the retries wait for.

Words

  • operations.log before: disconnect: eject refused (refused with status 49168)
  • operations.log now: disconnect: eject refused after 5 tries (busy: another program holds a file on the card), or disconnect: ejected after 2 tries when a retry saved it.
  • The banner keeps its sentence and drops the number for a busy card.

Facts measured

  • The status code: 49168 is 0xC010 = unix_err(EBUSY), the kernel's EBUSY as DiskArbitration encodes it. The issue calls it kDAReturnBusy, but that is 0xF8DA0002, the code a dissenting client returns. Both are treated as busy.
  • DiskArbitration answers (FAT32 disk image served by the same FSKit msdos module as the card, macOS 26 / Darwin 25.5, 2026-11-03):
    • a file held open: 0xC010 in 238–498 ms per try, which reproduces the issue's code;
    • after the file is released: unmounted in 232 ms;
    • a volume already unmounted: kDAReturnNotMounted;
    • a detached disk: kDAReturnBadArgument.
  • .metadata_never_index is still honoured on macOS 26. Same kind of FAT32 volume, with indexing switched on and a .Spotlight-V100 store in place:
    • mdutil -s before the file: "Indexing enabled."
    • after a remount with the file: "Indexing and searching disabled."
    • writing the file to a mounted volume changes nothing for that mount. Spotlight decides at mount time, so the retries still cover the first session.
  • On the RC-5 itself: pending, filled in after the hardware check below.

Tests

  • card_claim_tests (new): synthetic cards checked against the claim and the never-index file:
    • minted vs found;
    • an existing file, directory or dangling link left alone;
    • exclusive creation;
    • a foreign marker;
    • a missing volume;
    • a read-only root;
    • only the write's own sidecar removed;
    • memory banks, takes, the marker, .Spotlight-V100 and the old marker file byte-identical.
  • eject_retry_tests (new): the policy with fed-in answers:
    • always busy → exactly 5 tries, 4 pauses of 1 s, then the banner;
    • a non-busy refusal reported at once;
    • busy then success → ejected after 2 tries;
    • success on the last try;
    • answers that arrive later from another thread;
    • a double report refused;
    • the exact log lines;
    • the quit bound against the longest eject;
    • all three backends drive through the policy, with no ladders left underneath.
  • first_seen_tests: meeting a card leaves the file.
  • pedal_monitor_harness: a card changed on disk during an eject is not read until the eject resolves.
  • Mutations broken on purpose: 16, caught 15. They covered the retry count, retrying refusals, the words, the banner number, exclusive creation, the sweep's reach, the claim's order, the read-only path, the classification, the worker scan and the quit bound (the build fails). The one survivor is equivalent on POSIX: dropping the look-before-create is covered by O_EXCL.

Not verified here

  • The mdutil -s reading on the RC-5 after Connect → Disconnect → Connect with this build. It needs the pedal and the app's removable-volume permission.
  • A power cycle of the RC-5 and the RC-500 with .metadata_never_index at the root. Root files proven so far are loopercat.toml and macOS's directories; a zero-byte dot file is new.
  • Linux and Windows are built only by CI. On those platforms the busy pause is now 1 s instead of 400 ms, and the never-index file is written there too: it costs nothing and protects the card the day it meets a Mac.

The first Disconnect after a Connect was refused as busy on 2026-10-19 and
2026-11-02 (issue #169): Spotlight indexes the pedal's card right after every
mount, which is exactly when a player disconnects after a quick look, and an
indexer's open file refuses the unmount.

An empty .metadata_never_index at the volume root tells Spotlight to leave
the volume alone. It is still honoured on macOS 26: on a FAT32 volume served
by the same FSKit msdos module as the card, with indexing switched on and a
.Spotlight-V100 store in place, `mdutil -s` read "Indexing enabled." before
the file and "Indexing and searching disabled." after a remount with it.

The file is written where the card's identity is reached - the corner's name
at Connect and the history's session for an operation - through one claim
(CardClaim.hpp): the marker is read, or minted when the card has none, and
then Spotlight.hpp makes sure the file is there. It is created only when
nothing by that name exists, exclusively, so whatever is there - any file, a
directory, a link - is never rewritten, removed or followed; .Spotlight-V100
is not touched. A marker this build cannot read stops the claim before
anything is written. A write ends with the root sidecar sweep, as every
marker write does; no write, no sweep. operations.log says when the file was
written. Linux and Windows read no such file; it costs nothing there and
protects the card the day it meets a Mac.
…ords

The first Disconnect after a Connect showed "The volume would not eject ...
(refused with status 49168)" while Spotlight indexed the card (issue #169).
diskarbitrationd's log of it: no client dissented, the kernel refused the
unmount with EBUSY. 49168 is 0xC010, unix_err(EBUSY) as DiskArbitration hands
a BSD error back - not kDAReturnBusy, which is a dissenting client's code. A
second press a moment later went through.

EjectRetry.h is now the eject's policy on all three platforms: a busy answer
is tried again, five tries one second apart - about four seconds, the second
press the player made by hand, made for them - and only a hold that outlives
that reaches the banner. Any other refusal is told at once, and a success on
a later try is a success. Each backend keeps what only it knows: how to make
one unmount try and what busy looks like there (EBUSY or a busy dissenter on
macOS, udisks2's DeviceBusy on Linux, a refused volume lock on Windows). The
Linux and Windows ladders of their own (five tries, 400 ms) are folded into
it, so tries do not multiply. On macOS the pause runs on the watcher's queue
and is a no-op once the watcher is gone, like the auto-mount grace.

operations.log now says "eject refused after 5 tries (busy: another program
holds a file on the card)" instead of the status number, and "ejected after
2 tries" when a retry saved it. The banner keeps its sentence and adds the
OS's words only for a refusal that is not busy.
The worker kept scanning the card every 1.5 s while ejecting: the memory
banks, every track folder, the uncached probe of MEMORY1.RC0. The lifecycle
machine already threw those scans away until the completion, but the files
they opened were real, and with the eject now waiting out a busy card a scan
landing between two tries is a holder the retries would wait for - the app
standing in its own way. While ejecting the worker now delivers the card as
last seen, in the ejecting state, and reads nothing until the completion.

pedal_monitor_harness proves it: the card changes on disk while an eject is
in flight and no delivery shows the change, until a refusal returns the
worker to connected and the next scan does.
… locked card keeps its name

A fresh pair of eyes found two ways the fix could hurt more than the busy
banner it removes, and a handful of smaller ones.

The retries on macOS ran the whole unmount setup again on DiskArbitration's
queue, statfs of the volume included. On a wedged FSKit mount (2026-07-22) a
statfs never returns: every callback on that queue would have stopped, and
the destructor's drain with them, so the app could not even quit. The disk is
now resolved once, on the caller's thread, and held; the tries on the queue
only ask DiskArbitration.

A quit waited 5 s for the release, and the retries alone could take longer:
measured on a FAT32 image through the card's FSKit module (2026-11-03), a
held file is refused with 0xC010 - the very 49168 of the issue - in
0.24-0.50 s per try, so five tries and four pauses take up to 6.5 s. A quit
that left in the middle dropped an unmount DiskArbitration could still carry
out, leaving the pedal in STORAGE with its volume gone. The bound is 8 s now,
and a static_assert holds it above the longest eject (EjectRetry.h names
both numbers).

A card the system mounts read-only - FAT after an error, a locked card -
would have lost its name, its first-seen baseline and every history-backed
operation to a never-index file it could not take. The marker is the
identity and the file is a courtesy: the claim now reports the failure
(operations.log says so) and goes on as it always did.

Smaller:

- the write swept the whole card's junk on a card that merely lacked the
  file; it now removes the one sidecar it caused, so a connect that only met
  the card still leaves everything of the card's where it was.
- a volume someone else unmounted between two tries (kDAReturnNotMounted,
  measured) is the eject done, not a banner about a card still in use.
- the log line about the file was written only when the pedal was still the
  one being read; it is told before that check now, since the file is on the
  card either way.
- the comment on a busy try's detail said it was kept for the trace; the
  trace names the cause in words, as the issue asked, and carries no number.
- the harness's mid-eject check passed on an empty snapshot; it now insists
  the held card is whole.

Not changed: a yank inside the retry window still ends as a refusal and a
ghost (a detached disk answers kDAReturnBadArgument); whether a mount
outlived its device is the ghost path's question.
@AliceLafox
AliceLafox merged commit 4003a33 into main Nov 5, 2026
9 of 10 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Disconnect: the first eject after Connect is refused as busy while Spotlight indexes the card

1 participant