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 : }