isolate_manager 5.2.0

Create multiple long-lived isolates for the Functions, supports Worker on the Web (with the effective generator) and WASM compilation.

Isolate Manager

Features

• Supports to create multiple Isolates for:
  • A single Function: One IsolateManager instance can be used for only one Function, so that the stream can be used easily when using something like a StreamBuilder (Use the@isolateManagerWorker and @isolateManagerCustomWorker annotations).
  • Multiple Functions: One IsolateManagerShared instance can be used for multiple Functions, it's good for computing multiple Functions and doesn't care much about the stream (Use the @isolateManagerSharedWorker annotation).
• Supports Worker on the Web. If the Worker is unavailable in the working browser or is not configured, the Future (and Stream) will be used.
• Supports WASM compilation on the Web.
• Supports try-catch blocks.
• Multiple compute operations are allowed because the plugin will queue the input data and send it to a free isolate later.

Table Of Contents

• Benchmark
• Isolate Manager Shared (For Multiple Functions)
• Isolate Manager (For A Single Function)
  • Basic Usage
  • Custom Function Usage
  • Progress Values (Receives multiple values from a single compute)
• Try Catch Block
• Addtional Information
• Contributions

Benchmark

Execute a recursive Fibonacci function 70 times, computing the sequence for the numbers 30, 33, and 36. The results are in microseconds (On Macbook M1 Pro 14-inch 16Gb RAM).

• VM

Fibonacci	Main App	One Isolate	Three Isolates	Isolate.run
30	751,364	771,142	274,854	769,588
33	3,189,873	3,185,798	1,152,083	3,214,685
36	13,510,136	13,540,763	4,873,100	13,766,930

• Chrome (With Worker supported)

Fibonacci	Main App	One Worker	Three Workers	Isolate.run (Unsupported)
30	2,125,101	547,800	195,101	0
33	9,083,800	2,286,899	803,599	0
36	38,083,500	9,575,899	3,383,299	0

See here for the test details.

IsolateManagerShared Method

This method currently doesn't support the IsolateManagerFunction.customFunction.

void main() async {
  // Create 3 isolateShared to solve the problems
  final isolateShared = IsolateManager.createShared(
    concurrent: 3, 
    useWorker: true

    // Add this mappings so we can ignore the `workerName` parameter 
    // when using the `compute` method.
    workerMappings: {
      addFuture : 'addFuture', 
      add : 'add',
    }  
  );


  // Compute the values. The return type and parameter type will respect the type
  // of the function.
  final added = await isolateShared.compute(
    addFuture, 
    [1.1, 2.2], 
    // workerFunction: 'addFuture', // Ignored because the `workerMappings` is specified
  );
  print('addFuture: 1.1 + 2.2 = $added');

  // Compute the values. The return type and parameter type will respect the type
  // of the function.
  final added = await isolateShared.compute(
    add, 
    [1, 2], 
    // workerFunction: 'add', // Ignored because the `workerMappings` is specified
  );
  print('add: 1 + 2 = $added');
}

@isolateManagerSharedWorker
Future<double> addFuture(List<double> values) async {
  return values[0] + values[1];
}

@isolateManagerSharedWorker
int add(List<int> values) {
  return values[0] + values[1];
}

Important Note: If you want to build functions into js for Workers, these functions MUST NOT depend on any Flutter library like dart:ui, material,... The best way is moving these functions into a separated file so we can control the imports easily.

Run this command to generate a Javascript Worker (named $shared_worker.js inside the web folder):

dart run isolate_manager:generate

Add flag --shared if you want to generate only for the IsolateManagerShared.

IsolateManager Method

Basic Usage

There are multiple ways to use this package. The only thing to notice is that the function has to be a static or top-level function.

main() async {
  final isolate = IsolateManager.create(
      fibonacci, 
      workerName: 'fibonacci', // Add this line
      concurrent: 2,
    );

  isolate.stream.listen((value) {
    print(value);
  });

  final fibo = await isolate(20);
}

@isolateManagerWorker // Add this anotation
int fibonacci(int n) {
  if (n == 0) return 0;
  if (n == 1) return 1;

  return fibonacci(n - 1) + fibonacci(n - 2);
}

Important Note: If you want to build functions into js for Workers, these functions MUST NOT depend on any Flutter library like dart:ui, material,... The best way is moving these functions into a separated file so we can control the imports easily.

Run this command to generate a Javascript Worker:

dart run isolate_manager:generate

Add flag --single if you want to generate only for the IsolateManager.

You can restart or stop the isolate using this method:

await isolateManager.restart();
await isolateManager.stop();

Custom Function Usage

You can control everything with this method when you want to create multiple isolates for a function.

Step 1: Create a function of this form

Let it automatically handles the result and the Exception:

@isolateManagerCustomWorker // Add this anotation for a custom function
void customIsolateFunction(dynamic params) {
  IsolateManagerFunction.customFunction<int, int>(
    params,
    onEvent: (controller, message) {
      /* This event will be executed every time the `message` is received from the main isolate */
      return fibonacci(message);
    },
    onInitial: (controller, initialParams) {
       /* This event will be executed before all the other events and only one time. */
    },
    onDispose: (controller) {
       /* This event will be executed after all the other events and should NOT be a `Future` event */
    },
  );
}

Handle the result and the Exception by your self:

@isolateManagerCustomWorker // Add this anotation for a custom function
void customIsolateFunction(dynamic params) {
  IsolateManagerFunction.customFunction<Map<String, dynamic>, String>(
    params,
    onEvent: (controller, message) {
      // This event will be executed every time the `message` is received from the main isolate.
      try {
        final result = fibonacci(message);
        controller.sendResult(result);
      } catch (err, stack) {
        controller.sendResultError(IsolateException(err, stack));
      }

      // Just returns something that unused to complete this method.
      return 0;
    },
    onInitial: (controller, initialParams) {
       /* This event will be executed before all the other events. */
    },
    onDispose: (controller) {
       /* This event will be executed after all the other events. */
    },
    autoHandleException: false,
    autoHandleResult: false,
  );
}

Step 2: Create an IsolateManager instance for your own function

final isolateManager = IsolateManager.createCustom(
    customIsolateFunction,
    initialParams: 'This is the initialParams',
    workerName: 'customIsolateFunction',
    debugMode: true,
  );

Now you can use everything as the Basic Usage.

try-catch Block

You can use try-catch to catch exceptions:

try {
  final result = await isolate(-10);
} on SomeException catch (e1) {
  print(e1);
} catch (e2) {
  print(e2);
}

Progress Values

You can even manage the final result by using this callback, useful when you create your own function that needs to send the progress value before returning the final result:

main() {
  // Create an IsolateManager instance.
  final isolateManager = IsolateManager.createCustom(progressFunction);

  // Get the result.
  final result = await isolateManager.compute(100, callback: (value) {
    // Condition to recognize the progress value. Ex:
    final data = jsonDecode(value);

    if (data.containsKey('progress')) {
      print('This is a progress value: ${data['progress']}');

      // Return `false` to mark this value is not the final.
      return false;
    }

    print('This is a final value: ${data['result']}');

    // Return `true` to mark this value is the final.
    return true;
  });

  print(result); // 100
}

// This is a progress function
@isolateManagerCustomWorker // Add this anotation for a custom function
void progressFunction(dynamic params) {
  IsolateManagerFunction.customFunction<String, int>(
    params,
    onEvent: (controller, message) {
      // This value is sent as the progress values.
      for (int i = 0; i < message; i++) {
        final progress = jsonEncode({'progress' : messsage});
        controller.sendResult(progress);
      }

      // This is a final value.
      return jsonEncode({'result' : messsage});
    },
  );
}

Additional Information

• The function has to be a static or top-level function.

• If you want to build functions into js for Workers, these functions MUST NOT depend on any Flutter library like dart:ui, material,... The best way is moving these functions into a separated file so we can control the imports easily.

• Use queuesLength to get the current number of queued computation.

• Use ensureStarted to able to wait for the start method to finish when you want to call the start method manually without await and wait for it later.

• Use isStarted to check if the start method is completed or not.

• The result that you get from the isolate (or Worker) is sometimes different from the result that you want to get from the return type in the main app, you can use converter and workerConverter parameters to convert the result received from the Isolate (converter) and Worker (workerConverter). Example:

  1. List<String>

     main() async {
       final isolate = IsolateManager.create(
         aStringList,
         workerName: 'aStringList',
         // Cast to List<String>
         workerConverter: (value) => value.cast<String>() as List<String>,
         isDebug: true,
       );
     
       final listString = ['a', 'b', 'c'];
       final result = await isolate.compute(listString);
       expect(result, listString);
     }
     
     @isolateManagerWorker
     List<String> aStringList(List<String> params) {
       return params;
     }
     

  2. Map<String, int>: Use json for the complicated cases

     main() async {
       final isolate = IsolateManager.create(
         aStringIntMap,
         workerName: 'aStringIntMap',
         isDebug: true,
       );
       await isolate.start();
     
       final map = {'a': 1, 'b': 2, 'c': 3};
       final result = await isolate.compute(jsonEncode(map));
       expect(jsonDecode(result), map);
     }
     
     @isolateManagerWorker
     String aStringIntMap(String params) {
       return params;
     }
     

  Data flow: Main -> Isolate or Worker -> Converter -> Result

• If you want to use Worker more effectively, convert all parameters and results to JSON (or String) before sending them.

• The generator options and flags:

  • --single: Generates single Functions only.
  • --shared: Generates shared Functions only.
  • --in <path> (or -i <path>): Inputted folder.
  • --out <path> (or -o <path>): Outputted folder.
  • --obfuscate <level>: The obfuscated level of JS (0 to 4). Default is set to 4.
  • --debug: Keeps the temp files for debugging.

Contributions

• If you encounter any problems or feel the library is missing a feature, feel free to open an issue. Pull requests are also welcome.

• If you like my work or the free stuff on this channel and want to say thanks, or encourage me to do more, you can buy me a coffee. Thank you so much!