Minor improvements & bug fixes

Author: JaffaKetchup

lib/src/layer/tile_layer/tile_provider/network/caching/built_in/built_in_caching_provider.dart

@@ -19,53 +19,64 @@ import 'package:flutter_map/src/layer/tile_layer/tile_provider/network/caching/b
 /// For more information, see the online documentation.
 abstract interface class BuiltInMapCachingProvider
     implements MapCachingProvider {
-  /// if a singleton instance exists, return it, otherwise create a new
-  /// singleton instance (and start asynchronously initialising it)
+  /// If an instance exists, return it, otherwise create a new instance
   ///
-  /// If an instance already exists, the provided configuration will be ignored.
+  /// The provided configuration will only be respected if an instance does not
+  /// already exist.
   ///
   /// See individual properties for more information about configuration.
   factory BuiltInMapCachingProvider.getOrCreateInstance({
-    /// Path to the caching directory to use
+    /// Path to the directory to use to store cached tiles & other related files
     ///
-    /// This must be accessible to the program.
+    /// The provider actually uses the 'fm_cache' directory created as a child
+    /// of the path specified here.
+    ///
+    /// The program must have rights/permissions to access the path.
+    ///
+    /// The path does not have to exist, it will be recursively created if
+    /// missing.
+    ///
+    /// All files and directories within the path will be liable to deletion by
+    /// the size reducer.
     ///
     /// Defaults to a platform provided cache directory, which may be cleared by
     /// the OS at any time.
     String? cacheDirectory,
 
-    /// Preferred maximum size (in bytes) of the cache
+    /// Maximum total size of cached tiles, in bytes
     ///
-    /// This is applied when the internal caching mechanism is created (on the
-    /// first tile load in the main memory space for the app). It is not an
-    /// absolute limit.
+    /// This is applied only when the instance is created, by running the size
+    /// reducer. This runs in the background (and so does not delay reads or
+    /// writes). The cache size may exceed this limit while the program is
+    /// running.
+    ///
+    /// Disabling the size limit may improve write performance.
     ///
     /// Defaults to 1 GB. Set to `null` to disable.
     int? maxCacheSize = 1_000_000_000,
 
-    /// Override the duration of time a tile is considered fresh for
+    /// Function to convert a tile's URL to a key used to uniquely identify the
+    /// tile
     ///
-    /// Defaults to `null`: use duration calculated from each tile's HTTP
-    /// headers.
-    Duration? overrideFreshAge,
-
-    /// Function to convert a tile URL to a key used in the cache
+    /// Where parts of the URL are volatile or do not represent the tile's
+    /// contents/image - for example, API keys contained with the query
+    /// parameters - this should be modified to remove the volatile portions.
     ///
-    /// This may be useful where parts of the URL are volatile or do not
-    /// represent the tile image, for example, API keys contained with the query
-    /// parameters.
-    ///
-    /// The resulting key should be unique to that tile URL. Keys must be usable
-    /// as filenames on all intended platform filesystems.
+    /// Keys must be usable as filenames on all intended platform filesystems.
+    /// The callback should not throw.
     ///
     /// Defaults to generating a UUID from the entire URL string.
+    String Function(String url)? tileKeyGenerator,
+
+    /// Override the duration of time a tile is considered fresh for
     ///
-    /// The callback should not throw.
-    String Function(String url)? cacheKeyGenerator,
+    /// Defaults to `null`: use duration calculated from each tile's HTTP
+    /// headers.
+    Duration? overrideFreshAge,
 
     /// Prevent any tiles from being added or updated
     ///
-    /// Does not disable the size limiter if the cache size is larger than
+    /// Does not disable the size reducer if the cache size is larger than
     /// `maxCacheSize`.
     ///
     /// Defaults to `false`.
@@ -83,7 +94,7 @@ abstract interface class BuiltInMapCachingProvider
       cacheDirectory: cacheDirectory,
       maxCacheSize: maxCacheSize,
       overrideFreshAge: overrideFreshAge,
-      cacheKeyGenerator: cacheKeyGenerator,
+      tileKeyGenerator: tileKeyGenerator,
       readOnly: readOnly,
     );
   }

lib/src/layer/tile_layer/tile_provider/network/caching/built_in/impl/native/native.dart

@@ -20,31 +20,29 @@ class BuiltInMapCachingProviderImpl implements BuiltInMapCachingProvider {
 
   final String? cacheDirectory;
   final int? maxCacheSize;
+  final String Function(String url)? tileKeyGenerator;
   final Duration? overrideFreshAge;
-  final String Function(String url)? cacheKeyGenerator;
   final bool readOnly;
 
   @internal
   BuiltInMapCachingProviderImpl.createAndInitialise({
     required this.cacheDirectory,
     required this.maxCacheSize,
     required this.overrideFreshAge,
-    required this.cacheKeyGenerator,
+    required this.tileKeyGenerator,
     required this.readOnly,
   }) {
     // This should only be called/constructed once
     () async {
-      if (cacheKeyGenerator == null) {
+      if (tileKeyGenerator == null) {
         _uuid = Uuid(goptions: GlobalOptions(MathRNG()));
       }
 
       final cacheDirectoryPath = p.join(
-        this.cacheDirectory ??
-            (await getApplicationCacheDirectory()).absolute.path,
+        cacheDirectory ?? (await getApplicationCacheDirectory()).absolute.path,
         'fm_cache',
       );
-      final cacheDirectory = Directory(cacheDirectoryPath);
-      await cacheDirectory.create(recursive: true);
+      await Directory(cacheDirectoryPath).create(recursive: true);
 
       final sizeMonitorFilePath =
           p.join(cacheDirectoryPath, sizeMonitorFileName);
@@ -59,16 +57,13 @@ class BuiltInMapCachingProviderImpl implements BuiltInMapCachingProvider {
       // monitoring (and potentially run the reducer) if necessary
       // Reading does not depend on this.
       void sendMessageToWriter(Object message) {
-        if (writerPort != null) {
-          writerPort.send(message);
-        } else {
-          writerPortReady.future.then((port) => port.send(message));
-        }
+        if (writerPort != null) return writerPort.send(message);
+        writerPortReady.future.then((port) => port.send(message));
       }
 
-      _writeTileFile = ({required path, required metadata, tileBytes}) =>
-          sendMessageToWriter(
-              (path: path, metadata: metadata, tileBytes: tileBytes));
+      _writeTileFile = (path, metadata, tileBytes) => sendMessageToWriter(
+            (path: path, metadata: metadata, tileBytes: tileBytes),
+          );
       _reportReadFailure = () => sendMessageToWriter(false);
 
       final writerReceivePort = ReceivePort();
@@ -78,7 +73,7 @@ class BuiltInMapCachingProviderImpl implements BuiltInMapCachingProvider {
           port: writerReceivePort.sendPort,
           cacheDirectoryPath: cacheDirectoryPath,
           sizeMonitorFilePath: sizeMonitorFilePath,
-          sizeLimit: maxCacheSize,
+          maxCacheSize: maxCacheSize,
         ),
         debugName: '[flutter_map: cache] Tile & Size Monitor Writer',
       );
@@ -93,14 +88,14 @@ class BuiltInMapCachingProviderImpl implements BuiltInMapCachingProvider {
 
   late final Uuid _uuid; // left un-inited if provided generator
 
-  late final void Function({
-    required String path,
-    required CachedMapTileMetadata metadata,
+  late final void Function(
+    String path,
+    CachedMapTileMetadata metadata,
     Uint8List? tileBytes,
-  }) _writeTileFile;
+  ) _writeTileFile;
 
-  /// See `disableSizeMonitor` in worker
-  late final void Function() _reportReadFailure;
+  late final void Function()
+      _reportReadFailure; // See `disableSizeMonitor` in worker
 
   @override
   bool get isSupported => true;
@@ -110,7 +105,7 @@ class BuiltInMapCachingProviderImpl implements BuiltInMapCachingProvider {
     String url,
   ) async {
     final key =
-        cacheKeyGenerator?.call(url) ?? _uuid.v5(Namespace.url.value, url);
+        tileKeyGenerator?.call(url) ?? _uuid.v5(Namespace.url.value, url);
     final tileFile = File(
       p.join(_cacheDirectoryPath ?? await _cacheDirectoryPathReady.future, key),
     );
@@ -121,7 +116,7 @@ class BuiltInMapCachingProviderImpl implements BuiltInMapCachingProvider {
       final bytes = await tileFile.readAsBytes();
 
       if (bytes.lengthInBytes < 22) {
-        throw CachedMapTileReadFailureException(
+        throw CachedMapTileReadFailure(
           url: url,
           description:
               'cache file (${bytes.lengthInBytes}) was shorter than the '
@@ -145,14 +140,13 @@ class BuiltInMapCachingProviderImpl implements BuiltInMapCachingProvider {
         etag = const AsciiDecoder().convert(etagBytes);
       }
 
-      // Performing an unaligned read is a hassle
-      final tileBytesExpectedLength =
+      final tileBytesExpectedLength = // Perform an unaligned read
           bytes.buffer.asByteData(18 + etagLength, 4).getUint32(0, Endian.host);
 
       final tileBytes = Uint8List.sublistView(bytes, 18 + etagLength + 4);
 
       if (tileBytes.lengthInBytes != tileBytesExpectedLength) {
-        throw CachedMapTileReadFailureException(
+        throw CachedMapTileReadFailure(
           url: url,
           description:
               'tile image bytes (${tileBytes.lengthInBytes}) were not of '
@@ -168,13 +162,13 @@ class BuiltInMapCachingProviderImpl implements BuiltInMapCachingProvider {
         ),
         bytes: tileBytes,
       );
-    } on CachedMapTileReadFailureException {
+    } on CachedMapTileReadFailure {
       _reportReadFailure();
       rethrow;
     } catch (error, stackTrace) {
       _reportReadFailure();
       Error.throwWithStackTrace(
-        CachedMapTileReadFailureException(url: url, originalError: error),
+        CachedMapTileReadFailure(url: url, originalError: error),
         stackTrace,
       );
     }
@@ -189,20 +183,22 @@ class BuiltInMapCachingProviderImpl implements BuiltInMapCachingProvider {
     if (readOnly) return;
 
     final key =
-        cacheKeyGenerator?.call(url) ?? _uuid.v5(Namespace.url.value, url);
+        tileKeyGenerator?.call(url) ?? _uuid.v5(Namespace.url.value, url);
     final path = p.join(
       _cacheDirectoryPath ?? await _cacheDirectoryPathReady.future,
       key,
     );
 
-    final resolvedMetadata = overrideFreshAge != null
-        ? CachedMapTileMetadata(
-            staleAt: DateTime.timestamp().add(overrideFreshAge!),
-            lastModified: metadata.lastModified,
-            etag: metadata.etag,
-          )
-        : metadata;
-
-    _writeTileFile(path: path, metadata: resolvedMetadata, tileBytes: bytes);
+    _writeTileFile(
+      path,
+      overrideFreshAge != null
+          ? CachedMapTileMetadata(
+              staleAt: DateTime.timestamp().add(overrideFreshAge!),
+              lastModified: metadata.lastModified,
+              etag: metadata.etag,
+            )
+          : metadata,
+      bytes,
+    );
   }
 }