Merge pull request #52 from orchetect/2.0.0

OSCKit 2.0.0

Author: orchetect

.github/workflows/build.yml

@@ -40,22 +40,7 @@ jobs:
       run: xcodebuild build -workspace ".swiftpm/xcode/package.xcworkspace" -scheme "$SCHEME" -destination "generic/platform=macOS" | xcbeautify --renderer github-actions && exit ${PIPESTATUS[0]}
     - name: Unit Tests
       run: xcodebuild test -workspace ".swiftpm/xcode/package.xcworkspace" -scheme "$SCHEME" -destination "platform=macOS" | xcbeautify --renderer github-actions && exit ${PIPESTATUS[0]}
-
-  macOS-swift6:
-    name: macOS (Swift 6.0)
-    runs-on: macos-latest
-    steps:
-    - uses: actions/checkout@main
-    - uses: maxim-lobanov/setup-xcode@v1
-      with:
-        xcode-version: latest-stable
-    - name: Set Package to Swift 6.0
-      run: swift package tools-version --set "6.0"
-    - name: Build
-      run: xcodebuild build -workspace ".swiftpm/xcode/package.xcworkspace" -scheme "$SCHEME" -destination "generic/platform=macOS" | xcbeautify --renderer github-actions && exit ${PIPESTATUS[0]}
-    - name: Unit Tests
-      run: xcodebuild test -workspace ".swiftpm/xcode/package.xcworkspace" -scheme "$SCHEME" -destination "platform=macOS" | xcbeautify --renderer github-actions && exit ${PIPESTATUS[0]}
-      
+  
   macCatalyst:
     name: macCatalyst
     runs-on: macos-latest

Examples/Custom Type/Custom OSC Type/CustomType.swift

@@ -9,7 +9,7 @@ import OSCKitCore
 
 // NOTE:
 // In this basic example, we've chosen to use the underlying OSC Type "blob", which is essentially raw data, as our
-// underlying data storage chunk within an OSC message, since our object conforms to Codable and it's easily converted
+// underlying data storage chunk within an OSC message, since our type conforms to Codable and it's easily converted
 // to/from Data.
 //
 // Since we've chosen to use JSONEncoder, and JSON is technically text (string) block, we could have also chosen
@@ -33,16 +33,18 @@ extension CustomType: OSCValueCodable {
     // uses an OSC Type Tag that already exists.
     // For a reference of existing OSC Type Tags, see the OSC 1.0 spec online.
     static let oscTag: Character = "j"
-    // atomic indicates that the tag is static and will never change based on its data content
-    static let oscTagIdentity: OSCValueTagIdentity = .atomic(oscTag)
+    
+    // establishes that the tag is static and will never change based on its data payload
+    static let oscTagIdentity: OSCValueTagIdentity = .tag(oscTag)
 }
 
 extension CustomType: OSCValueEncodable {
-    public typealias OSCValueEncodingBlock = OSCValueAtomicEncoder<OSCEncoded>
-    static let oscEncoding = OSCValueEncodingBlock { value in
+    static let oscEncoding = OSCValueStaticTagEncoder<Self> { value throws(OSCEncodeError) in
         // Encode our Codable type instance into raw data
         let encoder = JSONEncoder()
-        let jsonData = try encoder.encode(value)
+        let jsonData: Data
+        do { jsonData = try encoder.encode(value) }
+        catch { throw .valueEncodingError(error.localizedDescription) }
 
         // OSCValueEncodingBlock makes it our responsibility to make sure OSB blob (data) is encoded correctly,
         // including a 4-byte big-endian Int32 length header and trailing null-byte padding to an alignment of 4 bytes.
@@ -53,16 +55,17 @@ extension CustomType: OSCValueEncodable {
 }
 
 extension CustomType: OSCValueDecodable {
-    public typealias OSCValueDecodingBlock = OSCValueAtomicDecoder<OSCDecoded>
-    static let oscDecoding = OSCValueDecodingBlock { dataReader in
+    static let oscDecoding = OSCValueStaticTagDecoder<Self> { dataReader throws(OSCDecodeError) in
         let decoder = JSONDecoder()
 
         // Gets entire data chunk from the OSC blob, stripping the length bytes and null padding suffix
         // and returning the actual data content
         let data = try dataReader.readBlob()
 
         // Decode into a new instance of our Codable type
-        let decoded = try decoder.decode(CustomType.self, from: data)
+        let decoded: CustomType
+        do { decoded = try decoder.decode(CustomType.self, from: data) }
+        catch { throw .valueDecodingError(error.localizedDescription) }
         return decoded
     }
 }

Examples/Custom Type/Custom OSC Type/OSCManager.swift

@@ -8,7 +8,7 @@ import Foundation
 import OSCKit
 
 /// OSC lifecycle and send/receive manager.
-final class OSCManager: ObservableObject, Sendable {
+@MainActor final class OSCManager: ObservableObject {
     private let client = OSCUDPClient()
     private let server = OSCUDPServer(port: 8000)
 
@@ -29,13 +29,15 @@ extension OSCManager {
     /// Call this once on app launch.
     func start() {
         // setup client
-        do { try client.start() } catch { print(error) }
+        do { try client.start() } catch { print(error.localizedDescription) }
 
         // setup server
         server.setReceiveHandler { [weak self] message, timeTag, host, port in
-            self?.handle(message: message, timeTag: timeTag, host: host, port: port)
+            Task { @MainActor in
+                self?.handle(message: message, timeTag: timeTag, host: host, port: port)
+            }
         }
-        do { try server.start() } catch { print(error) }
+        do { try server.start() } catch { print(error.localizedDescription) }
     }
 
     func stop() {
@@ -66,11 +68,11 @@ extension OSCManager {
 // MARK: - Send
 
 extension OSCManager {
-    func send(_ message: OSCMessage, to host: String, port: UInt16) {
+    func send(_ packet: OSCPacket, to host: String, port: UInt16) {
         do {
-            try client.send(message, to: host, port: port)
+            try client.send(packet, to: host, port: port)
         } catch {
-            print(error)
+            print(error.localizedDescription)
         }
     }
 }

Examples/Method Blocks/OSC Method Blocks/ContentView.swift

@@ -28,7 +28,7 @@ struct ContentView: View {
                 sendTestOSCMessageCWithOptionalValue()
             }
 
-            Button("Send Test OSC Message C With No Optional Value") {
+            Button("Send Test OSC Message C With Missing Optional Value") {
                 sendTestOSCMessageCWithNoOptionalValue()
             }
         }

Examples/Method Blocks/OSC Method Blocks/OSCManager.swift

@@ -8,7 +8,7 @@ import Foundation
 import OSCKit
 
 /// OSC lifecycle and send/receive manager.
-final class OSCManager: ObservableObject, Sendable {
+@MainActor final class OSCManager: ObservableObject {
     private let client = OSCUDPClient()
     private let server = OSCUDPServer(port: 8000)
     private let receiver = OSCReceiver()
@@ -24,17 +24,15 @@ extension OSCManager {
     /// Call once at app startup.
     func start() {
         // setup client
-        do { try client.start() } catch { print(error) }
+        do { try client.start() } catch { print(error.localizedDescription) }
 
         // setup server
         server.setReceiveHandler { [weak self] message, timeTag, host, port in
-            do {
-                try self?.receiver.handle(message: message, timeTag: timeTag, host: host, port: port)
-            } catch {
-                print(error)
+            Task {
+                await self?.receiver.handle(message: message, timeTag: timeTag, host: host, port: port)
             }
         }
-        do { try server.start() } catch { print(error) }
+        do { try server.start() } catch { print(error.localizedDescription) }
     }
 
     func stop() {
@@ -54,7 +52,7 @@ extension OSCManager {
         do {
             try client.send(message, to: host, port: port)
         } catch {
-            print(error)
+            print(error.localizedDescription)
         }
     }
 }

Examples/Method Blocks/OSC Method Blocks/OSCReceiver.swift

@@ -14,30 +14,34 @@ final class OSCReceiver: Sendable {
     private let addressSpace = OSCAddressSpace()
 
     public init() {
-        // Register local OSC method and supply a closure block
-        addressSpace.register(localAddress: "/methodA") { values, host, port in
+        Task { await setup() }
+    }
+    
+    private func setup() async {
+        // A) Register local OSC method and supply a closure block
+        await addressSpace.register(localAddress: "/methodA") { values, host, port in
             guard let str = try? values.masked(String.self) else { return }
             print("Received methodA from \(host) port \(port) with value: \"\(str)\"")
         }
 
-        // Register local OSC method and supply a closure block
-        addressSpace.register(localAddress: "/some/address/methodB") { values, host, port in
+        // B) Register local OSC method and supply a closure block
+        await addressSpace.register(localAddress: "/some/address/methodB") { values, host, port in
             guard let (str, int) = try? values.masked(String.self, Int.self) else { return }
             print("Received methodB from \(host) port \(port) with values: [\"\(str)\", \(int)]")
         }
 
         // Instead of supplying a closure, it's also possible to forward to a function:
 
-        // Option 1: weak reference (recommended):
-        addressSpace.register(
+        // C) Option 1: weak reference (recommended):
+        await addressSpace.register(
             localAddress: "/some/address/methodC",
             block: { [weak self] values, host, port in
                 self?.handleMethodC(values: values, host: host, port: port)
             }
         )
 
-        // Option 2: strong reference (discouraged):
-        // addressSpace.register(
+        // C) Option 2: strong reference (discouraged):
+        // await addressSpace.register(
         //     localAddress: "/some/address/methodC",
         //     block: handleMethodC
         // )
@@ -48,9 +52,9 @@ final class OSCReceiver: Sendable {
         print("Received methodC from \(host) port \(port) with values: [\"\(str)\", \(dbl as Any)]")
     }
 
-    public func handle(message: OSCMessage, timeTag: OSCTimeTag, host: String, port: UInt16) throws {
+    public func handle(message: OSCMessage, timeTag: OSCTimeTag, host: String, port: UInt16) async {
         // Execute closures for matching methods, and returns the matching method IDs
-        let methodIDs = addressSpace.dispatch(message: message, host: host, port: port)
+        let methodIDs = await addressSpace.dispatch(message: message, host: host, port: port)
 
         // If no IDs are returned, it means that the OSC message address pattern did not match any
         // that were registered

Examples/Method IDs/OSC Method IDs/ContentView.swift

@@ -28,7 +28,7 @@ struct ContentView: View {
                 sendTestOSCMessageCWithOptionalValue()
             }
 
-            Button("Send Test OSC Message C With No Optional Value") {
+            Button("Send Test OSC Message C With Missing Optional Value") {
                 sendTestOSCMessageCWithNoOptionalValue()
             }
         }

Examples/Method IDs/OSC Method IDs/OSCManager.swift

@@ -8,33 +8,37 @@ import Foundation
 import OSCKit
 
 /// OSC lifecycle and send/receive manager.
-final class OSCManager: ObservableObject, Sendable {
+@MainActor final class OSCManager: ObservableObject {
     private let client = OSCUDPClient()
     private let server = OSCUDPServer(port: 8000)
-    private let receiver = OSCReceiver()
+    private var receiver: OSCReceiver?
 
     init() {
-        start()
+        Task { await start() }
     }
 }
 
 // MARK: - Lifecycle
 
 extension OSCManager {
     /// Call once at app startup.
-    func start() {
+    func start() async {
         // setup client
-        do { try client.start() } catch { print(error) }
+        do { try client.start() } catch { print(error.localizedDescription) }
+        
+        receiver = await OSCReceiver()
 
         // setup server
         server.setReceiveHandler { [weak self] message, timeTag, host, port in
-            do {
-                try self?.receiver.handle(message: message, timeTag: timeTag, host: host, port: port)
-            } catch {
-                print(error)
+            Task {
+                do {
+                    try await self?.receiver?.handle(message: message, timeTag: timeTag, host: host, port: port)
+                } catch {
+                    print(error.localizedDescription)
+                }
             }
         }
-        do { try server.start() } catch { print(error) }
+        do { try server.start() } catch { print(error.localizedDescription) }
     }
 
     func stop() {
@@ -50,7 +54,7 @@ extension OSCManager {
         do {
             try client.send(message, to: host, port: port)
         } catch {
-            print(error)
+            print(error.localizedDescription)
         }
     }
 }

Examples/Method IDs/OSC Method IDs/OSCReceiver.swift

@@ -17,15 +17,15 @@ final class OSCReceiver: Sendable {
     private let idMethodB: OSCAddressSpace.MethodID
     private let idMethodC: OSCAddressSpace.MethodID
 
-    public init() {
+    public init() async {
         // register local OSC methods and store the ID tokens once before receiving OSC messages
-        idMethodA = addressSpace.register(localAddress: "/methodA")
-        idMethodB = addressSpace.register(localAddress: "/some/address/methodB")
-        idMethodC = addressSpace.register(localAddress: "/some/address/methodC")
+        idMethodA = await addressSpace.register(localAddress: "/methodA")
+        idMethodB = await addressSpace.register(localAddress: "/some/address/methodB")
+        idMethodC = await addressSpace.register(localAddress: "/some/address/methodC")
     }
 
-    public func handle(message: OSCMessage, timeTag: OSCTimeTag, host: String, port: UInt16) throws {
-        let ids = addressSpace.methods(matching: message.addressPattern)
+    public func handle(message: OSCMessage, timeTag: OSCTimeTag, host: String, port: UInt16) async throws {
+        let ids = await addressSpace.methods(matching: message.addressPattern)
 
         guard !ids.isEmpty else {
             // No matches against any registered local OSC addresses.

Examples/README.md

@@ -1,9 +1,11 @@
 # OSCKit Examples
 
-These example projects are provided to demonstrate using OSCKit.
+These example projects are provided to demonstrate using OSCKit on Apple platforms.
 
 They will build for all platforms including macOS, iOS, tvOS and visionOS, and can be run in device simulators.
 
 ## Build Note
 
-If Xcode builds but the app does not run, it may be because Xcode is defaulting to the wrong Scheme. Ensure the example app's Scheme is selected then try again.
+> [!TIP]
+>
+> If Xcode builds but the app does not run, it may be because Xcode is defaulting to the wrong Scheme. Ensure the example app's Scheme is selected then try again.