feat: Initial implementation of many GCD API's using Swift Concurrency

.github/workflows/pull_request.yml

@@ -0,0 +1,43 @@
+name: Pull request
+
+on:
+  pull_request:
+    types: [opened, reopened, synchronize]
+
+jobs:
+  soundness:
+    name: Soundness
+    uses: swiftlang/github-workflows/.github/workflows/soundness.yml@main
+    with:
+      format_check_container_image: swift:6.1.0-noble
+      license_header_check_enabled: false
+      api_breakage_check_enabled: false
+
+  tests:
+    name: tests
+    uses: swiftlang/github-workflows/.github/workflows/swift_package_test.yml@main
+    with:
+      enable_macos_checks: false
+      linux_exclude_swift_versions: "[{\"swift_version\": \"5.9\"}, {\"swift_version\": \"5.10\"}, {\"swift_version\": \"5.10.1\"}, {\"swift_version\": \"6.0\"}]"
+      enable_windows_checks: false
+
+  wasm-sdk:
+    name: WebAssembly SDK
+    runs-on: ubuntu-latest
+    container:
+      image: "swift:6.1.0-noble"
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+      - name: Swift version
+        run: swift --version
+      - name: WasmBuild
+        # TODO: Update this to use swift-nio once https://github.com/apple/swift-nio/pull/3159/ is merged
+        run: |
+          apt-get update -y -q
+          apt-get install -y -q curl
+          apt-get install -y -q jq
+          version="$(swift --version | head -n1)"
+          tag="$(curl -sL "https://raw.githubusercontent.com/swiftwasm/swift-sdk-index/refs/heads/main/v1/tag-by-version.json" | jq -e -r --arg v "$version" '.[$v] | .[-1]')"
+          curl -sL "https://raw.githubusercontent.com/swiftwasm/swift-sdk-index/refs/heads/main/v1/builds/$tag.json" | jq -r '.["swift-sdks"]["wasm32-unknown-wasi"] | "swift sdk install \"\(.url)\" --checksum \"\(.checksum)\""' | sh -x
+          swift build --swift-sdk wasm32-unknown-wasi

.gitignore

@@ -1,62 +1,8 @@
-# Xcode
-#
-# gitignore contributors: remember to update Global/Xcode.gitignore, Objective-C.gitignore & Swift.gitignore
-
-## User settings
+.DS_Store
+/.build
+/Packages
 xcuserdata/
-
-## Obj-C/Swift specific
-*.hmap
-
-## App packaging
-*.ipa
-*.dSYM.zip
-*.dSYM
-
-## Playgrounds
-timeline.xctimeline
-playground.xcworkspace
-
-# Swift Package Manager
-#
-# Add this line if you want to avoid checking in source code from Swift Package Manager dependencies.
-# Packages/
-# Package.pins
-# Package.resolved
-# *.xcodeproj
-#
-# Xcode automatically generates this directory with a .xcworkspacedata file and xcuserdata
-# hence it is not needed unless you have added a package configuration file to your project
-# .swiftpm
-
-.build/
-
-# CocoaPods
-#
-# We recommend against adding the Pods directory to your .gitignore. However
-# you should judge for yourself, the pros and cons are mentioned at:
-# https://guides.cocoapods.org/using/using-cocoapods.html#should-i-check-the-pods-directory-into-source-control
-#
-# Pods/
-#
-# Add this line if you want to avoid checking in source code from the Xcode workspace
-# *.xcworkspace
-
-# Carthage
-#
-# Add this line if you want to avoid checking in source code from Carthage dependencies.
-# Carthage/Checkouts
-
-Carthage/Build/
-
-# fastlane
-#
-# It is recommended to not store the screenshots in the git repo.
-# Instead, use fastlane to re-generate the screenshots whenever they are needed.
-# For more information about the recommended setup visit:
-# https://docs.fastlane.tools/best-practices/source-control/#source-control
-
-fastlane/report.xml
-fastlane/Preview.html
-fastlane/screenshots/**/*.png
-fastlane/test_output
+DerivedData/
+.swiftpm/configuration/registries.json
+.swiftpm/xcode/package.xcworkspace/contents.xcworkspacedata
+.netrc

.licenseignore

@@ -0,0 +1 @@
+Package.swift

.swift-format

@@ -0,0 +1,79 @@
+{
+  "fileScopedDeclarationPrivacy" : {
+    "accessLevel" : "private"
+  },
+  "indentConditionalCompilationBlocks" : false,
+  "indentSwitchCaseLabels" : false,
+  "indentation" : {
+    "spaces" : 4
+  },
+  "lineBreakAroundMultilineExpressionChainComponents" : false,
+  "lineBreakBeforeControlFlowKeywords" : false,
+  "lineBreakBeforeEachArgument" : false,
+  "lineBreakBeforeEachGenericRequirement" : false,
+  "lineBreakBetweenDeclarationAttributes" : false,
+  "lineLength" : 140,
+  "maximumBlankLines" : 1,
+  "multiElementCollectionTrailingCommas" : true,
+  "noAssignmentInExpressions" : {
+    "allowedFunctions" : [
+      "XCTAssertNoThrow"
+    ]
+  },
+  "prioritizeKeepingFunctionOutputTogether" : false,
+  "reflowMultilineStringLiterals" : {
+    "never" : {
+
+    }
+  },
+  "respectsExistingLineBreaks" : true,
+  "rules" : {
+    "AllPublicDeclarationsHaveDocumentation" : false,
+    "AlwaysUseLiteralForEmptyCollectionInit" : false,
+    "AlwaysUseLowerCamelCase" : true,
+    "AmbiguousTrailingClosureOverload" : true,
+    "AvoidRetroactiveConformances" : true,
+    "BeginDocumentationCommentWithOneLineSummary" : false,
+    "DoNotUseSemicolons" : true,
+    "DontRepeatTypeInStaticProperties" : true,
+    "FileScopedDeclarationPrivacy" : true,
+    "FullyIndirectEnum" : true,
+    "GroupNumericLiterals" : true,
+    "IdentifiersMustBeASCII" : true,
+    "NeverForceUnwrap" : false,
+    "NeverUseForceTry" : false,
+    "NeverUseImplicitlyUnwrappedOptionals" : false,
+    "NoAccessLevelOnExtensionDeclaration" : true,
+    "NoAssignmentInExpressions" : true,
+    "NoBlockComments" : true,
+    "NoCasesWithOnlyFallthrough" : true,
+    "NoEmptyLinesOpeningClosingBraces" : false,
+    "NoEmptyTrailingClosureParentheses" : true,
+    "NoLabelsInCasePatterns" : true,
+    "NoLeadingUnderscores" : false,
+    "NoParensAroundConditions" : true,
+    "NoPlaygroundLiterals" : true,
+    "NoVoidReturnOnFunctionSignature" : true,
+    "OmitExplicitReturns" : false,
+    "OneCasePerLine" : true,
+    "OneVariableDeclarationPerLine" : true,
+    "OnlyOneTrailingClosureArgument" : true,
+    "OrderedImports" : true,
+    "ReplaceForEachWithForLoop" : true,
+    "ReturnVoidInsteadOfEmptyTuple" : true,
+    "TypeNamesShouldBeCapitalized" : true,
+    "UseEarlyExits" : false,
+    "UseExplicitNilCheckInConditions" : true,
+    "UseLetInEveryBoundCaseVariable" : true,
+    "UseShorthandTypeNames" : true,
+    "UseSingleLinePropertyGetter" : true,
+    "UseSynthesizedInitializer" : true,
+    "UseTripleSlashForDocumentationComments" : true,
+    "UseWhereClausesInForLoops" : false,
+    "ValidateDocumentationComments" : false
+  },
+  "spacesAroundRangeFormationOperators" : true,
+  "spacesBeforeEndOfLineComments" : 1,
+  "tabWidth" : 8,
+  "version" : 1
+}

Package.swift

@@ -0,0 +1,22 @@
+// swift-tools-version: 6.0
+
+import PackageDescription
+
+let package = Package(
+    name: "swift-dispatch-async",
+    products: [
+        .library(
+            name: "DispatchAsync",
+            targets: ["DispatchAsync"]
+        )
+    ],
+    targets: [
+        .target(name: "DispatchAsync"),
+        .testTarget(
+            name: "DispatchAsyncTests",
+            dependencies: [
+                "DispatchAsync"
+            ]
+        ),
+    ]
+)

README.md

@@ -1 +1,141 @@
-# dispatch-async
+# swift-dispatch-async
+
+## ⚠️ WARNING - This is an 🧪experimental🧪 repository and should not be adopted at large.
+
+DispatchAsync is a temporary experimental repository aimed at implementing missing Dispatch support in the SwiftWasm toolchain.
+Currently, [SwiftWasm doesn't include Dispatch](https://book.swiftwasm.org/getting-started/porting.html#swift-foundation-and-dispatch). 
+But, SwiftWasm does support Swift Concurrency. DispatchAsync implements a number of common Dispatch API's using Swift Concurrency
+under the hood.
+
+Dispatch Async does not provide blocking API's such as `DispatchQueue.sync`, primarily due to the intentional lack of blocking
+API's in Swift Concurrency.
+
+# Toolchain Adoption Plans
+
+DispatchAsync is not meant for consumption abroad directly as a new Swift Module. Rather, the intention is to provide eventual integration
+as a drop-in replacement for Dispatch when compiling to Wasm.
+
+There are a few paths to adoption into the Swift toolchain
+
+- DispatchAsync can be emplaced inside the [libDispatch repository](https://github.com/swiftlang/swift-corelibs-libdispatch), and compiled
+into the toolchain only for wasm targets.
+- DispatchAsync can be consumed in place of libDispatch when building the Swift toolchain.
+
+Ideally, with either approach, this repository would transfer ownership to the swiftlang organization.
+
+In the interim, to move wasm support forward, portions of DispatchAsync may be inlined (copy-pasted)
+into various libraries to enable wasm support. DispatchAsync is designed for this purpose, and has
+special `#if` handling to ensure that existing temporary usages will be elided without breakage
+the moment SwiftWasm adds support for `Dispatch` into the toolchain.
+
+# DispatchSemaphore Limitations
+
+The current implementation of `DispatchSemaphore` has some limitations. Blocking threads goes against the design goals of Swift Concurrency.
+The `wait` function on `DispatchSemaphore` goes against this goal. Furthermore, most wasm targets run on a single thread from the web
+browser, so any time the `wait` function ends up blocking the calling thread, it would almost certainly freeze the single-threaded wasm
+executable.
+
+To navigate these issues, there are some limitations:
+
+- For wasm compilation targets, `DispatchSemaphore` assumes single-threaded execution, and lacks various safeguards that would otherwise
+be needed for multi-threaded execution. This makes the implementation much easier.
+- For wasm targets, calls to `signal` and `wait` must be balanced. An assertion triggers if `wait` is called more times than `signal`.
+- DispatchSemaphore is deprecated for wasm targets, and AsyncSemaphore is encouraged as the replacement.
+- For non-wasm targets, DispatchSemaphore is simply a typealias for `AsyncSemaphore`, and provides only a non-blocking async `wait` 
+function. This reduces potential issues that can arise from wait being a thread-blocking function.
+
+# Usage
+
+If you've scrolled this far, you probably saw the warning. But just to make sure…
+
+> ⚠️ WARNING - This is an 🧪experimental🧪 repository and should not be adopted at large.
+
+PassiveLogic is [actively working](https://github.com/PassiveLogic/swift-web-examples/issues/1) to mainstream this into the SwiftWasm
+toolchain. But if you can't wait, here are some tips.
+
+## 1. Only use this for WASI platforms, and only if Dispatch cannot be imported.
+
+Use `#if os(WASI) && !canImport(Dispatch)` to elide usages outside of WASI platforms:
+
+```swift
+#if os(WASI) && !canImport(Dispatch)
+import DispatchAsync
+#else
+import Dispatch
+#endif
+
+// Use Dispatch API's the same way you normal would.
+```
+
+## 2. If you really want to use DispatchAsync as a pure Swift Dispatch alternative for non-wasm targets
+
+Stop. Are you sure? If you do this, you'll need to be '
+
+1. Add the dependency to your package:
+
+```swift
+let package = Package(
+    name: "MyPackage",
+    products: [
+        // Products define the executables and libraries a package produces, making them visible to other packages.
+        .library(
+            name: "MyPackage",
+            targets: [
+                "MyPackage"
+            ]
+        ),
+    ],
+    dependencies: [
+        .package(
+            url: "https://github.com/PassiveLogic/swift-dispatch-async.git",
+            from: "0.0.1"
+        ),
+    ],
+    targets: [
+        .target(
+            name: "MyPackage"
+            dependencies: [
+                "DispatchAsync"
+            ]
+        ),
+    ]
+)
+```
+
+2. Import and use DispatchAsync in place of Dispatch like this:
+
+```swift
+#if os(WASI) && !canImport(Dispatch)
+import DispatchAsync
+#else
+// Non-WASI platforms have to explicitly bring in DispatchAsync
+// by using `@_spi`.
+@_spi(DispatchAsync) import DispatchAsync
+#endif
+
+// Not allowed, brings in Dispatch, aka "the real GCD":
+// import Dispatch
+
+// Also not allowed, brings in Dispatch
+// import Foundation
+
+// You'll need to use scoped Foundation imports:
+import struct Foundation.URL // Ok. Doesn't bring in Dispatch
+
+// If you ignore the above notes, but do the following, be prepared for namespace
+// collisions between the toolchain's Dispatch and DispatchAsync:
+
+private typealias DispatchQueue = DispatchAsync.DispatchQueue // Ok as long as Dispatch isn't imported
+
+// Ok. If you followed everything above, you can now do the following, using pure Swift
+// under the hood! 🎉
+DispatchQueue.main.async {
+    // Run your code here…
+}
+```
+
+# LICENSE
+
+This project is distributed by PassiveLogic under the Apache-2.0 license. See
+[LICENSE](https://github.com/PassiveLogic/swift-dispatch-async/blob/main/LICENSE) for full terms of use.
+