|
| 1 | +// Copyright 2013 The Flutter 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. |
| 4 | + |
| 5 | +import 'dart:js_interop'; |
| 6 | +import 'package:meta/meta.dart'; |
| 7 | + |
| 8 | +import '../../engine.dart' show Instrumentation; |
| 9 | +import '../util.dart'; |
| 10 | +import 'canvaskit_api.dart'; |
| 11 | + |
| 12 | +/// Collects native objects that weren't explicitly disposed of using |
| 13 | +/// [UniqueRef.dispose] or [CountedRef.unref]. |
| 14 | +SkObjectFinalizationRegistry _finalizationRegistry = createSkObjectFinalizationRegistry( |
| 15 | + (UniqueRef<Object> uniq) { |
| 16 | + uniq.collect(); |
| 17 | + }.toJS |
| 18 | +); |
| 19 | + |
| 20 | +NativeMemoryFinalizationRegistry nativeMemoryFinalizationRegistry = NativeMemoryFinalizationRegistry(); |
| 21 | + |
| 22 | +/// An indirection to [SkObjectFinalizationRegistry] to enable tests provide a |
| 23 | +/// mock implementation of a finalization registry. |
| 24 | +class NativeMemoryFinalizationRegistry { |
| 25 | + void register(Object owner, UniqueRef<Object> ref) { |
| 26 | + if (browserSupportsFinalizationRegistry) { |
| 27 | + _finalizationRegistry.register(owner, ref); |
| 28 | + } |
| 29 | + } |
| 30 | +} |
| 31 | + |
| 32 | +/// Manages the lifecycle of a C++ object referenced by a single Dart object. |
| 33 | +/// |
| 34 | +/// It is expected that when the C++ object is no longer needed [dispose] is |
| 35 | +/// called. |
| 36 | +/// |
| 37 | +/// To prevent memory leaks, the underlying C++ object is deleted by the GC if |
| 38 | +/// it wasn't previously disposed of explicitly. |
| 39 | +class UniqueRef<T extends Object> { |
| 40 | + UniqueRef(Object owner, T nativeObject, this._debugOwnerLabel) { |
| 41 | + _nativeObject = nativeObject; |
| 42 | + if (Instrumentation.enabled) { |
| 43 | + Instrumentation.instance.incrementCounter('$_debugOwnerLabel Created'); |
| 44 | + } |
| 45 | + nativeMemoryFinalizationRegistry.register(owner, this); |
| 46 | + } |
| 47 | + |
| 48 | + T? _nativeObject; |
| 49 | + final String _debugOwnerLabel; |
| 50 | + |
| 51 | + /// Returns the underlying native object reference, if it has not been |
| 52 | + /// disposed of yet. |
| 53 | + /// |
| 54 | + /// The returned reference must not be stored. I should only be borrowed |
| 55 | + /// temporarily. Storing this reference may result in dangling pointer errors. |
| 56 | + T get nativeObject { |
| 57 | + assert(!isDisposed, 'Native object was disposed.'); |
| 58 | + return _nativeObject!; |
| 59 | + } |
| 60 | + |
| 61 | + /// Returns whether the underlying native object has been disposed and |
| 62 | + /// therefore can no longer be used. |
| 63 | + bool get isDisposed => _nativeObject == null; |
| 64 | + |
| 65 | + /// Disposes the underlying native object. |
| 66 | + /// |
| 67 | + /// The underlying object may be deleted or its ref count may be bumped down. |
| 68 | + /// The exact action taken depends on the sharing model of that particular |
| 69 | + /// object. For example, an [SkImage] may not be immediately deleted if a |
| 70 | + /// [SkPicture] exists that still references it. On the other hand, [SkPaint] |
| 71 | + /// is deleted eagerly. |
| 72 | + void dispose() { |
| 73 | + assert(!isDisposed, 'A native object reference cannot be disposed more than once.'); |
| 74 | + if (Instrumentation.enabled) { |
| 75 | + Instrumentation.instance.incrementCounter('$_debugOwnerLabel Deleted'); |
| 76 | + } |
| 77 | + final SkDeletable object = nativeObject as SkDeletable; |
| 78 | + if (!object.isDeleted()) { |
| 79 | + object.delete(); |
| 80 | + } |
| 81 | + _nativeObject = null; |
| 82 | + } |
| 83 | + |
| 84 | + /// Called by the garbage [Collector] when the owner of this handle is |
| 85 | + /// collected. |
| 86 | + /// |
| 87 | + /// Garbage collection is used as a back-up for the cases when the handle |
| 88 | + /// isn't disposed of explicitly by calling [dispose]. It most likely |
| 89 | + /// indicates a memory leak or inefficiency in the framework or application |
| 90 | + /// code. |
| 91 | + @visibleForTesting |
| 92 | + void collect() { |
| 93 | + if (!isDisposed) { |
| 94 | + if (Instrumentation.enabled) { |
| 95 | + Instrumentation.instance.incrementCounter('$_debugOwnerLabel Leaked'); |
| 96 | + } |
| 97 | + dispose(); |
| 98 | + } |
| 99 | + } |
| 100 | +} |
| 101 | + |
| 102 | +/// Interface that classes wrapping [UniqueRef] must implement. |
| 103 | +/// |
| 104 | +/// Used to collect stack traces in debug mode. |
| 105 | +abstract class StackTraceDebugger { |
| 106 | + /// The stack trace pointing to code location that created or upreffed a |
| 107 | + /// [CountedRef]. |
| 108 | + StackTrace get debugStackTrace; |
| 109 | +} |
| 110 | + |
| 111 | +/// Manages the lifecycle of a C++ object referenced by multiple Dart objects. |
| 112 | +/// |
| 113 | +/// Uses reference counting to manage the lifecycle of the C++ object. |
| 114 | +/// |
| 115 | +/// If the C++ object has a unique owner, use [UniqueRef] instead. |
| 116 | +/// |
| 117 | +/// The [ref] method can be used to increment the refcount to tell this box to |
| 118 | +/// keep the underlying C++ object alive. |
| 119 | +/// |
| 120 | +/// The [unref] method can be used to decrement the refcount indicating that a |
| 121 | +/// referring object no longer needs it. When the refcount drops to zero the |
| 122 | +/// underlying C++ object is deleted. |
| 123 | +/// |
| 124 | +/// In addition to ref counting, this object is also managed by GC. When this |
| 125 | +/// reference is garbage collected, the underlying C++ object is automatically |
| 126 | +/// deleted. This is mostly done to prevent memory leaks in production. Well |
| 127 | +/// behaving framework and app code are expected to rely on [ref] and [unref] |
| 128 | +/// for timely collection of resources. |
| 129 | +class CountedRef<R extends StackTraceDebugger, T extends Object> { |
| 130 | + /// Creates a counted reference. |
| 131 | + CountedRef(T nativeObject, R debugReferrer, String debugLabel) { |
| 132 | + _ref = UniqueRef<T>(this, nativeObject, debugLabel); |
| 133 | + if (assertionsEnabled) { |
| 134 | + debugReferrers.add(debugReferrer); |
| 135 | + } |
| 136 | + assert(refCount == debugReferrers.length); |
| 137 | + } |
| 138 | + |
| 139 | + /// The native object reference whose lifecycle is being managed by this ref |
| 140 | + /// count. |
| 141 | + /// |
| 142 | + /// Do not store this value outside this class. |
| 143 | + late final UniqueRef<T> _ref; |
| 144 | + |
| 145 | + /// Returns the underlying native object reference, if it has not been |
| 146 | + /// disposed of yet. |
| 147 | + /// |
| 148 | + /// The returned reference must not be stored. I should only be borrowed |
| 149 | + /// temporarily. Storing this reference may result in dangling pointer errors. |
| 150 | + T get nativeObject => _ref.nativeObject; |
| 151 | + |
| 152 | + /// The number of objects sharing references to this box. |
| 153 | + /// |
| 154 | + /// When this count reaches zero, the underlying [nativeObject] is scheduled |
| 155 | + /// for deletion. |
| 156 | + int get refCount => _refCount; |
| 157 | + int _refCount = 1; |
| 158 | + |
| 159 | + /// Whether the underlying [nativeObject] has been disposed and is no longer |
| 160 | + /// accessible. |
| 161 | + bool get isDisposed => _ref.isDisposed; |
| 162 | + |
| 163 | + /// When assertions are enabled, stores all objects that share this box. |
| 164 | + /// |
| 165 | + /// The length of this list is always identical to [refCount]. |
| 166 | + /// |
| 167 | + /// This list can be used for debugging ref counting issues. |
| 168 | + final Set<R> debugReferrers = <R>{}; |
| 169 | + |
| 170 | + /// If asserts are enabled, the [StackTrace]s representing when a reference |
| 171 | + /// was created. |
| 172 | + List<StackTrace> debugGetStackTraces() { |
| 173 | + if (assertionsEnabled) { |
| 174 | + return debugReferrers |
| 175 | + .map<StackTrace>((R referrer) => referrer.debugStackTrace) |
| 176 | + .toList(); |
| 177 | + } |
| 178 | + throw UnsupportedError(''); |
| 179 | + } |
| 180 | + |
| 181 | + /// Increases the reference count of this box because a new object began |
| 182 | + /// sharing ownership of the underlying [nativeObject]. |
| 183 | + void ref(R debugReferrer) { |
| 184 | + assert( |
| 185 | + !_ref.isDisposed, |
| 186 | + 'Cannot increment ref count on a deleted handle.', |
| 187 | + ); |
| 188 | + assert(_refCount > 0); |
| 189 | + assert( |
| 190 | + debugReferrers.add(debugReferrer), |
| 191 | + 'Attempted to increment ref count by the same referrer more than once.', |
| 192 | + ); |
| 193 | + _refCount += 1; |
| 194 | + assert(refCount == debugReferrers.length); |
| 195 | + } |
| 196 | + |
| 197 | + /// Decrements the reference count for the [nativeObject]. |
| 198 | + /// |
| 199 | + /// Does nothing if the object has already been deleted. |
| 200 | + /// |
| 201 | + /// If this causes the reference count to drop to zero, deletes the |
| 202 | + /// [nativeObject]. |
| 203 | + void unref(R debugReferrer) { |
| 204 | + assert( |
| 205 | + !_ref.isDisposed, |
| 206 | + 'Attempted to unref an already deleted native object.', |
| 207 | + ); |
| 208 | + assert( |
| 209 | + debugReferrers.remove(debugReferrer), |
| 210 | + 'Attempted to decrement ref count by the same referrer more than once.', |
| 211 | + ); |
| 212 | + _refCount -= 1; |
| 213 | + assert(refCount == debugReferrers.length); |
| 214 | + if (_refCount == 0) { |
| 215 | + _ref.dispose(); |
| 216 | + } |
| 217 | + } |
| 218 | +} |
0 commit comments