Queues & Concurrency

Arkhein is a desktop application, and responsive user interfaces require offloading heavy work to background processes.

Queue Connections

• background: This is our primary queue connection for NativePHP. Use it for folder indexing, LLM inference, and Vektor rebuilds.
• default: Used for short-lived, transient tasks.

Concurrency Serialization

SQLite and Vektor's binary index are not built for highly concurrent access. To prevent data corruption, Arkhein enforces strict serialization of certain operations.

• Job Locks: Folder indexing jobs are locked at the job level. Only one indexing operation can occur for a specific folder_id at a time.
• Service Locks: MemoryService uses locks to ensure that only one Vektor rebuild can be performed at a time.

Invariants

• Desktop Responsiveness: No long-running or blocking task should ever occur in the main UI thread.
• Serialization over Speed: In local-first desktop contexts, data integrity and SSOT consistency are more important than maximum concurrent throughput.

Common Failures

Lock Timeouts

If a lock remains active (e.g., due to a process crash), subsequent jobs may fail with a "Lock Timeout." Use the application's native tools to clear stuck locks.

Queue Not Processing

If the background queue worker is not running, heavy tasks like indexing and AI responses will never complete. Ensure your NativePHP environment is correctly configured to start queue workers.