# facebook/fbretaincycledetector architecture

> Architecture diagram of the GitHub repository facebook/fbretaincycledetector, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/facebook/fbretaincycledetector
- Repository: https://github.com/facebook/fbretaincycledetector

## Overview

##### Project Type and Purpose
- This project is a specialized iOS library built to assist developers in detecting memory leaks caused by retain cycles at runtime.
- The README emphasizes usage in Debug builds, configuration via filters, candidate collection via FBAllocationTracker, and integration with function interposition (using fishhook) to monitor Objective-C associations.
- The repository is structured as a mixed codebase that not only implements the detection logic (using a modular split across Detector, Graph creation, and Filtering) but also includes supporting integration libraries for associated objects capture.

##### Analyzing the File Structure
- Top-level directories/files suggest a typical open-source iOS framework:
- Directories like FBRetainCycleDetector, containing subdirectories for different components:
○ Associations – holds classes like FBAssociationManager and its internal helpers;
○ Detector – contains the core detector classes (FBRetainCycleDetector, FBNodeEnumerator, etc.) that actually drive the cycle-finding logic.
○ Graph – constructs the object graph representation by wrapping objects (and includes specialized parts for blocks and timers);
○ Filtering – holds edge filters to decide which relationships to ignore.
○ Layout – includes code to help present or relate findings (for example, how cycles are formatted).
- Unit tests are contained in FBRetainCycleDetectorTests demonstrating how to exercise and verify the library functionality.
- Build and configuration files (podspec, build scripts, GitHub workflows) indicate CI and integration support.
- The rcd_fishhook directory and update_fishhook.sh script point to an embedded fishhook integration for function interposition – a key piece of the association tracking.

##### Main Components and Their Relationships
- FBRetainCycleDetector Core:
- Primary API for detecting cycles. It interacts with candidate objects and outputs sets of cycles.
- Resides in the Detector module.
- Object Graph Builder:
- The Graph directory encapsulates classes that build the object graph (consider including FBObjectiveCGraphElement, FBObjectiveCObject, etc.).
- Depicts the transformation of runtime objects into graph nodes.
- Filtering Subsystem:
- The Filtering directory holds edge filters (FBStandardGraphEdgeFilters) to refine which connections may lead to false positives.
- Layout and Presentation:
- Layout directories (Blocks, Classes) indicate helper utilities to arrange graph aspects for clearer visualization.
- Association Handling:
- The Associations directory, where FBAssociationManager hooks into Objective-C runtime functions.
- Configuration Module:
- FBObjectGraphConfiguration which accepts filter blocks and timer behavior settings.
- Testing and Integration:
- The FBRetainCycleDetectorTests area can be denoted as ensuring correctness of the entire process.
- Optionally, list integration with FBAllocationTracker and FBMemoryProfiler as external consumers of this library.

Relationships between these components:
● An iOS application (or test harness) first initializes integration by calling [FBAssociationManager hook] (via fishhook) at startup.
● The application then creates an instance of FBRetainCycleDetector.
● The detector receives candidate objects – a process optionally managed by FBAllocationTracker.
● The detector uses its FBObjectGraphConfiguration settings (possibly containing filter blocks) to guide the analysis.
● The Detector module leverages the Graph and Filtering components to build the object graph and prune extraneous relations before computing cycles.
● Finally, the results (object cycles) are output for diagnostic logging or further processing.

##### Architectural Patterns and Design Principles
- Modularity: Each logical aspect (association tracking, graph building, filtering, layout) is encapsulated within its dedicated module.
- Separation of Concerns: The design isolates detection logic (Detector) from configuration (FBObjectGraphConfiguration) and runtime modifications (FBAssociationManager).
- Inversion of Control: The library expects users to plug in their filter blocks and candidate management logic.
- Use of Function Interposition: Integration with fishhook highlights an advanced runtime technique.

## Diagram (Mermaid)

```mermaid
flowchart TD
    APP("Application/Main Entry"):::external
    Alloc("FBAllocationTracker"):::external
    Mem("FBMemoryProfiler"):::external

    Assoc("Association Handling (FBAssociationManager)"):::orange
    Fish("Fishhook Integration"):::orange
    Core("FBRetainCycleDetector Core"):::blue
    Config("Configuration Module (FBObjectGraphConfiguration)"):::green
    Graph("Object Graph Builder"):::blue
    Filtering("Filtering Subsystem"):::blue
    Layout("Layout and Presentation"):::blue
    Tests("Testing & Integration"):::green

    %% Relationships
    APP -->|"initiate"| Assoc
    Assoc -->|"hooks_runtime"| Fish
    APP -->|"creates_instance"| Core
    Alloc -->|"provides_candidates"| Core
    Core -->|"uses"| Config
    Core -->|"builds_graph"| Graph
    Graph -->|"returns_graph"| Core
    Core -->|"applies_filters"| Filtering
    Filtering -->|"refines_graph"| Core
    Core -->|"formats_results"| Layout
    Core -->|"outputs_cycles"| Mem
    Tests -->|"validates"| Core

    %% Click Events
    click Core "https://github.com/facebook/fbretaincycledetector/tree/main/FBRetainCycleDetector/Detector"
    click Graph "https://github.com/facebook/fbretaincycledetector/tree/main/FBRetainCycleDetector/Graph"
    click Filtering "https://github.com/facebook/fbretaincycledetector/tree/main/FBRetainCycleDetector/Filtering"
    click Layout "https://github.com/facebook/fbretaincycledetector/tree/main/FBRetainCycleDetector/Layout"
    click Assoc "https://github.com/facebook/fbretaincycledetector/tree/main/FBRetainCycleDetector/Associations"
    click Fish "https://github.com/facebook/fbretaincycledetector/tree/main/rcd_fishhook"
    click Config "https://github.com/facebook/fbretaincycledetector/blob/main/FBRetainCycleDetector/Graph/FBObjectGraphConfiguration.h"
    click Tests "https://github.com/facebook/fbretaincycledetector/tree/main/FBRetainCycleDetectorTests"

    %% Styles
    classDef blue fill:#AED6F1,stroke:#1B4F72,stroke-width:2px;
    classDef orange fill:#FAD7A0,stroke:#D35400,stroke-width:2px;
    classDef green fill:#A9DFBF,stroke:#229954,stroke-width:2px;
    classDef external fill:#D5DBDB,stroke:#616A6B,stroke-width:2px;
```
