QwkSync

QWKSync.NET Concurrency Model

Core rules

QWKSync.NET enforces single-flight concurrency:

• Only one active sync may operate against the same local inbox, local outbox, or profile at a time.
• Concurrent attempts must fail fast with a clear error.
• Coordination is enforced by QWKSync.NET, not by transport extensions. 

This guarantee exists to prevent corruption, duplication, and non-deterministic behaviour. 

---

What is considered “the same”

Single-flight is defined in terms of the local locations and profile involved in the sync plan:

• QwkSyncPlan.LocalInboxDirectory
• QwkSyncPlan.LocalOutboxDirectory
• The profile used for the session (as a coordination scope) 

If any of these overlap between two sessions, QWKSync.NET treats them as a conflict and fails fast. Conflicts are detected by comparing normalised absolute paths using OS-appropriate comparison rules.

Transfer parallelism

Default behaviour is sequential processing:

• Discovery happens as a single operation.
• Downloads are processed one packet at a time.
• Uploads are processed one packet at a time.
• No parallel packet transfers by default. 

This is a deliberate constraint to keep behaviour deterministic and reduce safety risks. 

Threading assumptions

• QWKSync.NET makes no UI assumptions.
• Progress is reported through IProgress<QwkSyncProgress>? and must not affect behaviour. 
• Logging is via ISyncLogSink? without adding logging framework dependencies. 

Cancellation and concurrency

• All operations accept CancellationToken.
• Cancellation must interrupt I/O promptly.
• Cancellation must always trigger cleanup of temporary download files created by the session. 

Single-flight locks or guards must not prevent cancellation from being observed quickly. Avoid blocking waits. Acquire the guard before starting transfers, and ensure all waits honour cancellation.

Retry and concurrency

Retry is core-orchestrated, bounded, and deterministic. Defaults: no retries. 

When retries are enabled:

• Retries must not introduce parallelism.
• Retries must not weaken the single-flight guarantee.

Transport responsibilities

Transports implement the operations but do not own core-level coordination:

• All remote file operations go through ITransport.
• Resume behaviour is transport-owned, but is disabled by default and never assumed by QWKSync.NET. 

This site is open source. Improve this page.