1 // Copyright 2012 the V8 project authors. All rights reserved.
2 // Use of this source code is governed by a BSD-style license that can be
3 // found in the LICENSE file.
9 // This file contains all of the routing and accounting for Object.observe.
10 // User code will interact with these mechanisms via the Object.observe APIs
11 // and, as a side effect of mutation objects which are observed. The V8 runtime
12 // (both C++ and JS) will interact with these mechanisms primarily by enqueuing
13 // proper change records for objects which were mutated. The Object.observe
14 // routing and accounting consists primarily of three participants
16 // 1) ObjectInfo. This represents the observed state of a given object. It
17 // records what callbacks are observing the object, with what options, and
18 // what "change types" are in progress on the object (i.e. via
19 // notifier.performChange).
21 // 2) CallbackInfo. This represents a callback used for observation. It holds
22 // the records which must be delivered to the callback, as well as the global
23 // priority of the callback (which determines delivery order between
26 // 3) observationState.pendingObservers. This is the set of observers which
27 // have change records which must be delivered. During "normal" delivery
28 // (i.e. not Object.deliverChangeRecords), this is the mechanism by which
29 // callbacks are invoked in the proper order until there are no more
30 // change records pending to a callback.
32 // Note that in order to reduce allocation and processing costs, the
33 // implementation of (1) and (2) have "optimized" states which represent
34 // common cases which can be handled more efficiently.
38 // We have to wait until after bootstrapping to grab a reference to the
39 // observationState object, since it's not possible to serialize that
40 // reference into the snapshot.
41 function GetObservationStateJS() {
42 if (IS_UNDEFINED(observationState)) {
43 observationState = %GetObservationState();
46 // TODO(adamk): Consider moving this code into heap.cc
47 if (IS_UNDEFINED(observationState.callbackInfoMap)) {
48 observationState.callbackInfoMap = %ObservationWeakMapCreate();
49 observationState.objectInfoMap = %ObservationWeakMapCreate();
50 observationState.notifierObjectInfoMap = %ObservationWeakMapCreate();
51 observationState.pendingObservers = null;
52 observationState.nextCallbackPriority = 0;
53 observationState.lastMicrotaskId = 0;
56 return observationState;
59 function GetPendingObservers() {
60 return GetObservationStateJS().pendingObservers;
63 function SetPendingObservers(pendingObservers) {
64 GetObservationStateJS().pendingObservers = pendingObservers;
67 function GetNextCallbackPriority() {
68 return GetObservationStateJS().nextCallbackPriority++;
71 function nullProtoObject() {
72 return { __proto__: null };
75 function TypeMapCreate() {
76 return nullProtoObject();
79 function TypeMapAddType(typeMap, type, ignoreDuplicate) {
80 typeMap[type] = ignoreDuplicate ? 1 : (typeMap[type] || 0) + 1;
83 function TypeMapRemoveType(typeMap, type) {
87 function TypeMapCreateFromList(typeList, length) {
88 var typeMap = TypeMapCreate();
89 for (var i = 0; i < length; i++) {
90 TypeMapAddType(typeMap, typeList[i], true);
95 function TypeMapHasType(typeMap, type) {
96 return !!typeMap[type];
99 function TypeMapIsDisjointFrom(typeMap1, typeMap2) {
100 if (!typeMap1 || !typeMap2)
103 for (var type in typeMap1) {
104 if (TypeMapHasType(typeMap1, type) && TypeMapHasType(typeMap2, type))
111 var defaultAcceptTypes = (function() {
120 return TypeMapCreateFromList(defaultTypes, defaultTypes.length);
123 // An Observer is a registration to observe an object by a callback with
124 // a given set of accept types. If the set of accept types is the default
125 // set for Object.observe, the observer is represented as a direct reference
126 // to the callback. An observer never changes its accept types and thus never
127 // needs to "normalize".
128 function ObserverCreate(callback, acceptList) {
129 if (IS_UNDEFINED(acceptList))
131 var observer = nullProtoObject();
132 observer.callback = callback;
133 observer.accept = acceptList;
137 function ObserverGetCallback(observer) {
138 return IS_SPEC_FUNCTION(observer) ? observer : observer.callback;
141 function ObserverGetAcceptTypes(observer) {
142 return IS_SPEC_FUNCTION(observer) ? defaultAcceptTypes : observer.accept;
145 function ObserverIsActive(observer, objectInfo) {
146 return TypeMapIsDisjointFrom(ObjectInfoGetPerformingTypes(objectInfo),
147 ObserverGetAcceptTypes(observer));
150 function ObjectInfoGetOrCreate(object) {
151 var objectInfo = ObjectInfoGet(object);
152 if (IS_UNDEFINED(objectInfo)) {
153 if (!%_IsJSProxy(object)) {
154 %SetIsObserved(object);
158 changeObservers: null,
163 %WeakCollectionSet(GetObservationStateJS().objectInfoMap,
169 function ObjectInfoGet(object) {
170 return %WeakCollectionGet(GetObservationStateJS().objectInfoMap, object);
173 function ObjectInfoGetFromNotifier(notifier) {
174 return %WeakCollectionGet(GetObservationStateJS().notifierObjectInfoMap,
178 function ObjectInfoGetNotifier(objectInfo) {
179 if (IS_NULL(objectInfo.notifier)) {
180 objectInfo.notifier = { __proto__: notifierPrototype };
181 %WeakCollectionSet(GetObservationStateJS().notifierObjectInfoMap,
182 objectInfo.notifier, objectInfo);
185 return objectInfo.notifier;
188 function ChangeObserversIsOptimized(changeObservers) {
189 return IS_SPEC_FUNCTION(changeObservers) ||
190 IS_SPEC_FUNCTION(changeObservers.callback);
193 // The set of observers on an object is called 'changeObservers'. The first
194 // observer is referenced directly via objectInfo.changeObservers. When a second
195 // is added, changeObservers "normalizes" to become a mapping of callback
196 // priority -> observer and is then stored on objectInfo.changeObservers.
197 function ObjectInfoNormalizeChangeObservers(objectInfo) {
198 if (ChangeObserversIsOptimized(objectInfo.changeObservers)) {
199 var observer = objectInfo.changeObservers;
200 var callback = ObserverGetCallback(observer);
201 var callbackInfo = CallbackInfoGet(callback);
202 var priority = CallbackInfoGetPriority(callbackInfo);
203 objectInfo.changeObservers = nullProtoObject();
204 objectInfo.changeObservers[priority] = observer;
208 function ObjectInfoAddObserver(objectInfo, callback, acceptList) {
209 var callbackInfo = CallbackInfoGetOrCreate(callback);
210 var observer = ObserverCreate(callback, acceptList);
212 if (!objectInfo.changeObservers) {
213 objectInfo.changeObservers = observer;
217 ObjectInfoNormalizeChangeObservers(objectInfo);
218 var priority = CallbackInfoGetPriority(callbackInfo);
219 objectInfo.changeObservers[priority] = observer;
222 function ObjectInfoRemoveObserver(objectInfo, callback) {
223 if (!objectInfo.changeObservers)
226 if (ChangeObserversIsOptimized(objectInfo.changeObservers)) {
227 if (callback === ObserverGetCallback(objectInfo.changeObservers))
228 objectInfo.changeObservers = null;
232 var callbackInfo = CallbackInfoGet(callback);
233 var priority = CallbackInfoGetPriority(callbackInfo);
234 objectInfo.changeObservers[priority] = null;
237 function ObjectInfoHasActiveObservers(objectInfo) {
238 if (IS_UNDEFINED(objectInfo) || !objectInfo.changeObservers)
241 if (ChangeObserversIsOptimized(objectInfo.changeObservers))
242 return ObserverIsActive(objectInfo.changeObservers, objectInfo);
244 for (var priority in objectInfo.changeObservers) {
245 var observer = objectInfo.changeObservers[priority];
246 if (!IS_NULL(observer) && ObserverIsActive(observer, objectInfo))
253 function ObjectInfoAddPerformingType(objectInfo, type) {
254 objectInfo.performing = objectInfo.performing || TypeMapCreate();
255 TypeMapAddType(objectInfo.performing, type);
256 objectInfo.performingCount++;
259 function ObjectInfoRemovePerformingType(objectInfo, type) {
260 objectInfo.performingCount--;
261 TypeMapRemoveType(objectInfo.performing, type);
264 function ObjectInfoGetPerformingTypes(objectInfo) {
265 return objectInfo.performingCount > 0 ? objectInfo.performing : null;
268 function ConvertAcceptListToTypeMap(arg) {
269 // We use undefined as a sentinel for the default accept list.
270 if (IS_UNDEFINED(arg))
273 if (!IS_SPEC_OBJECT(arg))
274 throw MakeTypeError("observe_accept_invalid");
276 var len = ToInteger(arg.length);
277 if (len < 0) len = 0;
279 return TypeMapCreateFromList(arg, len);
282 // CallbackInfo's optimized state is just a number which represents its global
283 // priority. When a change record must be enqueued for the callback, it
284 // normalizes. When delivery clears any pending change records, it re-optimizes.
285 function CallbackInfoGet(callback) {
286 return %WeakCollectionGet(GetObservationStateJS().callbackInfoMap, callback);
289 function CallbackInfoSet(callback, callbackInfo) {
290 %WeakCollectionSet(GetObservationStateJS().callbackInfoMap,
291 callback, callbackInfo);
294 function CallbackInfoGetOrCreate(callback) {
295 var callbackInfo = CallbackInfoGet(callback);
296 if (!IS_UNDEFINED(callbackInfo))
299 var priority = GetNextCallbackPriority();
300 CallbackInfoSet(callback, priority);
304 function CallbackInfoGetPriority(callbackInfo) {
305 if (IS_NUMBER(callbackInfo))
308 return callbackInfo.priority;
311 function CallbackInfoNormalize(callback) {
312 var callbackInfo = CallbackInfoGet(callback);
313 if (IS_NUMBER(callbackInfo)) {
314 var priority = callbackInfo;
315 callbackInfo = new InternalArray;
316 callbackInfo.priority = priority;
317 CallbackInfoSet(callback, callbackInfo);
322 function ObjectObserve(object, callback, acceptList) {
323 if (!IS_SPEC_OBJECT(object))
324 throw MakeTypeError("observe_non_object", ["observe"]);
325 if (%IsJSGlobalProxy(object))
326 throw MakeTypeError("observe_global_proxy", ["observe"]);
327 if (!IS_SPEC_FUNCTION(callback))
328 throw MakeTypeError("observe_non_function", ["observe"]);
329 if (ObjectIsFrozen(callback))
330 throw MakeTypeError("observe_callback_frozen");
332 var objectObserveFn = %GetObjectContextObjectObserve(object);
333 return objectObserveFn(object, callback, acceptList);
336 function NativeObjectObserve(object, callback, acceptList) {
337 var objectInfo = ObjectInfoGetOrCreate(object);
338 var typeList = ConvertAcceptListToTypeMap(acceptList);
339 ObjectInfoAddObserver(objectInfo, callback, typeList);
343 function ObjectUnobserve(object, callback) {
344 if (!IS_SPEC_OBJECT(object))
345 throw MakeTypeError("observe_non_object", ["unobserve"]);
346 if (%IsJSGlobalProxy(object))
347 throw MakeTypeError("observe_global_proxy", ["unobserve"]);
348 if (!IS_SPEC_FUNCTION(callback))
349 throw MakeTypeError("observe_non_function", ["unobserve"]);
351 var objectInfo = ObjectInfoGet(object);
352 if (IS_UNDEFINED(objectInfo))
355 ObjectInfoRemoveObserver(objectInfo, callback);
359 function ArrayObserve(object, callback) {
360 return ObjectObserve(object, callback, ['add',
366 function ArrayUnobserve(object, callback) {
367 return ObjectUnobserve(object, callback);
370 function ObserverEnqueueIfActive(observer, objectInfo, changeRecord) {
371 if (!ObserverIsActive(observer, objectInfo) ||
372 !TypeMapHasType(ObserverGetAcceptTypes(observer), changeRecord.type)) {
376 var callback = ObserverGetCallback(observer);
377 if (!%ObserverObjectAndRecordHaveSameOrigin(callback, changeRecord.object,
382 var callbackInfo = CallbackInfoNormalize(callback);
383 if (IS_NULL(GetPendingObservers())) {
384 SetPendingObservers(nullProtoObject());
385 if (DEBUG_IS_ACTIVE) {
386 var id = ++GetObservationStateJS().lastMicrotaskId;
387 var name = "Object.observe";
388 %EnqueueMicrotask(function() {
389 %DebugAsyncTaskEvent({ type: "willHandle", id: id, name: name });
390 ObserveMicrotaskRunner();
391 %DebugAsyncTaskEvent({ type: "didHandle", id: id, name: name });
393 %DebugAsyncTaskEvent({ type: "enqueue", id: id, name: name });
395 %EnqueueMicrotask(ObserveMicrotaskRunner);
398 GetPendingObservers()[callbackInfo.priority] = callback;
399 callbackInfo.push(changeRecord);
402 function ObjectInfoEnqueueExternalChangeRecord(objectInfo, changeRecord, type) {
403 if (!ObjectInfoHasActiveObservers(objectInfo))
406 var hasType = !IS_UNDEFINED(type);
407 var newRecord = hasType ?
408 { object: objectInfo.object, type: type } :
409 { object: objectInfo.object };
411 for (var prop in changeRecord) {
412 if (prop === 'object' || (hasType && prop === 'type')) continue;
413 %DefineDataPropertyUnchecked(
414 newRecord, prop, changeRecord[prop], READ_ONLY + DONT_DELETE);
416 ObjectFreezeJS(newRecord);
418 ObjectInfoEnqueueInternalChangeRecord(objectInfo, newRecord);
421 function ObjectInfoEnqueueInternalChangeRecord(objectInfo, changeRecord) {
422 // TODO(rossberg): adjust once there is a story for symbols vs proxies.
423 if (IS_SYMBOL(changeRecord.name)) return;
425 if (ChangeObserversIsOptimized(objectInfo.changeObservers)) {
426 var observer = objectInfo.changeObservers;
427 ObserverEnqueueIfActive(observer, objectInfo, changeRecord);
431 for (var priority in objectInfo.changeObservers) {
432 var observer = objectInfo.changeObservers[priority];
433 if (IS_NULL(observer))
435 ObserverEnqueueIfActive(observer, objectInfo, changeRecord);
439 function BeginPerformSplice(array) {
440 var objectInfo = ObjectInfoGet(array);
441 if (!IS_UNDEFINED(objectInfo))
442 ObjectInfoAddPerformingType(objectInfo, 'splice');
445 function EndPerformSplice(array) {
446 var objectInfo = ObjectInfoGet(array);
447 if (!IS_UNDEFINED(objectInfo))
448 ObjectInfoRemovePerformingType(objectInfo, 'splice');
451 function EnqueueSpliceRecord(array, index, removed, addedCount) {
452 var objectInfo = ObjectInfoGet(array);
453 if (!ObjectInfoHasActiveObservers(objectInfo))
461 addedCount: addedCount
464 ObjectFreezeJS(changeRecord);
465 ObjectFreezeJS(changeRecord.removed);
466 ObjectInfoEnqueueInternalChangeRecord(objectInfo, changeRecord);
469 function NotifyChange(type, object, name, oldValue) {
470 var objectInfo = ObjectInfoGet(object);
471 if (!ObjectInfoHasActiveObservers(objectInfo))
475 if (arguments.length == 2) {
476 changeRecord = { type: type, object: object };
477 } else if (arguments.length == 3) {
478 changeRecord = { type: type, object: object, name: name };
488 ObjectFreezeJS(changeRecord);
489 ObjectInfoEnqueueInternalChangeRecord(objectInfo, changeRecord);
492 var notifierPrototype = {};
494 function ObjectNotifierNotify(changeRecord) {
495 if (!IS_SPEC_OBJECT(this))
496 throw MakeTypeError("called_on_non_object", ["notify"]);
498 var objectInfo = ObjectInfoGetFromNotifier(this);
499 if (IS_UNDEFINED(objectInfo))
500 throw MakeTypeError("observe_notify_non_notifier");
501 if (!IS_STRING(changeRecord.type))
502 throw MakeTypeError("observe_type_non_string");
504 ObjectInfoEnqueueExternalChangeRecord(objectInfo, changeRecord);
507 function ObjectNotifierPerformChange(changeType, changeFn) {
508 if (!IS_SPEC_OBJECT(this))
509 throw MakeTypeError("called_on_non_object", ["performChange"]);
511 var objectInfo = ObjectInfoGetFromNotifier(this);
512 if (IS_UNDEFINED(objectInfo))
513 throw MakeTypeError("observe_notify_non_notifier");
514 if (!IS_STRING(changeType))
515 throw MakeTypeError("observe_perform_non_string");
516 if (!IS_SPEC_FUNCTION(changeFn))
517 throw MakeTypeError("observe_perform_non_function");
519 var performChangeFn = %GetObjectContextNotifierPerformChange(objectInfo);
520 performChangeFn(objectInfo, changeType, changeFn);
523 function NativeObjectNotifierPerformChange(objectInfo, changeType, changeFn) {
524 ObjectInfoAddPerformingType(objectInfo, changeType);
528 changeRecord = %_CallFunction(UNDEFINED, changeFn);
530 ObjectInfoRemovePerformingType(objectInfo, changeType);
533 if (IS_SPEC_OBJECT(changeRecord))
534 ObjectInfoEnqueueExternalChangeRecord(objectInfo, changeRecord, changeType);
537 function ObjectGetNotifier(object) {
538 if (!IS_SPEC_OBJECT(object))
539 throw MakeTypeError("observe_non_object", ["getNotifier"]);
540 if (%IsJSGlobalProxy(object))
541 throw MakeTypeError("observe_global_proxy", ["getNotifier"]);
543 if (ObjectIsFrozen(object)) return null;
545 if (!%ObjectWasCreatedInCurrentOrigin(object)) return null;
547 var getNotifierFn = %GetObjectContextObjectGetNotifier(object);
548 return getNotifierFn(object);
551 function NativeObjectGetNotifier(object) {
552 var objectInfo = ObjectInfoGetOrCreate(object);
553 return ObjectInfoGetNotifier(objectInfo);
556 function CallbackDeliverPending(callback) {
557 var callbackInfo = CallbackInfoGet(callback);
558 if (IS_UNDEFINED(callbackInfo) || IS_NUMBER(callbackInfo))
561 // Clear the pending change records from callback and return it to its
562 // "optimized" state.
563 var priority = callbackInfo.priority;
564 CallbackInfoSet(callback, priority);
566 var pendingObservers = GetPendingObservers();
567 if (!IS_NULL(pendingObservers))
568 delete pendingObservers[priority];
570 // TODO: combine the following runtime calls for perf optimization.
572 %MoveArrayContents(callbackInfo, delivered);
573 %DeliverObservationChangeRecords(callback, delivered);
578 function ObjectDeliverChangeRecords(callback) {
579 if (!IS_SPEC_FUNCTION(callback))
580 throw MakeTypeError("observe_non_function", ["deliverChangeRecords"]);
582 while (CallbackDeliverPending(callback)) {}
585 function ObserveMicrotaskRunner() {
586 var pendingObservers = GetPendingObservers();
587 if (!IS_NULL(pendingObservers)) {
588 SetPendingObservers(null);
589 for (var i in pendingObservers) {
590 CallbackDeliverPending(pendingObservers[i]);
595 function SetupObjectObserve() {
596 %CheckIsBootstrapping();
597 InstallFunctions($Object, DONT_ENUM, $Array(
598 "deliverChangeRecords", ObjectDeliverChangeRecords,
599 "getNotifier", ObjectGetNotifier,
600 "observe", ObjectObserve,
601 "unobserve", ObjectUnobserve
603 InstallFunctions($Array, DONT_ENUM, $Array(
604 "observe", ArrayObserve,
605 "unobserve", ArrayUnobserve
607 InstallFunctions(notifierPrototype, DONT_ENUM, $Array(
608 "notify", ObjectNotifierNotify,
609 "performChange", ObjectNotifierPerformChange
613 SetupObjectObserve();