{"id":878,"url":"https://github.com/facebook/FBRetainCycleDetector","last_synced_at":"2025-07-30T19:32:53.422Z","repository":{"id":38206074,"uuid":"55717457","full_name":"facebook/FBRetainCycleDetector","owner":"facebook","description":"iOS library to help detecting retain cycles in runtime.","archived":false,"fork":false,"pushed_at":"2024-08-20T02:15:18.000Z","size":3053,"stargazers_count":4210,"open_issues_count":43,"forks_count":586,"subscribers_count":105,"default_branch":"main","last_synced_at":"2024-10-29T09:07:26.813Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Objective-C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/facebook.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","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}},"created_at":"2016-04-07T18:17:16.000Z","updated_at":"2024-10-28T16:47:07.000Z","dependencies_parsed_at":"2024-05-14T09:27:50.413Z","dependency_job_id":"ac1bba87-d020-46f5-a37e-700b40998ee5","html_url":"https://github.com/facebook/FBRetainCycleDetector","commit_stats":{"total_commits":92,"total_committers":37,"mean_commits":"2.4864864864864864","dds":0.7065217391304348,"last_synced_commit":"d47cba6db773b97757f85ebd7dbe1f188150b50f"},"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/facebook%2FFBRetainCycleDetector","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/facebook%2FFBRetainCycleDetector/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/facebook%2FFBRetainCycleDetector/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/facebook%2FFBRetainCycleDetector/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/facebook","download_url":"https://codeload.github.com/facebook/FBRetainCycleDetector/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":227524317,"owners_count":17783449,"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","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":[],"created_at":"2024-01-05T20:15:33.669Z","updated_at":"2024-12-04T19:32:12.125Z","avatar_url":"https://github.com/facebook.png","language":"Objective-C++","funding_links":[],"categories":["Code Quality","Objective-C++","Uncategorized","Tools","OOM-Leaks-Crash"],"sub_categories":["Uncategorized","Other free courses","Getting Started","GraphQL"],"readme":"# FBRetainCycleDetector\n[![Support Ukraine](https://img.shields.io/badge/Support-Ukraine-FFD500?style=flat\u0026labelColor=005BBB)](https://opensource.fb.com/support-ukraine)\n[![Build Status](https://travis-ci.org/facebook/FBRetainCycleDetector.svg?branch=main)](https://travis-ci.org/facebook/FBRetainCycleDetector)\n[![Carthage compatible](https://img.shields.io/badge/Carthage-compatible-4BC51D.svg?style=flat)](https://github.com/Carthage/Carthage)\n[![CocoaPods](https://img.shields.io/cocoapods/v/FBRetainCycleDetector.svg)](https://cocoapods.org/pods/FBRetainCycleDetector)\n[![License](https://img.shields.io/cocoapods/l/FBRetainCycleDetector.svg)](https://github.com/facebook/FBRetainCycledetector/blob/main/LICENSE)\n\nAn iOS library that finds retain cycles using runtime analysis.\n\n## About\nRetain cycles are one of the most common ways of creating memory leaks. It's incredibly easy to create a retain cycle, and tends to be hard to spot it.\nThe goal of FBRetainCycleDetector is to help find retain cycles at runtime.\nThe features of this project were influenced by [Circle](https://github.com/mikeash/Circle).\n\n## Installation\n\n### Carthage\n\nTo your Cartfile add:\n\n    github \"facebook/FBRetainCycleDetector\"\n\n`FBRetainCycleDetector` is built out from non-debug builds, so when you want to test it, use\n\n    carthage update --configuration Debug\n\n### CocoaPods\n\nTo your podspec add:\n\n    pod 'FBRetainCycleDetector'\n\nYou'll be able to use `FBRetainCycleDetector` fully only in `Debug` builds. This is controlled by [compilation flag](https://github.com/facebook/FBRetainCycleDetector/blob/main/FBRetainCycleDetector/Detector/FBRetainCycleDetector.h#L83) that can be provided to the build to make it work in other configurations.\n\n## Example usage\n\nLet's quickly dive in\n\n```objc\n#import \u003cFBRetainCycleDetector/FBRetainCycleDetector.h\u003e\n```\n\n```objc\nFBRetainCycleDetector *detector = [FBRetainCycleDetector new];\n[detector addCandidate:myObject];\nNSSet *retainCycles = [detector findRetainCycles];\nNSLog(@\"%@\", retainCycles);\n```\n\n`- (NSSet\u003cNSArray\u003cFBObjectiveCGraphElement *\u003e *\u003e *)findRetainCycles` will return a set of arrays of wrapped objects. It's pretty hard to look at at first, but let's go through it. Every array in this set will represent one retain cycle. Every element in this array is a wrapper around one object in this retain cycle. Check [FBObjectiveCGraphElement](https://github.com/facebook/FBRetainCycleDetector/blob/main/FBRetainCycleDetector/Graph/FBObjectiveCGraphElement.h).\n\nExample output could look like this:\n```\n{(\n    (\n        \"-\u003e MyObject \",\n        \"-\u003e _someObject -\u003e __NSArrayI \"\n    )\n)}\n```\n`MyObject` through `someObject` property retained `NSArray` that it was a part of.\n\nFBRetainCycleDetector will look for cycles that are no longer than 10 objects.\nWe can make it bigger (although it's going to be slower!).\n\n```objc\nFBRetainCycleDetector *detector = [FBRetainCycleDetector new];\n[detector addCandidate:myObject];\nNSSet *retainCycles = [detector findRetainCyclesWithMaxCycleLength:100];\n```\n\n### Filters\n\nThere could also be retain cycles that we would like to omit. It's because not every retain cycle is a leak, and we might want to filter them out.\nTo do so we need to specify filters:\n\n```objc\nNSMutableArray *filters = @[\n  FBFilterBlockWithObjectIvarRelation([UIView class], @\"_subviewCache\"),\n];\n\n// Configuration object can describe filters as well as some options\nFBObjectGraphConfiguration *configuration =\n[[FBObjectGraphConfiguration alloc] initWithFilterBlocks:filters\n                                     shouldInspectTimers:YES];\nFBRetainCycleDetector *detector = [[FBRetainCycleDetector alloc] initWithConfiguration:configuration];\n[detector addCandidate:myObject];\nNSSet *retainCycles = [detector findRetainCycles];\n```\n\nEvery filter is a block that having two `FBObjectiveCGraphElement` objects can say, if their relation is valid.\n\nCheck [FBStandardGraphEdgeFilters](FBRetainCycleDetector/Filtering/FBStandardGraphEdgeFilters.h) to learn more about how to use filters.\n\n### NSTimer\n\nNSTimer can be troublesome as it will retain it's target. Oftentimes it means a retain cycle. `FBRetainCycleDetector` can detect those,\nbut if you want to skip them, you can specify that in the configuration you are passing to `FBRetainCycleDetector`.\n\n```objc\nFBObjectGraphConfiguration *configuration =\n[[FBObjectGraphConfiguration alloc] initWithFilterBlocks:someFilters\n                                     shouldInspectTimers:NO];\nFBRetainCycleDetector *detector = [[FBRetainCycleDetector alloc] initWithConfiguration:configuration];\n```\n\n### Associations\n\nObjective-C let's us set associated objects for every object using [objc_setAssociatedObject](https://developer.apple.com/library/mac/documentation/Cocoa/Reference/ObjCRuntimeRef/#//apple_ref/c/func/objc_setAssociatedObject).\n\nThese associated objects can lead to retain cycles if we use retaining policies, like `OBJC_ASSOCIATION_RETAIN_NONATOMIC`. FBRetainCycleDetector can catch these kinds of cycles, but to do so we need to set it up. Early in the application's lifetime, preferably in `main.m` we can add this:\n\n```objc\n#import \u003cFBRetainCycleDetector/FBAssociationManager.h\u003e\n\nint main(int argc, char * argv[]) {\n  @autoreleasepool {\n    [FBAssociationManager hook];\n    return UIApplicationMain(argc, argv, nil, NSStringFromClass([AppDelegate class]));\n  }\n}\n```\n\nIn the code above `[FBAssociationManager hook]` will use [fishhook](https://github.com/facebook/fishhook) to interpose functions `objc_setAssociatedObject` and `objc_resetAssociatedObjects` to track associations before they are made.\n\n## Getting Candidates\n\nIf you want to profile your app, you might want to have an abstraction over how to get candidates for `FBRetainCycleDetector`. While you can simply track it your own, you can also use [FBAllocationTracker](https://github.com/facebook/FBAllocationTracker). It's a small tool we created that can help you track the objects. It offers simple API that you can query for example for all instances of given class, or all class names currently tracked, etc.\n\n`FBAllocationTracker` and `FBRetainCycleDetector` can work nicely together. We have created a small example and drop-in project called [FBMemoryProfiler](https://github.com/facebook/FBMemoryProfiler) that leverages both these projects. It offers you very basic UI that you can use to track all allocations and force retain cycle detection from UI.\n\n## Contributing\nSee the [CONTRIBUTING](CONTRIBUTING.md) file for how to help out.\n\n## License\n[`FBRetainCycleDetector` is BSD-licensed](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffacebook%2FFBRetainCycleDetector","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffacebook%2FFBRetainCycleDetector","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffacebook%2FFBRetainCycleDetector/lists"}