LCOV - code coverage report
Current view: top level - src - combine_singleton.dart (source / functions) Hit Total Coverage
Test: lcov.info Lines: 5 5 100.0 %
Date: 2022-12-12 00:09:36 Functions: 0 0 -

          Line data    Source code
       1             : import 'package:combine/src/combine_info.dart';
       2             : import 'package:combine/src/combine_isolate/combine_isolate.dart';
       3             : import 'package:combine/src/combine_worker_singleton.dart';
       4             : import 'package:combine/src/isolate_factory/effective_isolate_factory.dart';
       5             : import 'package:combine/src/isolate_factory/isolate_factory.dart';
       6             : import 'package:combine/src/isolate_messenger/isolate_messenger.dart';
       7             : 
       8             : /// {@template combine_singleton}
       9             : /// [Combine] is used to [spawn] a new [CombineIsolate].
      10             : ///
      11             : /// Take a look at [CombineWorker] if you want to efficiently execute tasks in isolates' pool.
      12             : /// {@endtemplate}
      13             : class Combine {
      14             :   /// {@macro combine_singleton}
      15           4 :   factory Combine() => _instance;
      16           2 :   Combine._();
      17             : 
      18             :   /// `late` is used to make this singleton lazy. So it will be initialized
      19             :   /// only on first usage.
      20           6 :   static late final _instance = Combine._();
      21             : 
      22             :   /// Creates a new [CombineIsolate] which is just a representation of Isolate.
      23             :   /// So when you create a [CombineIsolate], an Isolate
      24             :   /// will be created under the hood. On the web, however,
      25             :   /// [entryPoint] will be executed on the main isolate.
      26             :   ///
      27             :   /// [entryPoint] is a function which will be called in Isolate.
      28             :   /// This function may be first-level, as well as a top-level or static.
      29             :   /// Also it may use closure variables but with some restrictions:
      30             :   ///  - closure variable will be copied (as every variable passed to isolate)
      31             :   ///    so it won't be synchronized across Isolates.
      32             :   ///  - if you use at least one variable from closure all closure variables
      33             :   ///    will be copied to the Isolate due to this
      34             :   ///    [issue](https://github.com/dart-lang/sdk/issues/36983).
      35             :   ///    It can lead to high memory consumption or event exception because
      36             :   ///    some variables may contains native resources.
      37             :   ///
      38             :   /// Due to above points, I highly recommend you to avoid using closure
      39             :   /// variables, until this issue is fixed.
      40             :   ///
      41             :   /// [debugName] is the Isolate's name for dev tools.
      42             :   ///
      43             :   /// If [errorsAreFatal] is set to `true` then uncaught exceptions will kill the Isolate.
      44             :   ///
      45             :   /// Returns [CombineInfo] which holds [CombineIsolate] to control Isolate
      46             :   /// and [IsolateMessenger] to communicate with it.
      47             :   ///
      48             :   /// Example usage:
      49             :   /// ```dart
      50             :   /// CombineInfo isolateInfo = await Combine().spawn((context) {
      51             :   ///   print("Argument from main isolate: ${context.argument}");
      52             :   ///
      53             :   ///   context.messenger.messages.listen((message) {
      54             :   ///     print("Message from main isolate: $message");
      55             :   ///     context.messenger.send("Hello from isolate!");
      56             :   ///   });
      57             :   /// }, argument: 42);
      58             :   ///
      59             :   /// isolateInfo.messenger
      60             :   ///   ..messages.listen((message) {
      61             :   ///     print("Message from isolate: $message");
      62             :   ///   })
      63             :   ///   ..send("Hello from main isolate!");
      64             :   ///
      65             :   /// // Will print:
      66             :   /// // Argument from main isolate: 42
      67             :   /// // Message from main isolate: Hello from main isolate!
      68             :   /// // Message from isolate: Hello from isolate!
      69             :   /// ```
      70           2 :   Future<CombineInfo> spawn<T>(
      71             :     IsolateEntryPoint<T> entryPoint, {
      72             :     T? argument,
      73             :     bool errorsAreFatal = true,
      74             :     String? debugName = "combine_isolate",
      75             :   }) async {
      76           4 :     return effectiveIsolateFactory.create(
      77             :       entryPoint,
      78             :       argument: argument,
      79             :       errorsAreFatal: errorsAreFatal,
      80             :       debugName: debugName,
      81             :     );
      82             :   }
      83             : }

Generated by: LCOV version 1.16