swift-async-conveyor

1.0.1

A lightweight Swift utility that ensures async tasks run in strict FIFO order, providing simple and efficient serial execution for concurrency control across all Apple platforms.
0xfeedface1993/swift-async-conveyor

What's New

1.0.1

2025-07-04T13:02:17Z

Full Changelog: 1.0.0...1.0.1

๐Ÿšš AsyncConveyor

SwiftPM Compatible Platform License: MIT

A lightweight Swift concurrency utility to ensure closures are executed serially, one at a time.

AsyncConveyor is a concurrency control primitive that guarantees only one async block runs at a time. When multiple tasks invoke run(_:), they are automatically queued and executed in FIFO order. Ideal for controlling access to critical resources like databases, files, or network sessions.


๐Ÿ”ง Features

  • ๐Ÿ” Serial execution of async closures
  • โœ… Supports structured concurrency and cancellation handling
  • ๐Ÿงต Lock-free internal implementation using ManagedCriticalState
  • ๐Ÿงช Well-suited for unit testing and task coordination scenarios
  • ๐Ÿง No external dependencies except Swift standard concurrency APIs

๐Ÿ“ฆ Requirements

  • Swift 5.9+
  • Concurrency enabled (Swift Concurrency runtime)
  • Supported Platforms:
    • iOS 13+
    • macOS 10.15+
    • watchOS 6+
    • tvOS 13+

๐Ÿš€ Installation

Use Swift Package Manager:

.package(url: "https://github.com/0xfeedface1993/swift-async-conveyor.git", from: "1.0.0")

Then add "AsyncConveyor" to your target dependencies.


๐Ÿง‘โ€๐Ÿ’ป Usage

import AsyncConveyor

let conveyor = AsyncConveyor()

Task {
    try await conveyor.run {
        print("Task A starting")
        try await Task.sleep(nanoseconds: 1_000_000_000)
        print("Task A finished")
    }
}

Task {
    try await conveyor.run {
        print("Task B starting")
        try await Task.sleep(nanoseconds: 500_000_000)
        print("Task B finished")
    }
}

โœ… Output

Task A starting
Task A finished
Task B starting
Task B finished

Note: Even though Task B starts earlier in wall time, it waits for Task A to complete before executing.


๐Ÿ›‘ Cancellation Safety

If a task is cancelled while waiting or running, AsyncConveyor ensures:

  • The task is properly removed from the internal queue
  • The next task resumes correctly
  • No memory leaks or deadlocks

๐Ÿ”’ Use Cases

  • Serializing file reads/writes
  • Managing access to a database or cache
  • Enforcing order of operations in state machines
  • Coordinating request pipelines
  • Preventing overlapping animations or transitions

๐Ÿงช Testing Tips

  • Each .run { } block is awaited and can be tested deterministically.
  • Consider injecting AsyncConveyor as a dependency when testing logic that depends on ordering.

๐Ÿง  Design Philosophy

AsyncConveyor follows a minimal locking, actor-free design by using ManagedCriticalState to efficiently manage internal state. It behaves similarly to a serial DispatchQueue, but with native async/await and structured cancellation.


๐Ÿ‘ท Contributions

Contributions and feedback are welcome! Please open issues or PRs.

Description

  • Swift Tools 5.10.0
View More Packages from this Author

Dependencies

Last updated: Sun Jul 06 2025 00:13:14 GMT-0900 (Hawaii-Aleutian Daylight Time)