{"id":33899974,"url":"https://github.com/coenttb/swift-memory-allocation","last_synced_at":"2026-05-06T14:34:17.551Z","repository":{"id":324877044,"uuid":"1098905631","full_name":"coenttb/swift-memory-allocation","owner":"coenttb","description":"A Swift library for memory allocation observability.","archived":false,"fork":false,"pushed_at":"2025-11-18T11:11:43.000Z","size":39,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-11-18T11:26:28.626Z","etag":null,"topics":["allocation","cross-platform","leak-detection","linux","macos","memory","observability","performance","profiling","server-side-swift","swift","testing"],"latest_commit_sha":null,"homepage":"https://coenttb.com","language":"Swift","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/coenttb.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-18T09:49:50.000Z","updated_at":"2025-11-18T11:11:47.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/coenttb/swift-memory-allocation","commit_stats":null,"previous_names":["coenttb/swift-memory-allocation"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/coenttb/swift-memory-allocation","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/coenttb%2Fswift-memory-allocation","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/coenttb%2Fswift-memory-allocation/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/coenttb%2Fswift-memory-allocation/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/coenttb%2Fswift-memory-allocation/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/coenttb","download_url":"https://codeload.github.com/coenttb/swift-memory-allocation/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/coenttb%2Fswift-memory-allocation/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":27672062,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-12-11T02:00:11.302Z","response_time":56,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["allocation","cross-platform","leak-detection","linux","macos","memory","observability","performance","profiling","server-side-swift","swift","testing"],"created_at":"2025-12-11T22:51:36.703Z","updated_at":"2025-12-11T22:51:37.467Z","avatar_url":"https://github.com/coenttb.png","language":"Swift","funding_links":[],"categories":[],"sub_categories":[],"readme":"# swift-memory-allocation\n\n[![CI](https://github.com/coenttb/swift-memory-allocation/workflows/CI/badge.svg)](https://github.com/coenttb/swift-memory-allocation/actions/workflows/ci.yml)\n![Development Status](https://img.shields.io/badge/status-active--development-blue.svg)\n\n**Cross-platform memory allocation observability for Swift**\n\nA focused library providing memory allocation tracking, leak detection, peak memory profiling, and allocation histograms across macOS and Linux.\n\n## Features\n\n- **Allocation Tracking** - Measure memory allocations in code blocks\n- **Leak Detection** - Detect memory leaks by tracking net allocations\n- **Peak Memory Tracking** - Monitor peak memory usage over time\n- **Allocation Profiling** - Profile allocations with statistics and histograms\n- **Cross-Platform** - Works on macOS and Linux with platform-optimized implementations\n- **Thread-Safe** - All trackers are Sendable and safe for concurrent use\n- **Zero Dependencies** - Pure Swift using only Darwin/Glibc platform primitives (no Foundation)\n\n## Installation\n\nAdd `swift-memory-allocation` to your `Package.swift`:\n\n```swift\ndependencies: [\n    .package(url: \"https://github.com/coenttb/swift-memory-allocation\", from: \"0.1.0\")\n]\n```\n\nThen add it to your target:\n\n```swift\n.target(\n    name: \"YourTarget\",\n    dependencies: [\n        .product(name: \"MemoryAllocation\", package: \"swift-memory-allocation\")\n    ]\n)\n```\n\n## Quick Start\n\n### Basic Allocation Tracking\n\n```swift\nimport MemoryAllocation\n\n// Measure allocations in a code block\nlet (result, stats) = AllocationTracker.measure {\n    let array = Array(repeating: 0, count: 1000)\n    return array.count\n}\n\nprint(\"Allocated \\(stats.bytesAllocated) bytes\")\nprint(\"Allocations: \\(stats.allocations)\")\nprint(\"Deallocations: \\(stats.deallocations)\")\n```\n\n### Leak Detection\n\n```swift\nlet detector = LeakDetector()\n\n// Your code here\nvar leaked: [[Int]] = []\nfor i in 0..\u003c100 {\n    leaked.append(Array(repeating: i, count: 100))\n}\n\nif detector.hasLeaks() {\n    print(\"Warning: \\(detector.netAllocations) leaked allocations\")\n    print(\"Net bytes: \\(detector.netBytes)\")\n}\n\n// Or assert no leaks\ntry detector.assertNoLeaks()  // Throws if leaks detected\n```\n\n### Peak Memory Tracking\n\n```swift\nlet tracker = PeakMemoryTracker()\n\nfor i in 0..\u003c100 {\n    let array = Array(repeating: 0, count: i * 100)\n    tracker.sample()  // Record current memory\n}\n\nprint(\"Peak memory: \\(tracker.peakBytes) bytes\")\nprint(\"Peak allocations: \\(tracker.peakAllocations)\")\n```\n\n### Allocation Profiling\n\n```swift\nlet profiler = AllocationProfiler()\n\n// Profile multiple runs\nfor _ in 0..\u003c100 {\n    profiler.profile {\n        let array = Array(repeating: 0, count: 1000)\n        _ = array.reduce(0, +)\n    }\n}\n\n// Analyze results\nprint(\"Mean: \\(profiler.meanBytes) bytes\")\nprint(\"Median: \\(profiler.medianBytes) bytes\")\nprint(\"P95: \\(profiler.percentileBytes(95)) bytes\")\nprint(\"P99: \\(profiler.percentileBytes(99)) bytes\")\n\n// Generate histogram\nlet histogram = profiler.histogram(buckets: 10)\nfor bucket in histogram.buckets {\n    print(\"\\(bucket.lowerBound)-\\(bucket.upperBound): \\(bucket.count) (\\(bucket.frequency)%)\")\n}\n```\n\n## Platform Differences\n\n### macOS/iOS/watchOS/tvOS\n\nUses `malloc_zone_statistics` which provides:\n- Current memory snapshot\n- Blocks in use\n- Total bytes in use\n\n**Note**: On Darwin platforms, allocation deltas represent snapshots and can be negative due to background cleanup. This is expected behavior.\n\n### Linux\n\nUses LD_PRELOAD malloc/free hooks which provide:\n- Accurate allocation counting\n- Deallocation tracking\n- Per-thread statistics\n\n**Note**: On Linux, you need to start tracking explicitly:\n\n```swift\n#if os(Linux)\nAllocationStats.startTracking()\n#endif\n```\n\n## API Overview\n\n### `AllocationStats`\n\nCore type representing allocation statistics.\n\n```swift\npublic struct AllocationStats: Sendable, Equatable {\n    public let allocations: Int\n    public let deallocations: Int\n    public let bytesAllocated: Int\n\n    public var netAllocations: Int { allocations - deallocations }\n\n    public static func capture() -\u003e AllocationStats\n    public static func delta(from start: AllocationStats, to end: AllocationStats) -\u003e AllocationStats\n}\n```\n\n### `AllocationTracker`\n\nMeasure allocations in code blocks.\n\n```swift\npublic enum AllocationTracker {\n    public static func measure\u003cT\u003e(_ operation: () throws -\u003e T) rethrows -\u003e (result: T, stats: AllocationStats)\n    public static func measure\u003cT\u003e(_ operation: () async throws -\u003e T) async rethrows -\u003e (result: T, stats: AllocationStats)\n    public static func measure(_ operation: () throws -\u003e Void) rethrows -\u003e AllocationStats\n    public static func measure(_ operation: () async throws -\u003e Void) async rethrows -\u003e AllocationStats\n}\n```\n\n### `LeakDetector`\n\nDetect memory leaks by tracking net allocations.\n\n```swift\npublic final class LeakDetector: Sendable {\n    public init()\n\n    public func hasLeaks() -\u003e Bool\n    public var netAllocations: Int { get }\n    public var netBytes: Int { get }\n    public func delta() -\u003e AllocationStats\n    public func assertNoLeaks(file: StaticString = #file, line: UInt = #line) throws\n}\n```\n\n### `PeakMemoryTracker`\n\nTrack peak memory usage.\n\n```swift\npublic final class PeakMemoryTracker: Sendable {\n    public init()\n\n    public func sample()\n    public var peakBytes: Int { get }\n    public var peakAllocations: Int { get }\n    public var samples: [AllocationStats] { get }\n    public var current: AllocationStats { get }\n    public func reset()\n\n    public static func track\u003cT\u003e(_ operation: (PeakMemoryTracker) throws -\u003e T) rethrows -\u003e (result: T, peak: AllocationStats)\n    public static func track\u003cT\u003e(_ operation: (PeakMemoryTracker) async throws -\u003e T) async rethrows -\u003e (result: T, peak: AllocationStats)\n}\n```\n\n### `AllocationProfiler`\n\nProfile allocations with statistics and histograms.\n\n```swift\npublic final class AllocationProfiler: Sendable {\n    public init()\n\n    public func profile\u003cT\u003e(_ operation: () throws -\u003e T) rethrows -\u003e T\n    public func profile\u003cT\u003e(_ operation: () async throws -\u003e T) async rethrows -\u003e T\n\n    public var count: Int { get }\n    public var allMeasurements: [AllocationStats] { get }\n\n    public var meanBytes: Double { get }\n    public var medianBytes: Int { get }\n    public func percentileBytes(_ percentile: Int) -\u003e Int\n\n    public var meanAllocations: Double { get }\n    public var medianAllocations: Int { get }\n    public func percentileAllocations(_ percentile: Int) -\u003e Int\n\n    public func histogram(buckets: Int = 10) -\u003e AllocationHistogram\n    public func reset()\n}\n```\n\n## Use Cases\n\n### 1. Performance Testing\n\nTrack memory allocations in your test suite:\n\n```swift\nfunc testMemoryEfficiency() throws {\n    let stats = AllocationTracker.measure {\n        myExpensiveOperation()\n    }\n\n    // Assert maximum allocation budget\n    #expect(stats.bytesAllocated \u003c= 1024 * 1024)  // Max 1MB\n}\n```\n\n### 2. CI/CD Regression Detection\n\nProfile allocations across builds:\n\n```swift\nlet profiler = AllocationProfiler()\n\nfor _ in 0..\u003c1000 {\n    profiler.profile {\n        criticalPath()\n    }\n}\n\n// Compare with baseline\nlet p95 = profiler.percentileBytes(95)\n#expect(p95 \u003c= baselineP95)\n```\n\n### 3. Production Monitoring\n\nDetect leaks in long-running services:\n\n```swift\nlet detector = LeakDetector()\n\nwhile running {\n    handleRequest()\n\n    if detector.netAllocations \u003e threshold {\n        logger.warning(\"Potential leak: \\(detector.netBytes) bytes\")\n    }\n}\n```\n\n### 4. Memory Profiling\n\nUnderstand allocation patterns:\n\n```swift\nlet tracker = PeakMemoryTracker()\n\nfor batch in batches {\n    processBatch(batch)\n    tracker.sample()\n}\n\nprint(\"Peak during processing: \\(tracker.peakBytes) bytes\")\n```\n\n## Requirements\n\n- Swift 6.2+\n- macOS 13+, iOS 16+, watchOS 9+, tvOS 16+, or Linux\n\n## License\n\nThis library is released under the Apache License 2.0. See [LICENSE](LICENSE) for details.\n\n## Related Projects\n\n- [swift-testing-performance](https://github.com/coenttb/swift-testing-performance) - Performance measurement traits for Swift Testing\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcoenttb%2Fswift-memory-allocation","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcoenttb%2Fswift-memory-allocation","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcoenttb%2Fswift-memory-allocation/lists"}