This repository has been archived by the owner on Feb 16, 2022. It is now read-only.
-
Notifications
You must be signed in to change notification settings - Fork 11
/
Copy pathDocumentation.html
626 lines (398 loc) · 56.6 KB
/
Documentation.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
<!DOCTYPE html>
<html>
<head>
<title></title>
<meta charset="utf-8"/>
</head>
<body>
<h1 id="tableofcontents">Table of Contents</h1>
<nav role="navigation" class="table-of-contents">
<ul>
<li><a href="#a-note-on-nomenclature">A Note on Nomenclature</a></li>
<li><a href="#observable-objects-and-properties">Observable Objects And Properties</a></li>
<li><a href="#key-paths">Key Paths</a></li>
<li><a href="#the-act-of-observing">The Act of Observing</a></li>
<li><a href="#beginning-observation">Beginning Observation</a></li>
<li><a href="#ending-observation">Ending Observation</a></li>
<li><a href="#observation-blocks">Observation Blocks</a></li>
<li><a href="#when-observation-blocks-get-called">When Observation Blocks Get Called</a></li>
<li><a href="#what-observable-does-while-observing">What Observable Does While Observing</a></li>
<li><a href="#cleanup-and-object-lifetime">Cleanup and Object Lifetime</a></li>
<li><a href="#observing-the-observers">Observing the Observers</a></li>
<li><a href="#dealloc-protocol">Dealloc Protocol</a></li>
<li><a href="#manually-triggering-observers">Manually Triggering Observers</a></li>
<li><a href="#debugging">Debugging</a></li>
<li><a href="#minutiae">Minutiae</a></li>
<li><a href="#common-features">Common Features</a></li>
<li><a href="#ebnobservabledictionary">EBNObservableDictionary</a></li>
<li><a href="#ebnobservableset">EBNObservableSet</a></li>
<li><a href="#ebnobservablearray">EBNObservableArray</a></li>
<ul>
<li><a href="#object-following-observations">Object-Following Observations</a></li>
<li><a href="#index-following-observations">Index-Following Observations</a></li>
</ul>
<li><a href="#minutiae-1">Minutiae</a></li>
<li><a href="#lazily-loaded-properties">Lazily Loaded Properties</a></li>
<li><a href="#synthetic-properties">Synthetic Properties</a></li>
<li><a href="#collection-properties-and-mutability-a-case-study">Collection Properties and Mutability: a Case Study</a></li>
<li><a href="#custom-loaders">Custom Loaders</a></li>
<li><a href="#hybrid-properties">Hybrid Properties</a></li>
<li><a href="#observing-synthetic-properties">Observing Synthetic Properties</a></li>
<li><a href="#chaining-synthetic-properties">Chaining Synthetic Properties</a></li>
<li><a href="#debugging-lazyloader-properties">Debugging LazyLoader Properties</a></li>
</ul>
</nav>
<hr />
<h1 id="whyuseobservable">Why Use Observable</h1>
<hr />
<p>Observable is a code package that lets you observe changes made to object properties. Similar to Apple’s KVO solution, you refer to properties with key path strings, your ‘observing’ object registers for observation with an ‘observed’ object, and when the observed value gets changed, you get told.</p>
<p>Unlike Apple’s KVO, Observable:</p>
<ul>
<li>Is based on blocks. You get notified of changes by providing a block to call.</li>
<li>Delays reporting of changes, and coalesces notifications of multiple changes that happen in quick succession.</li>
<li>Does not tell your block <strong>what</strong> sort of change happened, or what the previous value was. This is a side effect of the previous point.</li>
<li>Is clear on what happens when a key path entry is nil, or when a value in the middle of a key path changes while the path is being observed.</li>
<li>Is forgiving of observers that don’t clean up their observations, or that clean up their observations more times than they make them.</li>
<li>Implements observable collection classes that work as you’d expect.</li>
</ul>
<p>Observable is also designed with debugging in mind, providing several debug methods letting you see what properties are currently being observed for a particular object, and lets you set break-on-change breakpoints that act similar to watchpoints.</p>
<p>Plus, Observable has a subclass called LazyLoader, which makes it easy for you to implement lazily loaded properties, synthetic properties, and computed properties that work correctly with Observable.</p>
<h1 id="observablereference">Observable Reference</h1>
<hr />
<h2 id="anoteonnomenclature">A Note on Nomenclature</h2>
<p>This documentation refers to Observable as the SDK package, although the core class is EBNObservable, and all of its classes are prefixed EBN. This is because this code is plucked straight from the eBay for iPhone app, and the team has coding standards. Observable and EBNObservable are more or less interchangeable terms.</p>
<h2 id="observableobjectsandproperties">Observable Objects And Properties</h2>
<p>Generally speaking, an object that can be observed is an NSObject subclass that has properties. Exceptions include CoreFoundation objects that can’t be isa-swizzled, tagged pointers (those things where the ‘pointer’ contains all the information and doesn’t really point to anything), and certain kinds of proxy objects that don’t play nice with runtime subclassing. Swift objects can be observed, with the same caveats that exist for using the KVO observation available in Swift 4’s Foundation library.</p>
<p>Collection classes such as NSSet, NSDictionary, and NSArray and their mutable subclasses are observable objects, in that they have properties such as a <code>count</code> property and those properties can be observed, but much more often you want to observe an item in a collection class, which Observable also supports, although Apple’s KVO and KVC do not.</p>
<p>Just like with Apple’s KVO, for automatic observation of property changes to work properly the implementor of a class needs to always use property setter semantics when setting properties. You can use “object.property = x” notation or [object setProperty:x] notation. Using object->_property = x will change the property value without notifying observers, which is usually bad form, but be sure to follow the rules about using that form in init, dealloc, and within the setter method itself.</p>
<p>Most property types are observable. Strong, weak, copy, assign, atomic/nonatomic, IBOutlet properties–they can all be observed. Exceptions include certain kinds of struct-valued properties that Observable doesn’t know about, properties of Swift objects that don’t subclass NSObject, and a few exotic types of non-KVC compliant properties (generally, properties that cause a crash if you call <code>valueForKey:</code> on them).</p>
<p>Internally, when Observable begins observing a property for changes it creates a runtime subclass of the observed object’s class, adds a custom setter method to that subclass that calls through to the original setter and also handles notifying observers, and changes the class of the observed object to be the runtime-created subclass. This is very similar to what Apple’s KVO does to implement automatic change notification.</p>
<h2 id="keypaths">Key Paths</h2>
<p>A key path is a string of property names separated by periods. Key paths are always relative paths, rooted from the observed object. For example, for a singleton <code>UserCache</code> object that has a <code>currentUser</code> property (of type <code>User</code>) which in turn had an <code>Address</code> property, you might have a key path rooted at the singleton that looked like this:</p>
<pre><code class="C"> @interface UserCache : NSObject
@property User currentUser;
@end
@interface User : NSObject
@property StreetAddress address;
@end
@interface StreetAddress : NSObject
@property NSString *zipCode;
@end
NSString *keyPath = @"currentUser.Address.zipCode";
</code></pre>
<p>This is all very much like Apple’s KVO. Each component of the key path must be an actual property of the preceding object. Because of this design, only the last property in a key path can be of non-object type–although it can also be of object type.</p>
<p>Apple’s KVO has a bunch of aggregation operators that can be put into key paths, such as <code>"@max"</code> and <code>"@unionOfObjects"</code>. Observable doesn’t implement these, because this is the first time you’ve ever heard of them.</p>
<p>There are a few special key path elements Observable does support that Apple’s KVO does not. The <code>"*"</code> element means, “every property of this object”. That is, a key path built from the UserCache object containing <code>"currentUser.*.zipCode"</code> observes every property of the User object, which in the example is only the <code>"addresses"</code> property. Note that the <code>"*"</code> operator will observe on properties defined in superclasses of the given object.</p>
<p>Additionally, Observable has some special element notations for constructing key paths that refer to elements of sets and arrays. We’ll get to those later.</p>
<h2 id="theactofobserving">The Act of Observing</h2>
<p>When you start observing a key path, Observable watches for changes to each property in the key path. When a property in the middle of an observed key path changes value (that is, that property’s setter method gets called) Observable will stop observing the old value’s object and start observing the new value, re-wiring observations for all objects along the key path if necessary. Importantly, this mechanism works if the old or new value for a property in the middle of a key path is nil. An important pattern to understand is that you can set up an observation in your object’s init method, observing a property of some object and also requesting the data for that property be fetched asynchronously (network or file load, asynchronous image operation, whatever). When the fetch completes the property value goes from nil to non-nil, and your observer gets called. If the object changes again later (or a value in the observed key path changes), you’ll get notified again. In this way your code that responds to the initial fetch completion is the same code that responds to changes.</p>
<p>In the <code>User</code> example above, if the key path “currentUser.Address.zipCode” was being observed and the currentUser’s <code>Address</code> object was replaced with a new <code>StreetAddress</code> object, the observation will update automatically to observe the new <code>StreetAddress</code> object–and also the new <code>zipCode</code> property of the new <code>StreetAddress</code>.</p>
<p>In code:</p>
<pre><code class="C"> StreetAddress *homeAddress, *workAddress;
// homeAddress is being observed
currentUser.address = homeAddress;
// now workAddress is being observed, and homeAddress isn't.
currentUser.address = workAddress;
// Change the zipCode
currentUser.address.zipCode = @"97210";
</code></pre>
<p>Now for a feature that makes Observable work significantly different than Apple’s KVO. If you’re observing “currentUser.address.zipCode”, all 3 of those assignment statements above could cause your observation callback to be called. That is, if a change to an object in the middle of the key path causes the value of the endpoint to change, your observation callback will get scheduled. In this case, the first line could change the <code>zipCode</code> field from nil to the user’s home address zip code. Changing the address field to the workAddress could change the zipCode field and cause the observer block to be scheduled, if <code>homeAddress.zipCode != workAddress.zipCode</code>. The final line could cause the block to be scheduled again, unless the zipCode field was <code>"97210"</code> before the setter was called.</p>
<p>Even though the zipCode field changed multiple times, the observation block will only be called once, as Observable coalesces multiple changes that cause the same block to be scheduled during the processing of the same event. More on this later.</p>
<h2 id="beginningobservation">Beginning Observation</h2>
<p>There are 3 basic ways to set up observation: The <code>Observe(ValidatePaths())</code> macro pair, EBNObservable’s <code>tell:</code> methods, and EBNObservation’s <code>observe:</code> method.
The <code>Observe(ValidatePaths())</code> macro is the easiest way to set up observation. The observer object must be <code>self</code>– you can’t use the macro to set up observation while making some other object the observer. But, the macro does some very useful syntax checking at compile time. The macro looks like this:</p>
<pre><code class="C"> Observe(ValidatePaths(observedObject, keyPath) { blockContents });
</code></pre>
<p>Note that keyPath is not in quotes, and that blockContents isn’t actually a block. The macro tries to validate each property in the key path by ensuring that the compiler thinks observedObject.keyPath is a valid construction. It also tries to prevent you from using self or observedObject inside the block, as this can cause retain loops or other object lifetime issues.</p>
<p>The property validation is a useful defense against future changes that may be made to the object(s) you’re observing. Code that uses the macro won’t compile if the names of properties in the key path change, or the type of a property in the middle of the key path changes and the new type doesn’t have the property that the path specifies.</p>
<p>To make this even more clear, if you use regular strings for your key path and specify <code>@"fullName"</code> as part of it, and then some other engineer changes the <code>fullName</code> property to be <code>full_name</code> because they hate camel-case, your observation will still compile and run, but will not work as Observable cannot find a <code>fullName</code> property to observe for changes. The macro solves this problem, and it’s an important problem to solve.</p>
<p>Next, the tell: methods. These are methods defined by EBNObservable, so when you use them, the syntax declares that you’re asking an Observable object to tell you when things happen.</p>
<pre><code class="C"> - (EBNObservation *) tell:(id) observer when:(NSString *) propertyName changes:(ObservationBlock) callBlock;
- (EBNObservation *) tell:(id) observer whenAny:(NSArray *) propertyList changes:(ObservationBlock) callBlock;
</code></pre>
<p>The first method observes a single key path, the second takes an array of paths.
Both methods take an ObservationBlock as a parameter, which is defined as:</p>
<pre><code class="C"> typedef void (^ObservationBlock)(id observingObj, id observedObj);
</code></pre>
<p>One of the conveniences of the ObserveProperty macro is that you don’t need to declare your block’s parameters; the macro does that for you. But, a more concise syntax means less flexibility.</p>
<p>On that note, the most flexible way to set up observation is to create an EBNObservation yourself. EBNObservation objects are returned by the macro and also by the tell: methods, but if you set it up yourself you can easily use the same block to observe multiple key paths, set up a custom debugging description, execute the observation block yourself, and more.</p>
<h2 id="endingobservation">Ending Observation</h2>
<p>When you are done observing you can call one of these macros:</p>
<pre><code class="C"> StopObservingPath(observedObject, keyPath);
StopObserving(observedObject);
</code></pre>
<p>These macros behave similarly to the <code>ObserveProperty()</code> macro in that they try to validate the key path. Both of these macros assume ‘<code>self</code>’ is the observing object. If that’s not the case, see below. <code>StopObserving()</code> removes all observations on observedObject where <code>'self'</code> is the observer, while <code>StopObservingPath()</code> only remove ones that match the given key path.</p>
<p>You can also use one of these methods to end observation:</p>
<pre><code class="C"> - (void) stopTellingAboutChanges:(id) observer;
- (void) stopAllCallsTo:(ObservationBlock) block;
- (void) stopTelling:(id) observer aboutChangesTo:(NSString *) propertyName;
- (void) stopTelling:(id) observer aboutChangesToArray:(NSArray *) propertyList;
</code></pre>
<p>The first method tells the receiver to deregister all tells to the given observer object, and the second deregisters all tells to the given block. If you want to call the second method, be sure to save the block pointer when you register.</p>
<p>The last two methods deregister all tells to your object that were registered for a particular property or set of properties. If for some reason you registered for the same property more than once (for example, both you and your superclass registered for the same thing), all matching registrations will be removed.</p>
<p>It is safe to call these methods when you’re not actually observing the given object.</p>
<p>Stopping observation does not un-schedule observation blocks that have already been scheduled. If an observed property is mutated, and then one of the StopObserving methods is called before the observation block fires (remember that observation blocks are delayed until the end of the current main event runloop), the observation block will still fire.</p>
<h2 id="observationblocks">Observation Blocks</h2>
<p>Your code gets informed of a change to a observed key path by providing an Observation block. Observation blocks take this form:</p>
<pre><code class="C"> typedef void (^ObservationBlock)(id observingObj, id observedObj);
</code></pre>
<p>When Observable calls your block, it will pass back the observing and observed objects. Inside your block, you should refer to the observing and observed objects using these block parameters. If you use e.g. <code>self</code> and <code>modelObject</code> instead, you will probably run into retain loop issues. You can create a <code>__weak self</code>, but you need a <code>__weak modelObject</code> as well and, … just use the parameters. They already handle retain loop issues for you.</p>
<p>Unlike Apple’s KVO, the block arguments do <strong>not</strong> tell you what the old or new value of the property is, or even which property changed. You can, of course, access the new value of the property directly. You can also set it, or set other properties, without infinite-looping.</p>
<h2 id="whenobservationblocksgetcalled">When Observation Blocks Get Called</h2>
<p>Another difference between this class and Apple’s KVO is that notification of changes is delayed until the end of the event in which the change occurred. This is done so that we can coalesce multiple changes into a single observationBlock call when possible, following this rule:</p>
<p><strong>A single ObservationBlock will get called at most once per event loop iteration.</strong></p>
<p>This means that if a property changes value multiple times in a single event, the block gets called once. If the same block is used in registering for many properties (such as the array variant), the block gets called once, even if all the properties were modified during the event.</p>
<p>If an ObservationBlock sets another property when it runs (in the same or a different object), and that property is being observed as well, that property’s observationBlock will be called only if it hasn’t been called yet during this event loop iteration.</p>
<p>Your ObservationBlock will always be called on the main thread, even if the property is set in a background thread.</p>
<p>Your block may get called when any element in the key path changes value, if that change causes the value of any endpoint property in the key path to change value, and this includes changing from “unreachable” to “nil”. If, for example, you are observing the key path <code>address.zipCode</code> but <code>address</code> is initially nil, your observation block will get called when the address gets set to a non-nil value, even if that address doesn’t have a zip code. In this case, the zipCode has changed from ‘not reachable’ to ‘nil’. Often you may not care about these changes, but sometimes you do.</p>
<p>Additionally, if your key path uses wildcards, you observation block will get called when any endpoint property of the key path changes value, and your observation block will not be told which value changed. Ideally, you should write your observation blocks to inspect the current state of the observed objects, and modify observer state as appropriate.</p>
<h2 id="whatobservabledoeswhileobserving">What Observable Does While Observing</h2>
<p>…and why it makes your choice of key paths more important than ever.</p>
<p>If you create an observation on a key path such as <code>"address.zipCode"</code> of the currentUser object and while the observation is active, someone sets the <code>address</code> property of the currentUser, Observable will stop observing the <code>zipCode</code> property of the previous <code>Address</code> object and start observing the <code>zipCode</code> of the new <code>Address</code> object. Additionally, if at the time you create the observation the <code>address</code> property is nil, Observable will remember to set up observation on the <code>address</code> object (and the address’s <code>zipCode</code> property) when they receive a non-nil value.</p>
<p>But what if you want to have your observation ‘follow’ the old address if someone sets a new address for the currentUser, instead of switching over to the new address value? In that case, you should observe the <code>zipCode</code> key path of the <code>currentUser.address</code> object.</p>
<p>In code:</p>
<pre><code class="C"> // This observation follows the new address if the address object is replaced
Observe(ValidatePaths(currentUser, address.zipCode) ...);
// This observation follows the old address if the address object is replaced
Observe(ValidatePaths(currentUser.address, zipCode) ...);
</code></pre>
<p>The ability to observe a path that may be nil at the time of observation can be very powerful, as you can in many cases set up an observation on a model object path when your object gets initialized, and then fire off a request to the model layer to fetch the object you’re observing. When the model layer completes the fetch (and attaches the fetched object to a model object hierarchy) you get informed automatically.</p>
<p>But, careful selection of what object should be the ‘root’ of the observing key path and what should be parts of the key path property list is very important. The way to think about constructing a proper key path is in terms of update behavior at each point in the path.</p>
<h2 id="cleanupandobjectlifetime">Cleanup and Object Lifetime</h2>
<p>You should deregister observers when the observing object deallocs, although it’s not a requirement. Unlike Apple’s KVO, failing to deregister won’t cause an assert. Also, deregistering multiple times won’t cause an assert. Deregistering an observation you never made won’t cause an assert. Registering the same observation multiple times won’t cause an assert.</p>
<p>An observation does not hold the observed or observing object strongly. A EBNObservable instance can be dealloc’ed while its properties are being observed, and an observer object can safely be dealloc’ed while it has observations in place. The only exception to this is that an observed object is held strongly from the time one of its observed properties is mutated until the observer block for that property is executed. This is to ensure the observers get called before the observed object goes away. In fact, Observable also holds the observer object strongly from the time its block is scheduled until the block is executed. The intent is to ensure all observed change notifications are actually delivered.</p>
<p>ObservationBlocks themselves have a lifetime that is dependent on both the lifetime of the observed and observing objects. Observable checks that both objects still exist before calling observation blocks. If an observing object is deallocated while it has blocks registered, those blocks may not be deallocated immediately–although they’ll never be called again.</p>
<h2 id="observingtheobservers">Observing the Observers</h2>
<p><em>oblig latin phrase: Qui custodiet ipsos custodes?</em></p>
<p>You can query an Observable object at any time to see which of its properties are being observed, and how many observers there are on any property.</p>
<pre><code> // Returns all properties currently being observed, as an array of strings.
- (NSArray *) allObservedProperties;
// Returns how many observers there are for the given property
- (NSUInteger) numberOfObservers:(NSString *) propertyName;
</code></pre>
<p>You can also implement the following method to get notified when your properties are being observed. You will only get called when the number of observers for a particular property goes from 0 to 1 or 1 to 0. Additional observers for an already-observed property do not cause this method to be called.</p>
<pre><code> - (void) property:(NSString *) propName observationStateIs:(BOOL) isBeingObserved;
</code></pre>
<p>An enterprising engineer could use this to dynamically decide when certain parts of an object needed to be loaded in from backing store, or requested from the network, based entirely on whether anyone wants to know the value.</p>
<h2 id="deallocprotocol">Dealloc Protocol</h2>
<p>If you’re observing properties of some other object, you can implement the ObservedObjectDeallocProtocol. This protocol has one method, which tells you if an object whose properties you were observing has been deallocated.</p>
<p>For example, suppose you have:</p>
<pre><code> @class SubObject;
@interface BigClass
@property (strong) SubObject *subObjectThing;
@end
</code></pre>
<p>If you observe a property of subObjectThing, and someone replaces subObjectThing with a new value (that is, calls <code>BigClass.subObjectThing = newObjectThing;</code> you’ll get notified and can update your observation to observe the new subObject. HOWEVER: this only works if the old subObject is deallocated after getting replaced (that is, if nobody else owns it).</p>
<h2 id="manuallytriggeringobservers">Manually Triggering Observers</h2>
<p>If you have a case where you really need to modify a property value in an Observable object, but can’t call the setter method, you can use one of these methods:</p>
<pre><code class="C"> - (void) manuallyTriggerObserversForProperty:(NSString *) propertyName previousValue:(id) prevValue;
- (void) manuallyTriggerObserversForProperty:(NSString *) propertyName previousValue:(id) prevValue newValue:(id) newValue;
</code></pre>
<p>The concept here is similar to Apple’s <code>willChangeValueForKey:</code> and <code>didChangeValueForKey:</code> methods, except you only have to make one call. To ensure everything works correctly:</p>
<ol>
<li>Save the previous value : <code>NSString *oldZip = address->_zipCode;</code></li>
<li>Change the value before calling : <code>address->_zipCode = @"97210";</code></li>
<li>Then call the manual trigger method, passing in the previous value : <code>[Address manuallyTriggerObserversForProperty:@"zipCode" previousValue:oldZip];</code></li>
</ol>
<p>In most sane cases you will not have to deal with calling <code>manuallyTriggerObserversForProperty:</code>. But, because Observable will dynamically keep a key path up to date, meaning that as elements in the middle of a key path change value we update what object properties are being observed, it is important that you add manual trigger calls in cases where you can’t call the setter method. Much of what these methods do is keep key paths up to date.</p>
<p>An important caveat is that you do not have to do manual triggering for a property inside of that property’s custom setter method.</p>
<h2 id="debugging">Debugging</h2>
<p>You can see who all is observing a given object by calling <code>debugShowAllObservers</code> on an observed object.
In the debugger, call <code>po [modelObject debugShowAllObservers]</code> to see who’s observing the modelObject’s properties.</p>
<p>For example, while stopped in the lldb debugger:</p>
<pre><code> (lldb) po [currentUser debugShowAllObservers]
<User: 0x109311660>
address notifies:
0x109311960: for <AddressLabelCell: 0x10fe0f100> declared at AddressLabelCell.m:879
</code></pre>
<p>This shows that the <code>address</code> property of the <code>currentUser</code> object is being observed by an <code>AddressLabelCell</code> object.</p>
<p>The other neat debugging trick is that you can use Observable to set breakpoints that act very similar to debugger watchpoints, without the extreme slowness.</p>
<p>Again, in the debugger:</p>
<pre><code> (lldb) po [CurrentUser debugBreakOnChange:@"address.zipCode"]
Will break in debugger when address.zipCode changes.
...(continue execution)...
debugBreakOnChange breakpoint on keyPath: address.zipCode
debugString: Set from debugger.
prevValue: nil
newValue: 97210
(lldb)
</code></pre>
<p>What this does is create an observation whose observer block will break into the debugger when it gets called. This is very similar to setting a breakpoint on the setter method for a property, with a breakpoint condition that checks the self pointer against a specific value. However, <code>debugBreakOnChange:</code> will actually follow changes to the key path, meaning that if the currentUser’s address object is changed, the breakpoint will get hit when the zipCode property of the new address object is modified.</p>
<h2 id="whatnottodo">What Not to Do</h2>
<p>Avoid using bare strings for key paths whenever possible. If the name of a property in your key path changes later, your program still compiles and runs, but the observation never fires because its key path does not exist. You may expect that an invalid key path would cause a runtime error, but there are very good reasons why it doesn’t. Instead of bare strings, use the Observe() macros to create observations or the EBNValidatePath() macro to validate key paths whenever possible.</p>
<p>Instead of trying to manage balanced observe/stopObserving pairs, it’s generally much easier to observe in init and remove observations in dealloc, and then put a test inside your block. The overhead of observation is really quite small, it’s much easier to reason about your code if you do this.</p>
<p>Although Observable tries to help you avoid retain loops by giving you weakified/strongified versions of the observed and observing objects, you still need to watch for possible retain loops on <strong>other</strong> objects your block captures.</p>
<h2 id="minutiae">Minutiae</h2>
<ul>
<li>Setting a property to the same value it currently has will not cause observers to fire. For properties of object type, uses pointer comparison and not <code>isEqual:</code> to determine equality.</li>
<li>Observable is designed to work with ARC exclusively, and it requires iOS 6.</li>
<li>Observable tries to keep asserts to a minimum, but it has several asserts for programmer errors and places that may need improvement. One such place is that we only currently work with a few types of struct properties. Every struct property type needs to be special cased.</li>
<li>Observable can interoperate with Apple’s KVO. Both systems can observe the same property of the same object without interfering with each other.</li>
<li>Observable has troubles working with OCMock, mostly involving OCMock not being a good citizen with how it uses isa-swizzling. OCMock has code that sets the class of an object to its <em>original</em> class when it’s done mocking the object, which means that if the object had been being observed upon, that observation is broken after mocking. OCMock has fundamentally the same problem interoperating with Apple’s KVO.</li>
</ul>
<h1 id="observablecollectionsreference">Observable Collections Reference</h1>
<p>Observable has subclasses for <code>NSArray</code>, <code>NSSet</code> and <code>NSDictionary</code> and their mutable subclasses that can be observed and their contents can be observed just like any Observable subclass.</p>
<p>Specifically:</p>
<pre><code class="C"> EBNObservableDictionary *wordDictionary = [[EBNObservableDictionary alloc] init];
[wordDictionary tell:self when:@"steampunk" changes:
^(WordOfTheDay *blockSelf, EBNObservableDictionary *observed)]
{
// This gets called when the key "steampunk" is added, changed, or removed
// Get the object of the key normally
WordDefinition *def = [observed objectForKey:@"steampunk"];
});
</code></pre>
<p>If wordDictionary were a property of some other object, you could also observe the path <code>@"otherObject.wordDictionary.steampunk"</code>. Similarly, you can make a key path that goes through the object in the dictionary, such as <code>@"otherObject.wordDictionary.steampunk.pronunciationGuide"</code>.</p>
<h2 id="commonfeatures">Common Features</h2>
<p>All 3 collection classes have <code>count</code> as a declared property. This means that you can observe the count of members of a collection, just as with any other Observable object.</p>
<p>You can observe on elements of immutable collections, although this is generally only useful when the immutable collection is in the middle of a key path. That is, you can observe <code>@"immutableDictionary.dictionaryKey.nameProperty"</code> and be notified when the nameProperty of the object for the key <code>"dictionaryKey"</code> changes, even though the value for <code>"dictionaryKey"</code> itself cannot change, as it’s in a NSDictionary.</p>
<p>As with all other observable objects you can observe the key ‘*’ and be informed whenever the collection is mutated. The collection objects treat ‘*’ in a special way, and don’t place observations on the actual properties of the collection objects (such as <code>count</code> and <code>description</code>). But the semantics are the same–your observer gets called in response to any mutation.</p>
<p>It is entirely possible to create observation key paths of the form <code>@"*.*.*.*"</code>, observing all objects in a hierarchy of collection objects. Observable may run into performance problems if you do this, particularly if you have tens of thousands of objects in the hierarchy.</p>
<p>All 3 classes conform to NSSecureCoding, NSCopying, and NSMutableCopying, although they do not copy or encode observations. That is, a copied collection or a encoded/decoded collection will not carry over any of the observations that were active in the source collection object. Remember–the original item is <em>in</em> some key path as it’s a property of some root object that’s being observed, and the copy is <em>not</em> in that key path.</p>
<h2 id="ebnobservabledictionary">EBNObservableDictionary</h2>
<p>Dictionary keys must be NSStrings in order for their contents to be observed.</p>
<p>You can observe a key in a dictionary when that key does not yet have any value. Observation blocks on a key will be executed when that key’s value is changed, where ‘changed’ means: exactly one of old value and new value are nil, or <code>![newValue isEqual: oldValue]</code> . Calling <code>removeObjectForKey:</code> on an observed key will call observers if and only if the value for that key was previously non-nil.</p>
<h2 id="ebnobservableset">EBNObservableSet</h2>
<p>Creating observable sets requires that we have some way to specify a member of a set in a text string. EBNObservableSet therefore has a special method, <code>keyForObject:</code> that returns an NSString that can be used in a key path to refer to that object. This method works by taking the hash of the object and turning it into a string starting with ‘&’. The object does not need to be in the set at the time its key is created, but beware since mutating the object can modify its hash value, meaning that were you to generate and observe a key, mutate the object, and then add it to the set, your observer block will not execute as the object added to the set no longer matches the key being observed.</p>
<p>EBNObservableSet will call observers when observed objects are actually added or removed from the set. Calling <code>addObject:</code> on an object that is already in the set (or where the set already has an object that passes the isEqual: test) will not execute observers; neither will calling <code>removeObject:</code> on an object not in the set.</p>
<p>Because your observations are on a hash, and not the actual objects in the set, your observation blocks need to be ready to be called in the case of hash collisions. If an object with the same hash as the object you care about is added/removed from the set, your observation block will get called. Your observation block can then use isEqual: to differentiate between objects with the same hash.</p>
<p>There is also an <code>objectForKey:</code> method, letting you find an object in the set that matches a generated key. SPECIAL NOTE: Please be sure to understand the difference between <code>hash</code> and <code>isEqual:</code> before using this, and be aware that hash collisions can happen.</p>
<p>Really, the most common use case is to observe ‘*’ on the set and get notified whenever the set is mutated.</p>
<h2 id="ebnobservablearray">EBNObservableArray</h2>
<p>Observable arrays have two different ways to refer to their elements in a key path: Object-Following and Index-Following.</p>
<h3 id="object-followingobservations">Object-Following Observations</h3>
<p>First is the “object-following’ style, which looks like ”“array.4”. In this style, the key for the element in the array you want to observe is indicated with the current index of that element. For this observation style, the observation follows that object in the array. If elements before the observed element are added or removed, the observation updates so that it will continue to observe the initial array element. This means that the observed element’s current position in the array may no longer match its key path. With this style of observation, the observer block is only executed when the observed object is removed from the array. And, of course, the object you wish to observe must be in the array before you begin observation.</p>
<p>Attempting to observe an array with an object-following observation where the index to observe is beyond the end of the array is an error.</p>
<p>Object-following observations will remove themselves after they call the observer block. Note that this happens even if the array element isn’t the endpoint of the key path. Since the observer block is only called when the observed object leaves the array, and the object in the array that was being observed was only referenced by index at the time at the time the observation was set up, there is no way to re-connect the path in this case, even if the same object were re-added to the array.</p>
<h3 id="index-followingobservations">Index-Following Observations</h3>
<p>The other element reference style precedes the element index with a ‘#’, and the observation thus created will follow the index, not the object. If elements are added or removed at previous positions in the array, the observation will update itself so that it is always observing the element at the originally given index. If the size of the array shrinks so that the array no longer has an element at the given index, it is treated as if the value has become nil. For this observation style, observer blocks are executed whenever the object at the observed index changes–this includes the case where <code>replaceObjectAtIndex:</code> is called for the observed index.</p>
<p>It is allowed to create index-following observations on indexes that are beyond the current end of the array. In fact, it’s fairly common practice to initialize an empty array and immediately observe the first 7–12 indexes, before anything is placed in the array.</p>
<h2 id="minutiae">Minutiae</h2>
<p>The collection classes work by declaring themselves to be runtime subclasses of classes in their collection’s class cluster.</p>
<p>When a collection object is observed, EBNObservable gets the collection cluster subclass that handles that collection, and (if necessary) creates a runtime subclass of that class, replacing the collection primitives in the runtime subclass.</p>
<p>Copying an observable collection object does not copy the observations. However, mutableCopy will return an observable collection object (an EBNObservable), not an NSMutable.</p>
<h1 id="lazyloaderreference">LazyLoader Reference</h1>
<p>LazyLoader is a class that leverages Observable to introduce a few new capabilities appropriate for model objects. LazyLoader allows for the creation of several types of <em>synthetic properties</em>, which in this context means a property whose value is synthesized from other property values.</p>
<p>LazyLoader synthetic properties are <strong>properties</strong>, just like normal Objective-C properties. You can declare them strong, weak, assign, copy, atomic or not, readonly or readwrite. You can declare custom setters and getters or not.</p>
<p>If these concepts sound somewhat similar to Apple’s new property attributes in the Swift language, as it happens, they are. I’d written the code for this before hearing about Swift, and was very happy to see these sort of features in the Swift language (remember, Apple had been working on Swift for years, much longer than I’ve been working on LazyLoader). Lots of other people have come up with similar ideas as well; you can find examples on the internet.</p>
<h2 id="lazilyloadedproperties">Lazily Loaded Properties</h2>
<p>The most basic type of property supported is a <em>lazily loaded</em> property, which is a property that only computes its value when its value is requested. Lazily loaded properties compute their value in the getter method when the getter is called, cache the computed value in an ivar, and use an invalidation method to force a re-computation of their value. Although lazily loaded properties are usually somewhat CPU-intensive to compute, they need to perform their computation synchronously–you shouldn’t have lazily loaded properties initiate network requests to fetch their value.</p>
<p>Lazily Loaded properties have a concept of a valid/invalid state. When the property is in the valid state, LazyLoader has cached the current value of the property in its instance variable, and will return this value when the getter is called without calling the getter method. When the property is in the invalid state, the value in the ivar does not reflect the correct value, and LazyLoader will cause the proper value to be computed the next time the property’s value is requested. LazyLoader tracks valid/invalid states separately from the property itself; a pointer property can have a value of <code>NULL</code> while in the valid state.</p>
<p>All lazily loaded properties need to be declared in the classes’ <code>+initialize</code> method. You can use either the <code>syntheticProperty:</code> method or the <code>SyntheticProperty()</code> macro. Just like Observable, the major difference is that the macro performs compile-time checks to ensure the property is actually a property of the class. Here’s the code, for an example property named <code>fullName</code>:</p>
<pre><code class="C"> @property (strong) NSString *fullName;
...
// Method
[self syntheticProperty:@"fullName"];
// Macro
SyntheticProperty(fullName);
</code></pre>
<p>These calls will replace the getter method for the given property with a wrapper method that checks to see if the property is in a valid state, calls through to the original getter method if the property state isn’t valid, and returns a cached value if the property state is valid.</p>
<p>If the program state changes such that a Lazily Loaded property’s value is no longer correct, you can reflect this by invalidating the value. Invalidating marks the property invalid, meaning the value will get recomputed later. Again, there’s a method and a macro:</p>
<pre><code class="C"> // Method
[self invalidatePropertyValue:@"fullName"];
// Macro
InvalidatePropertyValue(fullName);
</code></pre>
<p>There’s also a convenience method to invalidate all the synthetic properties of an object at once:</p>
<pre><code class="C"> [self invalidateAllSyntheticProperties];
</code></pre>
<p>So far this code makes for a slight convenience, but isn’t terribly useful. Hand-rolling lazily loaded properties isn’t that difficult. However, this does make it easy to test your synthetic properties with and without lazy loading, simply by commenting out the <code>SyntheticProperty</code> call for that property. Without the <code>SyntheticProperty</code> call, your synthetic property will compute its value every time its getter is called.</p>
<h2 id="syntheticproperties">Synthetic Properties</h2>
<p>A Synthetic property has a list of key paths that the property depends on; that is, computing the value for the computed property uses data from the properties in the key paths. Synthetic properties are like lazily loaded properties in that they don’t compute their value until someone asks for it, but synthetic properties manage their own invalidation–they observe their list of key paths and mark themselves invalidated when any of the values they depend on change.</p>
<p>To declare a property to be a synthetic property, use code like the following, again in both method and macro form:</p>
<pre><code class="C"> // Method
[self syntheticProperty:@"fullName" dependsOnPaths:@[@"firstName", @lastName]];
// Macro
SyntheticProperty(fullName, firstName, lastName);
</code></pre>
<p>The <code>SyntheticProperty()</code> macro takes a variable number of arguments; the first argument is the property to be made synthetic, and the rest of the arguments are key paths (rooted at <code>self</code>) that the synthetic property uses to compute its value. If the value of the synthetic property can be completely determined by its dependent properties, there’s no need to manually invalidate it–it’ll automatically invalidate when any of its dependencies change.</p>
<p>You still can manually invalidate a synthetic property; use this if the property value is dependent on both other properties and some non-property value (in this example case, that could be a non-property setting that determines whether fullName should be formatted “First Last” or “Last, First”).</p>
<p>Internally, LazyLoader uses Observable to watch the dependent paths; this means that it performs path updating as values in the path change, and that it’s okay to declare a dependent path before the start point of the path has been assigned a value. Again, LazyLoader currently requires that all dependent paths be rooted at <code>self</code>, although the only reason for this is simplicity.</p>
<h2 id="collectionpropertiesandmutability:acasestudy">Collection Properties and Mutability: a Case Study</h2>
<p>If you have a mutable collection in your class and you want it exposed publicly so that others can access it but definitely do not want others to mutate it, you can create a private mutable collection and a public immutable collection, and write a custom getter that copies the internal collection to the external one.</p>
<pre><code class="C"> // In the .h file
@property NSDictionary *aDictionary;
// In the .m file
@property (strong) NSMutableDictionary *aMutableDictionary;
...
- (NSDictionary) aDictionary
{
return [aMutableDictionary copy];
}
</code></pre>
<p>However, the public property isn’t observable and it creates a new copy of aMutableDictionary every time the public dictionary is requested. Okay, so the creating a new copy thing isn’t really a performance issue. It isn’t.</p>
<p>Still, using LazyLoader we can easily improve on this:</p>
<pre><code class="C"> // In the .m file: change our mutable property's type to EBNObservableDictionary
@property (strong) EBNObservableDictionary *aMutableDictionary;
// In the +initialize method add this line
SyntheticProperty(aDictionary, aMutableDictionary.*);
// And, add a custom getter to link the two properties
- (NSDictionary *) aDictionary
{
return [aMutableDictionary copy];
}
</code></pre>
<p>And you’re done. The public aDictionary property is immutable, it will now be copied at most once per mutation performed on aMutableDictionary, and the public property is now properly observable–that is, observers of aDictionary will get called in response to aMutableDictionary being changed.</p>
<p>In fact, there’s a convenience method in EBNLazyLoader that makes this case even easier:</p>
<pre><code class="C"> // In your classes' +initialize method:
[self publicCollection:@"aDictionary" copiesFromPrivateCollection:@"aMutableDictionary"];
</code></pre>
<p>There it is. A one-liner that makes an observable public immutable collection that tracks the value of a private mutable collection.</p>
<h2 id="customloaders">Custom Loaders</h2>
<p>Classes that manage a set of values that are stored in a dictionary or dictionary-like-object but expose a bunch of properties as the API for retrieving the dictionary values are really very common. LazyLoader makes the creation of these sorts of classes easier by including support for custom loader methods.</p>
<p>When you declare a synthetic you can specify a selector to be a loader for that property. The loader method gets called when LazyLoader would otherwise call your getter method, but the loader method takes the name of the property that needs to be loaded:</p>
<pre><code class="C"> - (void) loader:(NSString *) propertyName
</code></pre>
<p>In this way, you can declare a single loader method for all your classes’ synthetic properties, and that method’s job is to set the ivar backing the given property to the correct value, usually by calling <code>setValue:forKey:</code>. This is much easier than having to write custom getters for each property or doing dynamic message resolution trickery.</p>
<h2 id="hybridproperties">Hybrid Properties</h2>
<p>Synthetic properties compute their value in their getter method, and therefore usually don’t have or need a setter method. With LazyLoader however, you can have properties that usually compute their value, but can also have their value overridden via the setter. No extra setup is required for this, just make sure your property is declared <code>readwrite</code>. Calling the setter will set the value as normal, and will mark the property as being valid. The property will keep the set value until the next time it is invalidated.</p>
<p>It is still unwise to call a property’s setter method from within its getter, as it is likely to lead to infinite recursion.</p>
<h2 id="observingsyntheticproperties">Observing Synthetic Properties</h2>
<p>A lazily loaded property that is being observed, and isn’t the last element in the observation’s key path, will effectively stop being lazily loaded because Observable needs to know the new value of the property immediately when it changes, in order to keep the observation on the key path up to date. Observable may need to set up observations on properties of the newly set object (and properties on that object, and so on) which forces the lazy loaded property to compute its value immediately.</p>
<p>This doesn’t mean that a property can’t be both synthetic and observed, just that observing sometimes needs to force immediate evaluation of the lazily loaded property.</p>
<h2 id="chainingsyntheticproperties">Chaining Synthetic Properties</h2>
<p>Take the example above where we have a <code>fullName</code> property that depends on the <code>firstName</code> and <code>lastName</code> properties. What if <code>fullName</code> were itself made into a dependency of another property?</p>
<pre><code class="C"> @property (strong) NSString *firstName;
@property (strong) NSString *lastName;
@property (strong) NSString *fullName;
@property (strong) NSString *zipCode;
@property (strong) NSString *city;
@property (strong) NSString *state;
@property (strong) NSString *street;
@property (strong) NSString *address;
...
SyntheticProperty(fullName, firstName, lastName);
SyntheticProperty(address, fullName, zipCode, city, state, street);
</code></pre>
<p>This works just fine. Changing the <code>firstName</code> property will cause the <code>fullName</code> property to be invalidated, as well as the <code>address</code> property. Manually invalidating the <code>fullName</code> property will also invalidate the <code>address</code> property.</p>
<h2 id="debugginglazyloaderproperties">Debugging LazyLoader Properties</h2>
<p>In the debugger, you can query which properties of a LazyLoader object are valid and invalid like this:</p>
<pre><code> (lldb) po [self debug_validProperties]
{(
fullName,
)}
(lldb) po [self debug_invalidProperties]
{(
address,
)}
</code></pre>
<p>You can also force all synthetic properties to be computed immediately (and therefore switch to the valid state) using <code>po [self debug_forceAllPropertiesValid]</code>. This makes all the instance variables that back your classes’ synthetic properties cache their currently valid value, meaning you can inspect them in the debugger and see the proper values for them.</p>
<h1 id="futurework">Future Work</h1>
<p>When working on this code base, be aware that there’s a fair number of unit tests implemented. Use them. This codebase is just the sort of thing that gains a lot from unit test support.</p>
<p>There’s lots of room to improve on this code. Here’s some good possibilities, in no particular order:</p>
<ul>
<li>Observable uses @synchronize in places where it needs thread-safety. This is very safe, as @synchronize handles unlocking in the case of exceptions being thrown, but it is quite slow compared to other available synchronization methods. As always, profile your code first, and only undertake this optimization if you find that @synchronize is actually slowing you down.</li>
<li>LazyLoader is designed to make it easy to enable and disable its functionality–in most cases, just commenting out one line of code will return a property to its non-synthetic state. This is the main reason I didn’t go with a model where you could declare a block that would compute the property’s value–the block would work nothing like the getter method and testing a property with and without lazy loading would become very difficult. However, this means that the point in the code where you declare a property synthetic is often far away from where its value is computed. There’s a couple of ways to remedy this; I’m interested in what people come up with.</li>
<li>The demonstration app is currently pretty weak; I didn’t even mention it in this documentation. Writing something that loads some data from a web service call, puts the data into a model object, and has views that observe the model object’s properties would be ideal.</li>
<li>The LazyLoader documentation concerning loader methods discusses classes that expose a property-based API but store their values in a dictionary, but the SDK doesn’t currently include one of these classes.</li>
<li>The current design is such that declaring an observation at the class level (probably in <code>+initialize</code>?) so that every object of that type would have that observation active could be a thing. It could have a performance advantage relative to setting up observations in <code>-init</code> if you were creating a large number of objects. In other words, write a new class method that says, “Every object of this class that gets created should have this here observation on it, right when it gets initialized.”</li>
<li>Better debugging: for the observations that operate on multiple key paths, having console logging that shows what change(s) caused the observer block to be scheduled would be useful.</li>
<li>More unit tests, as ever.</li>
</ul>
<h1 id="credits">Credits</h1>
<ul>
<li>Chall Fry - engineering <a href="mailto:[email protected]">[email protected]</a></li>
<li>Ben Yarger - QE, QA, unit test cases</li>
<li>Mark Yuan - Open Sourcing help</li>
</ul>
</body></html>