doc: add docC calatalog for library

.gitignore

@@ -22,6 +22,16 @@ DerivedData/
 *.perspectivev3
 !default.perspectivev3
 
+# OS generated files #
+######################
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+ehthumbs.db
+Thumbs.db
+
 ## Obj-C/Swift specific
 *.hmap
 
@@ -40,7 +50,7 @@ playground.xcworkspace
 Packages/
 Package.pins
 Package.resolved
-*.xcodeproj
+# *.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
@@ -66,6 +76,12 @@ Package.resolved
 
 Carthage/Build/
 
+# Add Xcode project related files required by Carthage
+AsyncObject.xcodeproj/*
+!AsyncObject.xcodeproj/*.pbxproj
+!AsyncObject.xcodeproj/*.plist
+!AsyncObject.xcodeproj/xcshareddata
+
 # Accio dependency management
 Dependencies/
 .accio/
@@ -88,3 +104,119 @@ fastlane/test_output
 # https://github.com/johnno1962/injectionforxcode
 
 iOSInjectionProject/
+
+# DocC
+.netrc
+.docc-build
+*.doccarchive*
+
+# Built Products
+*.xcframework*
+*.zip
+*.tar*
+
+## Node-Js ignores
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+lerna-debug.log*
+
+# Diagnostic reports (https://nodejs.org/api/report.html)
+report.[0-9]*.[0-9]*.[0-9]*.[0-9]*.json
+
+# Runtime data
+pids
+*.pid
+*.seed
+*.pid.lock
+
+# Directory for instrumented libs generated by jscoverage/JSCover
+lib-cov
+
+# Coverage directory used by tools like istanbul
+coverage
+*.lcov
+
+# nyc test coverage
+.nyc_output
+
+# Grunt intermediate storage (https://gruntjs.com/creating-plugins#storing-task-files)
+.grunt
+
+# Bower dependency directory (https://bower.io/)
+bower_components
+
+# node-waf configuration
+.lock-wscript
+
+# Compiled binary addons (https://nodejs.org/api/addons.html)
+build/Release
+
+# Dependency directories
+node_modules/
+jspm_packages/
+
+# TypeScript v1 declaration files
+typings/
+
+# TypeScript cache
+*.tsbuildinfo
+
+# Optional npm cache directory
+.npm
+
+# Optional eslint cache
+.eslintcache
+
+# Microbundle cache
+.rpt2_cache/
+.rts2_cache_cjs/
+.rts2_cache_es/
+.rts2_cache_umd/
+
+# Optional REPL history
+.node_repl_history
+
+# Output of 'npm pack'
+*.tgz
+
+# Yarn Integrity file
+.yarn-integrity
+
+# dotenv environment variables file
+.env
+.env.test
+
+# parcel-bundler cache (https://parceljs.org/)
+.cache
+
+# Next.js build output
+.next
+
+# Nuxt.js build / generate output
+.nuxt
+dist
+
+# Gatsby files
+.cache/
+# Comment in the public line in if your project uses Gatsby and *not* Next.js
+# https://nextjs.org/blog/next-9-1#public-directory-support
+# public
+
+# vuepress build output
+.vuepress/dist
+
+# Serverless directories
+.serverless/
+
+# FuseBox cache
+.fusebox/
+
+# DynamoDB Local files
+.dynamodb/
+
+# TernJS port file
+.tern-port

.vscode/settings.json

@@ -1,3 +1,9 @@
 {
-    "explorer.excludeGitIgnore": true,
+    "files.exclude": {
+        "**/.build": true,
+        "**/.swiftpm": true,
+        "**/.docc-build": true,
+        "**/node_modules": true,
+        "Package.resolved": true
+    }
 }

Sources/AsyncObject/AsyncObject.docc/AsyncObject.md

@@ -0,0 +1,13 @@
+# ``AsyncObject``
+
+Several synchronization primitives introduced to aid in modern swift concurrency. The primitives are very similar to those used in other operating systems including mutexes, condition variables, shared/exclusive locks, and semaphores.
+
+## Overview
+
+Several synchronization primitives introduced to aid in modern swift concurrency. The primitives are very similar to those used in other operating systems including mutexes, condition variables, shared/exclusive locks, and semaphores.
+
+## Topics
+
+### Synchronization Primitives
+
+- ``AsyncSemaphore``

Sources/AsyncObject/AsyncSemaphore.swift

@@ -1,28 +1,64 @@
 import Foundation
 import OrderedCollections
 
-actor AsyncSemaphore {
+/// An object that controls access to a resource across multiple task contexts through use of a traditional counting semaphore.
+///
+/// An async semaphore is an efficient implementation of a traditional counting semaphore.
+/// Unlike traditional semaphore, async semaphore suspends current task instead of blocking threads.
+///
+/// You increment a semaphore count by calling the ``signal()`` method
+/// and decrement a semaphore count by calling ``wait()`` method
+/// or its timeout variation ``wait(forNanoseconds:)``.
+public actor AsyncSemaphore {
+    /// The suspended tasks continuation type.
     private typealias Continuation = UnsafeContinuation<Void, Error>
+    /// The continuations stored with an associated key for all the suspended task that are waitig for access to resource.
     private var continuations: OrderedDictionary<UUID, Continuation> = [:]
+    /// Pool size for concurrent resource access.
+    /// Has value provided during initialization incremented by one.
     private var limit: UInt
+    /// Current count of semaphore.
+    /// Can have maximum value upto `limit`.
     private var count: Int
 
+    /// Add continuation with the provided key in `continuations` map.
+    ///
+    /// - Parameters:
+    ///   - continuation: The `continuation` to add.
+    ///   - key: The key in the map.
     private func addContinuation(
         _ continuation: Continuation,
         withKey key: UUID
     ) {
         continuations[key] = continuation
     }
 
+    /// Remove continuation associated with provided key
+    /// from `continuations` map.
+    ///
+    /// - Parameter key: The key in the map.
     private func removeContinuation(withKey key: UUID) {
         continuations.removeValue(forKey: key)
     }
 
+    /// Creates new counting semaphore with an initial value.
+    /// By default, initial value is zero.
+    ///
+    /// Passing zero for the value is useful for when two threads need to reconcile the completion of a particular event.
+    /// Passing a value greater than zero is useful for managing a finite pool of resources, where the pool size is equal to the value.
+    ///
+    /// - Parameter count: The starting value for the semaphore.
+    /// - Returns: The newly created semaphore.
     public init(value count: UInt = 0) {
         self.limit = count + 1
         self.count = Int(limit)
     }
 
+    /// Signals (increments) a semaphore.
+    ///
+    /// Increment the counting semaphore.
+    /// If the previous value was less than zero,
+    /// current task is resumed from suspension.
     public func signal() {
         guard count < limit else { return }
         count += 1
@@ -31,6 +67,10 @@ actor AsyncSemaphore {
         continuation.resume()
     }
 
+    /// Waits for, or decrements, a semaphore.
+    ///
+    /// Decrement the counting semaphore. If the resulting value is less than zero,
+    /// current task is suspended until a signal occurs.
     public func wait() async {
         count -= 1
         if count > 0 { return }
@@ -50,6 +90,13 @@ actor AsyncSemaphore {
         }
     }
 
+    /// Waits for within the duration, or decrements, a semaphore.
+    ///
+    /// Decrement the counting semaphore. If the resulting value is less than zero,
+    /// current task is suspended until a signal occurs or timeout duration completes.
+    ///
+    /// - Parameter duration: The duration in nano seconds to wait until.
+    /// - Returns: The result indicating whether wait completed or timed out.
     @discardableResult
     public func wait(
         forNanoseconds duration: UInt64