You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
- Rename Core-Components.md to CoreComponents.md (remove hyphens)
- Rename Advanced-Topics.md to AdvancedTopics.md (remove hyphens)
- Update article references in OpenAttributeGraph.md to match filenames
- Remove Architecture-article suffix, use Architecture directly
- Remove all ** bold formatting from markdown articles
- Update article titles to match filename conventions
Copy file name to clipboardExpand all lines: Sources/OpenAttributeGraph/OpenAttributeGraph.docc/Architecture.md
+41-41Lines changed: 41 additions & 41 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -14,13 +14,13 @@ The **Attribute layer** forms the foundation of the reactive system, providing t
14
14
15
15
#### Core Concepts
16
16
17
-
**Property Wrapper Design**: At its heart, ``Attribute`` is a property wrapper that makes any Swift value reactive. When you wrap a value with `@Attribute`, it automatically gains dependency tracking capabilities:
17
+
Property Wrapper Design: At its heart, ``Attribute`` is a property wrapper that makes any Swift value reactive. When you wrap a value with `@Attribute`, it automatically gains dependency tracking capabilities:
18
18
19
19
@Attribute var count: Int = 0
20
20
21
-
**Type Erasure**: ``AnyAttribute`` provides type-erased access to attributes, enabling runtime flexibility while maintaining type safety where possible.
21
+
Type Erasure: ``AnyAttribute`` provides type-erased access to attributes, enabling runtime flexibility while maintaining type safety where possible.
22
22
23
-
**Rule-Based Transformations**: The ``Rule`` and ``StatefulRule`` protocols allow you to create computed attributes that automatically update when their dependencies change:
23
+
Rule-Based Transformations: The ``Rule`` and ``StatefulRule`` protocols allow you to create computed attributes that automatically update when their dependencies change:
24
24
25
25
struct DoubledRule: Rule {
26
26
typealias Value = Int
@@ -31,52 +31,52 @@ The **Attribute layer** forms the foundation of the reactive system, providing t
31
31
}
32
32
}
33
33
34
-
**Reference Semantics**: ``WeakAttribute`` and ``OptionalAttribute`` provide safe ways to handle optional and weak references within the attribute system.
34
+
Reference Semantics: ``WeakAttribute`` and ``OptionalAttribute`` provide safe ways to handle optional and weak references within the attribute system.
35
35
36
36
#### Body System
37
37
38
38
The attribute body system optimizes performance through:
39
-
-**Lazy evaluation**: Values are only computed when needed
40
-
-**Caching**: Results are cached until dependencies change
41
-
-**Efficient invalidation**: Only affected attributes are marked for recomputation
39
+
- Lazy evaluation: Values are only computed when needed
40
+
- Caching: Results are cached until dependencies change
41
+
- Efficient invalidation: Only affected attributes are marked for recomputation
42
42
43
43
### Graph Layer
44
44
45
-
The **Graph layer** manages the dependency network between attributes and orchestrates efficient updates.
45
+
The Graph layer manages the dependency network between attributes and orchestrates efficient updates.
46
46
47
47
#### Dependency Management
48
48
49
49
The ``Graph`` maintains a directed acyclic graph (DAG) of attribute dependencies:
50
50
51
-
-**Automatic tracking**: Dependencies are discovered automatically when attributes are accessed during rule evaluation
52
-
-**Cycle detection**: The system prevents and detects circular dependencies
53
-
-**Batch updates**: Multiple changes are batched together for optimal performance
51
+
- Automatic tracking: Dependencies are discovered automatically when attributes are accessed during rule evaluation
52
+
- Cycle detection: The system prevents and detects circular dependencies
53
+
- Batch updates: Multiple changes are batched together for optimal performance
54
54
55
55
#### Update Propagation
56
56
57
57
When an attribute changes, the graph efficiently propagates updates:
58
58
59
-
1.**Mark phase**: Changed attributes are marked as invalid
60
-
2.**Sweep phase**: Dependent attributes are transitively marked
61
-
3.**Update phase**: Values are recomputed in dependency order
59
+
1. Mark phase: Changed attributes are marked as invalid
60
+
2. Sweep phase: Dependent attributes are transitively marked
61
+
3. Update phase: Values are recomputed in dependency order
62
62
63
63
#### Subgraphs
64
64
65
65
``Subgraph`` provides scoped computation contexts that allow:
66
-
-**Isolation**: Separate update domains for different parts of your application
The **Runtime layer** provides the low-level type introspection and memory management that makes the higher layers possible.
72
+
The Runtime layer provides the low-level type introspection and memory management that makes the higher layers possible.
73
73
74
74
#### Type Introspection
75
75
76
76
``Metadata`` provides Swift runtime type information:
77
-
-**Field enumeration**: Discover the fields of any Swift type at runtime
78
-
-**Layout information**: Access memory layout and alignment details
79
-
-**Type comparison**: Efficiently compare types and values
77
+
- Field enumeration: Discover the fields of any Swift type at runtime
78
+
- Layout information: Access memory layout and alignment details
79
+
- Type comparison: Efficiently compare types and values
80
80
81
81
This runtime introspection enables features like automatic KeyPath-based attribute access:
82
82
@@ -86,13 +86,13 @@ This runtime introspection enables features like automatic KeyPath-based attribu
86
86
#### Memory Management
87
87
88
88
The runtime layer handles:
89
-
-**Pointer arithmetic**: Safe offset calculations for nested attribute access
90
-
-**Type-safe casting**: Runtime type validation and casting
91
-
-**Value comparison**: Efficient equality checking across different types
89
+
- Pointer arithmetic: Safe offset calculations for nested attribute access
90
+
- Type-safe casting: Runtime type validation and casting
91
+
- Value comparison: Efficient equality checking across different types
92
92
93
93
#### Integration with Swift Runtime
94
94
95
-
> **Note**: The Runtime layer leverages techniques similar to those found in [wickwirew/Runtime](https://github.com/wickwirew/Runtime) for Swift runtime introspection and type manipulation.
95
+
> Note: The Runtime layer leverages techniques similar to those found in [wickwirew/Runtime](https://github.com/wickwirew/Runtime) for Swift runtime introspection and type manipulation.
96
96
97
97
The system integrates deeply with Swift's runtime to:
98
98
- Access private metadata structures safely
@@ -105,34 +105,34 @@ The system integrates deeply with Swift's runtime to:
105
105
106
106
When you create an attribute, all three layers collaborate:
107
107
108
-
1.**Runtime layer**: Introspects the value type and creates metadata
109
-
2.**Graph layer**: Allocates space in the dependency graph
110
-
3.**Attribute layer**: Wraps the value in a reactive property wrapper
108
+
1. Runtime layer: Introspects the value type and creates metadata
109
+
2. Graph layer: Allocates space in the dependency graph
110
+
3. Attribute layer: Wraps the value in a reactive property wrapper
111
111
112
112
### Dependency Tracking
113
113
114
114
During rule evaluation:
115
115
116
-
1.**Attribute layer**: Rules access their dependency attributes
117
-
2.**Graph layer**: Records these accesses as dependencies
118
-
3.**Runtime layer**: Handles type-safe value extraction and conversion
116
+
1. Attribute layer: Rules access their dependency attributes
117
+
2. Graph layer: Records these accesses as dependencies
118
+
3. Runtime layer: Handles type-safe value extraction and conversion
119
119
120
120
### Update Propagation
121
121
122
122
When a change occurs:
123
123
124
-
1.**Attribute layer**: Detects the value change
125
-
2.**Graph layer**: Propagates invalidation through dependencies
126
-
3.**Runtime layer**: Provides efficient value comparison to minimize updates
124
+
1. Attribute layer: Detects the value change
125
+
2. Graph layer: Propagates invalidation through dependencies
126
+
3. Runtime layer: Provides efficient value comparison to minimize updates
127
127
128
128
## Performance Characteristics
129
129
130
130
The three-layer architecture enables several performance optimizations:
131
131
132
-
-**Minimal allocations**: Attributes reuse storage and minimize memory churn
133
-
-**Lazy evaluation**: Computations are deferred until values are actually needed
134
-
-**Batch processing**: Multiple updates are processed together
135
-
-**Cache efficiency**: Hot paths through the dependency graph are optimized
132
+
- Minimal allocations: Attributes reuse storage and minimize memory churn
133
+
- Lazy evaluation: Computations are deferred until values are actually needed
134
+
- Batch processing: Multiple updates are processed together
135
+
- Cache efficiency: Hot paths through the dependency graph are optimized
0 commit comments