Skip to content

Commit 007751a

Browse files
scottmarchantscottmarchant
authored
ci: Update CI and README in preparation for semantically stable release (#5)
* docs: Update README in preparation for semantic 1.0.0 release. * ci: Pin swift workflows to version 0.0.2 for now, to avoid CI breaking due to unstable changes.
1 parent d4251dd commit 007751a

File tree

3 files changed

+44
-49
lines changed

3 files changed

+44
-49
lines changed

‎.github/workflows/pull_request.yml‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -7,15 +7,15 @@ on:
77
jobs:
88
soundness:
99
name: Soundness
10-
uses: swiftlang/github-workflows/.github/workflows/soundness.yml@main
10+
uses: swiftlang/github-workflows/.github/workflows/soundness.yml@0.0.2
1111
with:
1212
format_check_container_image: swift:6.1.0-noble
1313
license_header_check_enabled: false
1414
api_breakage_check_enabled: false
1515

1616
tests:
1717
name: tests
18-
uses: swiftlang/github-workflows/.github/workflows/swift_package_test.yml@main
18+
uses: swiftlang/github-workflows/.github/workflows/swift_package_test.yml@0.0.2
1919
with:
2020
# Runners aren't set up for this currently in GitHub/PassiveLogic
2121
enable_macos_checks: false

‎README.md‎

Lines changed: 42 additions & 45 deletions
Original file line numberDiff line numberDiff line change
@@ -1,57 +1,20 @@
11
# swift-dispatch-async
22

3-
## ⚠️ WARNING - This is an 🧪experimental🧪 repository and should not be adopted at large.
3+
DispatchAsync provides a pure-swift implementation of `Dispatch`, powered by Swift Concurrency. It is currently intended for use only
4+
in WASM targets, but could be used in other scenarios should the need arise.
45

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.
6+
The Swift for WebAssembly SDK [doesn't currenty include Dispatch](https://book.swiftwasm.org/getting-started/porting.html#swift-foundation-and-dispatch).
7+
But, it does support Swift Concurrency. DispatchAsync implements a number of common Dispatch API's using Swift Concurrency
8+
under the hood. This allows `import DispatchAsync` to be used in wasm targets as a drop-in replacement anywhere `import Dispatch` is
9+
currently in use.
910

1011
Dispatch Async does not provide blocking API's such as `DispatchQueue.sync`, primarily due to the intentional lack of blocking
1112
API's in Swift Concurrency.
1213

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-
4714
# Usage
4815

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.
16+
PassiveLogic plans to mainstream this into the SwiftWasm toolchain. If possible, it's better to wait until this is part of the
17+
official Swift for WebAssembly SDK. But if you need this now, below are some usage tips.
5518

5619
## 1. Only use this for WASI platforms, and only if Dispatch cannot be imported.
5720

@@ -133,6 +96,40 @@ DispatchQueue.main.async {
13396
}
13497
```
13598

99+
# Toolchain Adoption Plans
100+
101+
DispatchAsync is not meant for consumption abroad directly as a new Swift Module. Rather, the intention is to provide eventual integration
102+
as a drop-in replacement for Dispatch when compiling to Wasm.
103+
104+
There are a few paths to adoption into the Swift toolchain
105+
106+
- DispatchAsync can be emplaced inside the [libDispatch repository](https://github.com/swiftlang/swift-corelibs-libdispatch), and compiled
107+
into the toolchain only for wasm targets.
108+
- DispatchAsync can be consumed in place of libDispatch when building the Swift toolchain.
109+
110+
Ideally, with either approach, this repository would transfer ownership to the swiftlang organization.
111+
112+
In the interim, to move wasm support forward, portions of DispatchAsync may be inlined (copy-pasted)
113+
into various libraries to enable wasm support. DispatchAsync is designed for this purpose, and has
114+
special `#if` handling to ensure that existing temporary usages will be elided without breakage
115+
the moment SwiftWasm adds support for `Dispatch` into the toolchain.
116+
117+
# DispatchSemaphore Limitations
118+
119+
The current implementation of `DispatchSemaphore` has some limitations. Blocking threads goes against the design goals of Swift Concurrency.
120+
The `wait` function on `DispatchSemaphore` goes against this goal. Furthermore, most wasm targets run on a single thread from the web
121+
browser, so any time the `wait` function ends up blocking the calling thread, it would almost certainly freeze the single-threaded wasm
122+
executable.
123+
124+
To navigate these issues, there are some limitations:
125+
126+
- For wasm compilation targets, `DispatchSemaphore` assumes single-threaded execution, and lacks various safeguards that would otherwise
127+
be needed for multi-threaded execution. This makes the implementation much easier.
128+
- For wasm targets, calls to `signal` and `wait` must be balanced. An assertion triggers if `wait` is called more times than `signal`.
129+
- DispatchSemaphore is deprecated for wasm targets, and AsyncSemaphore is encouraged as the replacement.
130+
- For non-wasm targets, DispatchSemaphore is simply a typealias for `AsyncSemaphore`, and provides only a non-blocking async `wait`
131+
function. This reduces potential issues that can arise from wait being a thread-blocking function.
132+
136133
# LICENSE
137134

138135
This project is distributed by PassiveLogic under the Apache-2.0 license. See

‎Sources/DispatchAsync/DispatchAsync.swift‎

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -18,8 +18,6 @@
1818
///
1919
/// Platforms other than WASI shouldn't consume this library for now
2020
/// except for testing and development purposes.
21-
///
22-
/// TODO: SM: Add github permalink to this, after it is merged.
2321
#if !os(WASI)
2422
@_spi(DispatchAsync)
2523
#endif

0 commit comments

Comments
 (0)