From 0b9bd4166539cd07dadd07cf43ce5ace992764da Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mateusz=20Stompo=CC=81r?= Date: Sat, 27 Dec 2025 22:37:15 +0100 Subject: [PATCH 1/3] Update documentation --- .../Visitors/PNMultithreadVisitor.swift | 23 +++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/Sources/PNDependencyGraph/Visitors/PNMultithreadVisitor.swift b/Sources/PNDependencyGraph/Visitors/PNMultithreadVisitor.swift index 0d0b909..73a1f60 100644 --- a/Sources/PNDependencyGraph/Visitors/PNMultithreadVisitor.swift +++ b/Sources/PNDependencyGraph/Visitors/PNMultithreadVisitor.swift @@ -1,14 +1,37 @@ import Foundation +/// A multithreaded visitor for traversing a compiled dependency graph. +/// +/// The `PNMultithreadVisitor` class allows for concurrent traversal of a dependency graph, +/// executing node visits in parallel using an operation queue. It ensures that the first +/// node is visited synchronously while all other nodes are processed in parallel. +/// +/// Example usage: +/// ```swift +/// let visitor = PNMultithreadVisitor(graph: myGraph) +/// visitor.visit { node in +/// print("Visiting node: \(node)") +/// } +/// ``` public final class PNMultithreadVisitor { private let graph: PNCompiledGraph private let queue = OperationQueue() + + /// Initializes a new instance of `PNMultithreadVisitor` with the specified graph. + /// + /// - Parameter newGraph: The compiled dependency graph to visit. public init(graph newGraph: PNCompiledGraph) { graph = newGraph queue.qualityOfService = .userInitiated queue.maxConcurrentOperationCount = graph.nodes.count - 1 } + /// Traverses the dependency graph, visiting each node. + /// + /// The first node in the graph is visited synchronously, while all other nodes + /// are processed concurrently in an operation queue. + /// + /// - Parameter completion: A closure to be called for each visited node. public func visit(completion: @Sendable @escaping (PNNode) -> Void) { guard let first = graph.nodes.first else { return From b23189bbc24ff01ba361d508e8ee7c74040d541e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mateusz=20Stompo=CC=81r?= Date: Sat, 27 Dec 2025 22:39:12 +0100 Subject: [PATCH 2/3] Document more classes --- Sources/PNDependencyGraph/PNNode.swift | 41 +++++++++++++++++++ .../Visitors/PNSingleThreadVisitor.swift | 22 ++++++++++ 2 files changed, 63 insertions(+) diff --git a/Sources/PNDependencyGraph/PNNode.swift b/Sources/PNDependencyGraph/PNNode.swift index 321c31c..bb959cc 100644 --- a/Sources/PNDependencyGraph/PNNode.swift +++ b/Sources/PNDependencyGraph/PNNode.swift @@ -1,23 +1,64 @@ import Foundation +/// A node in a dependency graph. +/// +/// The `PNNode` class represents a single node within a dependency graph. Each node +/// has a unique identifier and can have dependencies on other nodes. +/// +/// Example usage: +/// ```swift +/// let node = PNNode(identifier: "node1") +/// let dependency = PNNode(identifier: "node2") +/// node.addDependency(node: dependency) +/// ``` public final class PNNode: @unchecked Sendable, Equatable { + /// Compares two `PNNode` instances for equality. + /// + /// Two nodes are considered equal if they are the same instance (identity comparison). + /// + /// - Parameters: + /// - lhs: The left-hand side node to compare. + /// - rhs: The right-hand side node to compare. + /// - Returns: `true` if the nodes are identical; otherwise, `false`. public static func == (lhs: PNNode, rhs: PNNode) -> Bool { lhs === rhs } + /// A unique identifier for the node. public let identifier: String + + /// The dependencies of this node. + /// + /// This property returns an array of nodes that this node depends on. + /// The dependencies are thread-safe and can be accessed from multiple threads. public var dependencies: [PNNode] { synchronization.withLock { unsafeDependencies } } + + /// The internal storage for dependencies. + /// + /// This is used internally to store the actual dependencies in a thread-safe manner. private var unsafeDependencies: [PNNode] = [] + + /// A lock used to synchronize access to dependencies. + /// + /// This ensures that the `dependencies` property can be safely accessed from multiple threads. private let synchronization = NSLock() + /// Initializes a new instance of `PNNode` with the specified identifier. + /// + /// - Parameter newIdentifier: A unique identifier for the node. init(identifier newIdentifier: String) { identifier = newIdentifier } + /// Adds a dependency to this node. + /// + /// This method adds a node to the list of dependencies for this node. + /// + /// - Parameter node: The node that this node depends on. public func addDependency(node: PNNode) { synchronization.withLock { unsafeDependencies.append(node) diff --git a/Sources/PNDependencyGraph/Visitors/PNSingleThreadVisitor.swift b/Sources/PNDependencyGraph/Visitors/PNSingleThreadVisitor.swift index 62739c1..dfb4366 100644 --- a/Sources/PNDependencyGraph/Visitors/PNSingleThreadVisitor.swift +++ b/Sources/PNDependencyGraph/Visitors/PNSingleThreadVisitor.swift @@ -1,9 +1,31 @@ public final class PNSingleThreadVisitor { + /// A single-threaded visitor for traversing a compiled dependency graph. + /// + /// The `PNSingleThreadVisitor` class allows for sequential traversal of a dependency graph, + /// executing node visits in a single thread. All nodes are processed in the order they appear + /// in the graph. + /// + /// Example usage: + /// ```swift + /// let visitor = PNSingleThreadVisitor(graph: myGraph) + /// visitor.visit { node in + /// print("Visiting node: \(node)") + /// } + /// ``` private let graph: PNCompiledGraph + + /// Initializes a new instance of `PNSingleThreadVisitor` with the specified graph. + /// + /// - Parameter graph: The compiled dependency graph to visit. public init(graph: PNCompiledGraph) { self.graph = graph } + /// Traverses the dependency graph, visiting each node in sequence. + /// + /// All nodes in the graph are visited one after another in the order they appear. + /// + /// - Parameter completion: A closure to be called for each visited node. public func visit(completion: (PNNode) -> Void) { for node in graph.nodes { completion(node) From 2269396f52a6e41ce82f42f8f906e20d2152a9da Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mateusz=20Stompo=CC=81r?= Date: Sat, 27 Dec 2025 22:40:50 +0100 Subject: [PATCH 3/3] Fix lint --- Sources/PNDependencyGraph/PNNode.swift | 6 +++--- .../PNDependencyGraph/Visitors/PNMultithreadVisitor.swift | 2 +- .../PNDependencyGraph/Visitors/PNSingleThreadVisitor.swift | 2 +- 3 files changed, 5 insertions(+), 5 deletions(-) diff --git a/Sources/PNDependencyGraph/PNNode.swift b/Sources/PNDependencyGraph/PNNode.swift index bb959cc..5e21e87 100644 --- a/Sources/PNDependencyGraph/PNNode.swift +++ b/Sources/PNDependencyGraph/PNNode.swift @@ -26,7 +26,7 @@ public final class PNNode: @unchecked Sendable, Equatable { /// A unique identifier for the node. public let identifier: String - + /// The dependencies of this node. /// /// This property returns an array of nodes that this node depends on. @@ -36,12 +36,12 @@ public final class PNNode: @unchecked Sendable, Equatable { unsafeDependencies } } - + /// The internal storage for dependencies. /// /// This is used internally to store the actual dependencies in a thread-safe manner. private var unsafeDependencies: [PNNode] = [] - + /// A lock used to synchronize access to dependencies. /// /// This ensures that the `dependencies` property can be safely accessed from multiple threads. diff --git a/Sources/PNDependencyGraph/Visitors/PNMultithreadVisitor.swift b/Sources/PNDependencyGraph/Visitors/PNMultithreadVisitor.swift index 73a1f60..8c74626 100644 --- a/Sources/PNDependencyGraph/Visitors/PNMultithreadVisitor.swift +++ b/Sources/PNDependencyGraph/Visitors/PNMultithreadVisitor.swift @@ -16,7 +16,7 @@ import Foundation public final class PNMultithreadVisitor { private let graph: PNCompiledGraph private let queue = OperationQueue() - + /// Initializes a new instance of `PNMultithreadVisitor` with the specified graph. /// /// - Parameter newGraph: The compiled dependency graph to visit. diff --git a/Sources/PNDependencyGraph/Visitors/PNSingleThreadVisitor.swift b/Sources/PNDependencyGraph/Visitors/PNSingleThreadVisitor.swift index dfb4366..1864836 100644 --- a/Sources/PNDependencyGraph/Visitors/PNSingleThreadVisitor.swift +++ b/Sources/PNDependencyGraph/Visitors/PNSingleThreadVisitor.swift @@ -13,7 +13,7 @@ public final class PNSingleThreadVisitor { /// } /// ``` private let graph: PNCompiledGraph - + /// Initializes a new instance of `PNSingleThreadVisitor` with the specified graph. /// /// - Parameter graph: The compiled dependency graph to visit.