An archive should only be modified by one action at a time. QRecall uses a couple of mechanisms to prevent multiple actions from trying to change the archive simultaneously, something that would undoubtedly result in corruption of the archive's data structure.
You may occasionally encounter an action that never starts, reporting that it is "Waiting on archive" or "Waiting for permission to open archive." Here are the possible causes, and what to do about them.
It's entirely possible that there's a QRecall action or application using the archive.
Within a few minutes, the waiting action should start running.
Another potential problem can occur with file servers. QRecall uses filesystem advisory locks to notify other QRecall processes that an archive is being modified and those other actions will have to wait their turn.
When an archive is shared on a file server, the file server manages the advisory locks for remote clients. This is where the problem can occur; if a remote system places an advisory lock on an archive, and the server later loses its connection with that client, the advisory lock can live on forever, blocking all future attempts to open the archive (even from the original client).
If you're technically inclined, you might be able to confirm that the server is holding an advisory lock.
For example, on an macOS system the command
sudo lsof will list all of the open file descriptors in the system.
Execute that command on the file server and look for a fileserver process (smbd) that has an
archive data file (/Volume/Shared/Backups/Laptops.archive/repository.data) open.
If you find one, it means the server's file sharing service is keeping open an archive file for one of its clients. But if none of the server's clients are updating that archive, it means the file is stuck.
You can usually correct this by:
Restarting the service will cause the server to forget all of the advisory locks it made on behalf of its clients. This can often be awkward, especially if you have clients actively using the server, but it is often the only way to get the server to forget its advisory locks.
Not all filesystems and servers support advisory locks. So that your archive doesn't become damaged when stored on a foreign filesystem, QRecall employs a second line of defense: semaphore lock files.
Semaphore file locks are invisible files stored in the archive package, and updated to indicate what is happening to the archive.
If an action process terminates abnormally (power failure), or if it loses access with the archive (the dog unplugs the network router), it can leave these files in their locked state, blocking other actions from accessing the archive.
The remedy for this problem is simple:
When an action can't access an archive because it's reported to be busy, the action starts a series of tests to determine if the archive really is being updated by another QRecall action.
If it determines that the archive is not being updated—meaning the semaphore lock files are stale—it will automatically reset the lock files and proceed with its action.
These tests can take anywhere from 2 to 20 minutes to conclude.