|
1 | | -# dispatch-async |
| 1 | +# swift-dispatch-async |
| 2 | + |
| 3 | +## ⚠️ WARNING - This is an 🧪experimental🧪 repository and should not be adopted at large. |
| 4 | + |
| 5 | +DispatchAsync is a temporary experimental repository aimed at implementing missing Dispatch support in the SwiftWasm toolchain. |
| 6 | +Currently, [SwiftWasm doesn't include Dispatch](https://book.swiftwasm.org/getting-started/porting.html#swift-foundation-and-dispatch). |
| 7 | +But, SwiftWasm does support Swift Concurrency. DispatchAsync implements a number of common Dispatch API's using Swift Concurrency |
| 8 | +under the hood. |
| 9 | + |
| 10 | +Dispatch Async does not provide blocking API's such as `DispatchQueue.sync`, primarily due to the intentional lack of blocking |
| 11 | +API's in Swift Concurrency. |
| 12 | + |
| 13 | +# Toolchain Adoption Plans |
| 14 | + |
| 15 | +DispatchAsync is not meant for consumption abroad directly as a new Swift Module. Rather, the intention is to provide eventual integration |
| 16 | +as a drop-in replacement for Dispatch when compiling to Wasm. |
| 17 | + |
| 18 | +There are a few paths to adoption into the Swift toolchain |
| 19 | + |
| 20 | +- DispatchAsync can be emplaced inside the [libDispatch repository](https://github.com/swiftlang/swift-corelibs-libdispatch), and compiled |
| 21 | +into the toolchain only for wasm targets. |
| 22 | +- DispatchAsync can be consumed in place of libDispatch when building the Swift toolchain. |
| 23 | + |
| 24 | +Ideally, with either approach, this repository would transfer ownership to the swiftlang organization. |
| 25 | + |
| 26 | +In the interim, to move wasm support forward, portions of DispatchAsync may be inlined (copy-pasted) |
| 27 | +into various libraries to enable wasm support. DispatchAsync is designed for this purpose, and has |
| 28 | +special `#if` handling to ensure that existing temporary usages will be elided without breakage |
| 29 | +the moment SwiftWasm adds support for `Dispatch` into the toolchain. |
| 30 | + |
| 31 | +# DispatchSemaphore Limitations |
| 32 | + |
| 33 | +The current implementation of `DispatchSemaphore` has some limitations. Blocking threads goes against the design goals of Swift Concurrency. |
| 34 | +The `wait` function on `DispatchSemaphore` goes against this goal. Furthermore, most wasm targets run on a single thread from the web |
| 35 | +browser, so any time the `wait` function ends up blocking the calling thread, it would almost certainly freeze the single-threaded wasm |
| 36 | +executable. |
| 37 | + |
| 38 | +To navigate these issues, there are some limitations: |
| 39 | + |
| 40 | +- For wasm compilation targets, `DispatchSemaphore` assumes single-threaded execution, and lacks various safeguards that would otherwise |
| 41 | +be needed for multi-threaded execution. This makes the implementation much easier. |
| 42 | +- For wasm targets, calls to `signal` and `wait` must be balanced. An assertion triggers if `wait` is called more times than `signal`. |
| 43 | +- DispatchSemaphore is deprecated for wasm targets, and AsyncSemaphore is encouraged as the replacement. |
| 44 | +- For non-wasm targets, DispatchSemaphore is simply a typealias for `AsyncSemaphore`, and provides only a non-blocking async `wait` |
| 45 | +function. This reduces potential issues that can arise from wait being a thread-blocking function. |
| 46 | + |
| 47 | +# Usage |
| 48 | + |
| 49 | +If you've scrolled this far, you probably saw the warning. But just to make sure… |
| 50 | + |
| 51 | +> ⚠️ WARNING - This is an 🧪experimental🧪 repository and should not be adopted at large at the present time. |
| 52 | +
|
| 53 | +PassiveLogic is [actively working](https://github.com/PassiveLogic/swift-web-examples/issues/1) to mainstream this into the SwiftWasm |
| 54 | +toolchain. But if you can't wait, here are some tips. |
| 55 | + |
| 56 | +## 1. Only use this for WASI platforms, and only if Dispatch cannot be imported. |
| 57 | + |
| 58 | +Use `#if os(WASI) && !canImport(Dispatch)` to elide usages outside of WASI platforms: |
| 59 | + |
| 60 | +```swift |
| 61 | +#if os(WASI) && !canImport(Dispatch) |
| 62 | +import DispatchAsync |
| 63 | +#else |
| 64 | +import Dispatch |
| 65 | +#endif |
| 66 | + |
| 67 | +// Use Dispatch API's the same way you normal would. |
| 68 | +``` |
| 69 | + |
| 70 | +## 2. If you really want to use DispatchAsync as a pure Swift Dispatch alternative for non-wasm targets |
| 71 | + |
| 72 | +Stop. Are you sure? If you do this, you'll need to be careful with all `import Dispatch`, `import Foundation`, and many other issues. |
| 73 | + |
| 74 | +1. Add the dependency to your package: |
| 75 | + |
| 76 | +```swift |
| 77 | +let package = Package( |
| 78 | + name: "MyPackage", |
| 79 | + products: [ |
| 80 | + .library( |
| 81 | + name: "MyPackage", |
| 82 | + targets: [ |
| 83 | + "MyPackage" |
| 84 | + ] |
| 85 | + ), |
| 86 | + ], |
| 87 | + dependencies: [ |
| 88 | + .package( |
| 89 | + url: "https://github.com/PassiveLogic/swift-dispatch-async.git", |
| 90 | + from: "0.0.1" |
| 91 | + ), |
| 92 | + ], |
| 93 | + targets: [ |
| 94 | + .target( |
| 95 | + name: "MyPackage" |
| 96 | + dependencies: [ |
| 97 | + .product(name: "DispatchAsync", package: "swift-dispatch-async", condition: .when(platforms: [.wasi])), |
| 98 | + ] |
| 99 | + ), |
| 100 | + ] |
| 101 | +) |
| 102 | +``` |
| 103 | + |
| 104 | +2. Import and use DispatchAsync in place of Dispatch like this: |
| 105 | + |
| 106 | +```swift |
| 107 | +#if os(WASI) && !canImport(Dispatch) |
| 108 | +import DispatchAsync |
| 109 | +#else |
| 110 | +// Non-WASI platforms have to explicitly bring in DispatchAsync |
| 111 | +// by using `@_spi`. |
| 112 | +@_spi(DispatchAsync) import DispatchAsync |
| 113 | +#endif |
| 114 | + |
| 115 | +// Not allowed, brings in Dispatch, aka "the real GCD": |
| 116 | +// import Dispatch |
| 117 | + |
| 118 | +// Also not allowed, brings in Dispatch |
| 119 | +// import Foundation |
| 120 | + |
| 121 | +// You'll need to use scoped Foundation imports: |
| 122 | +import struct Foundation.URL // Ok. Doesn't bring in Dispatch |
| 123 | + |
| 124 | +// If you ignore the above notes, but do the following, be prepared for namespace |
| 125 | +// collisions between the toolchain's Dispatch and DispatchAsync: |
| 126 | + |
| 127 | +private typealias DispatchQueue = DispatchAsync.DispatchQueue // Ok as long as Dispatch isn't imported |
| 128 | + |
| 129 | +// Ok. If you followed everything above, you can now do the following, using pure Swift |
| 130 | +// under the hood! 🎉 |
| 131 | +DispatchQueue.main.async { |
| 132 | + // Run your code here… |
| 133 | +} |
| 134 | +``` |
| 135 | + |
| 136 | +# LICENSE |
| 137 | + |
| 138 | +This project is distributed by PassiveLogic under the Apache-2.0 license. See |
| 139 | +[LICENSE](https://github.com/PassiveLogic/swift-dispatch-async/blob/main/LICENSE) for full terms of use. |
| 140 | + |
0 commit comments