ImageDisposeBugWorkaround enum

In Flutter version 3.10.4 (June 2023), an inconfirmed report of a new Flutter bug related to dispose() and image handling was reported -- see https://github.com/zathras/jovial_svg/issues/62. silentlyIgnoreErrors was added at this time.

As of Flutter 2.5, other usese of this enum became obsolete. It is maintained for backwards compatibility with earlier versions.

As of the initial date of publication of this library, there were several bugs in the then-current shipped version of Flutter (2.2.2) involving the dispose() method of ImageDescriptor and ImmutableImageBuffer. The only safe thing to do with this version of Flutter was to refrain from calling dispose() on these objects. This is non-optimal, since it is a potential memory leak. Even if a future version of Flutter correctly uses finalization to eventually dispose of the native memory backing these objects, large amounts of native memory might be retained for a significant amount of time, until the Dart objects are eventually reclaimed and finalized.

For this reason, a setting to call dispose() on one or both of these objects was exposed. That way, an application can cause dispose() to be called when the Flutter libraries are fixed, even if jovial_svg is not updated to follow the Flutter releases. In addition, jovial_svg should be conservative about following the latest Flutter releases too closely, as regards the default behavior.

Further, it was not documented if client code was supposed to call ImmutableImageBuffer.dispose() after handing the buffer off to ImageDescriptor. The most reasonable answer is "yes" - typically, one uses reference counting internally for this sort of thing - but given the instability of this area of Flutter, counting on the eventual specification going either way would have been risky. For this reason, we separate out the two dispose() calls in the global setting.

See also ScalableImage.imageDisposeBugWorkaround, where clients of this library can change the behavior.

Relevant bugs on Flutter include:

Note that these may have been fixed by https://github.com/flutter/engine/pull/26435, but as of the date of this library's initial publication, that had not yet been released. As of Flutter 2.5, it has been.

Inheritance

Constructors

ImageDisposeBugWorkaround()
const

Values

disposeImageDescriptor → const ImageDisposeBugWorkaround

Only dispose image descriptors. This value is believed to be obsolete.

disposeImmutableBuffer → const ImageDisposeBugWorkaround

Only dispose the immutable image buffer. This value is believed to be obsolete.

disposeNeither → const ImageDisposeBugWorkaround

Dispose neither the image buffer nor the immutable buffer. This value is believed to be obsolete.

disposeBoth → const ImageDisposeBugWorkaround

Dispose of everything normally.

silentlyIgnoreErrors → const ImageDisposeBugWorkaround

Dispose of everything normally, but do not print a warning if a bug in an image-related dispose() bug is detected (e.g. by catching an exception).

Properties

hashCode → int
The hash code for this object.
no setterinherited
index → int
A numeric identifier for the enumerated value.
no setterinherited
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited

Methods

noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
toString() → String
A string representation of this object.
inherited

Operators

operator ==(Object other) → bool
The equality operator.
inherited

Constants

values → const List<ImageDisposeBugWorkaround>
A constant List of the values in this enum, in order of their declaration.