isolate_cluster 0.15.1

  • README.md
  • CHANGELOG.md
  • Example
  • Installing
  • Versions
  • 47

Isolate Cluster

A library to build up a cluster of isolates. It provides easy communication between the isolates of the cluster. Furthermore, an isolate can register itself as a listener for cluster events.

How to use

Here is a quick overview of the feature implemented so far:


import 'package:isolate_cluster/isolate_cluster.dart';

main() async {
  // create a single node cluster (the only type currently supported).
  final cluster = new IsolateCluster.singleNode();

  // spawn 3 isolates. you have to provide a top-level function. optionally, properties
  // can be provided. the properties can be accessed from the IsolateContext and the IsolateRef.
  cluster.spawnIsolate(new Uri(path: '/sender/1'), sender, {'msg': 'foo'});
  cluster.spawnIsolate(new Uri(path: '/sender/2'), sender, {'msg': 'bar'});
  IsolateRef receiverRef = await cluster
      .spawnIsolate(new Uri(path: '/receiver'), receiver, {'type': 'receiver'});

  // Look up an isolate by path.
  IsolateRef lookedUp = await cluster.lookupIsolate(new Uri(path: '/receiver'));
  print('[main] looked up isolate: $lookedUp');

  // send a message to the isolate using the IsolateRef.
  receiverRef.send('foo bar', type: 'string');
}

// the entry point for the receiver isolate
receiver(IsolateContext isolateContext) {
  print('[$isolateContext] receiver started');

  // counter for received messages
  int msgCount = 0;

  // register a listener for messages sent to this isolate.
  isolateContext.onMessage.listen((message) async {
    print('[${isolateContext.path}] message received: ${message}');

    // reply message to sender
    message.replyTo?.send('re: ${message.content}');

    if (message.sender != null) {
      // look up sender by path
      IsolateRef lookedUpSender =
          await isolateContext.lookupIsolate(message.sender.path);
      print('[$isolateContext] looked up sender: $lookedUpSender');
    } else {
      IsolateRef spawnedIsolate =
          await isolateContext.spawnIsolate(new Uri(path: "/spawned"), spawned);
      spawnedIsolate.send("hello spawned!");
    }

    // if 3 messages received, shutdown the cluster node.
    msgCount++;
    if (msgCount == 3) {
      isolateContext.shutdownNode();
    }
  });

  // register a shutdown request listener
  isolateContext.shutdownRequestListener = () {
    print('[$isolateContext] shutdown requested!');
    isolateContext.shutdownIsolate();
  };
}

sender(IsolateContext isolateContext) {
  print('[${isolateContext}] sender started');

  // listen to replies from receiver
  isolateContext.onMessage.listen(
      (msg) => print('[${isolateContext.path}] message received: $msg'));

  // register a listener for isolate up events. a reference to the newly spawned isolate is provided to the listener. the listener
  // has access to the properties of the spawned isolate and can send messages to it via the IsolateRef.
  isolateContext.onIsolateUp
      .where((ref) => ref.property('type') == 'receiver')
      .listen((ref) => ref.send(isolateContext.property('msg')));
}

spawned(IsolateContext isolateContext) {
  print('[$isolateContext] spawned started');
  isolateContext.onMessage
      .listen((msg) => print('[$isolateContext] message received: $msg'));
}

Roadmap

These features will be implemented in the (near) future:

  • Supervision: Every isolate has a supervisor, that will be informed in the case of a failure
  • Multi-Node: Support for clusters distributed over multiple DartVMs

Version 0.15.1

  • Bugfix: Fixed an exception in AllIsolateRefSelector.

Version 0.15.0

  • It is now possible to provide a selector to IsolateRefGroup.send() to support different target selection strategies.

Version 0.14.0

  • BREAKING CHANGE: Renamed class Message to IsolateMessage.
  • It is now possible to register an (isolate local) error listener to listen to errors occured (and not catched) in the context of the isolate. If no listener is registered, the error is logged as a WARNING.

Version 0.13.0

  • Now supports Dart strong mode.

Version 0.12.0

  • Added getter for a local isolate ref to the isolate content.

Version 0.11.1

  • Bugfix: fixed hard-coded paths

Version 0.11.0

  • Added helper to send messages to a group of isolate of 'same type' using a round robin strategy.
  • Added helper to dispatch messages received by an isolate to handlers based on the message type.

Version 0.10.0

  • BREAKING CHANGE: Streams returned by IsolateContext.onMessage and IsolateContext.onIsolateUp are now broadcast streams and start emitting events after the entry point of the isolate was completely executed.

Version 0.9.0

  • Bugfix: Fixed broken argument check in lookupIsolates()

Version 0.8.0

  • BREAKING CHANGE: Changed logger names to be shorter.
  • Added lookupIsolates() to look up all isolates of a given path.

Version 0.7.0

  • A message to an isolate can now have a correlationId.

Version 0.6.0

  • BREAKING CHANGE: The getter isolateContext was not able to provide a valid context in all situations. Instead, the context is now a parameter of the EntryPoint function.
  • It is now possible to spawn an isolate by an URI.
  • All messages are now valid to be sent over a SendPort.

Version 0.5.0

  • BREAKING CHANGE: Renamed content to isolateContext
  • A message to an isolate can now have a type

Version 0.4.0

  • BREAKING CHANGE: Very isolate now has a path
  • Isolates can be looked up by path
  • Isolates can spawn and look up other isolates
  • Added documentation comments to all parts of the public API.
  • Added logging
  • Fixed a couple of bugs

Version 0.3.0

  • A cluster can now be stopped by calling IsolateCluster.shutdown()
  • Fixed typo in change log (again).

Version 0.2.1

  • Fixed typos in change log.

Version 0.2.0

  • BREAKING CHANGE: Newly spawned isolates no longer receive IsolateUp events for isolates that are already part of the cluster.

Version 0.1.0

  • Initial implementation.

example/example.dart

import 'package:isolate_cluster/isolate_cluster.dart';

main() async {
  // create a single node cluster (the only type currently supported).
  final cluster = new IsolateCluster.singleNode();

  // spawn an isolate by uri
  cluster.spawnIsolate(
      Uri.parse('/uri/isolate/'), Uri.parse('uri_isolate.dart'));

  // spawn 3 isolates. you have to provide a top-level function. optionally, properties
  // can be provided. the properties can be accessed from the IsolateContext and the IsolateRef.
  cluster.spawnIsolate(new Uri(path: '/sender/1'), sender, {'msg': 'foo'});
  cluster.spawnIsolate(new Uri(path: '/sender/2'), sender, {'msg': 'bar'});

  IsolateRef receiverRef = await cluster
      .spawnIsolate(new Uri(path: '/receiver'), receiver, {'type': 'receiver'});

  // Look up an isolate by path.
  IsolateRef lookedUp = await cluster.lookupIsolate(new Uri(path: '/receiver'));
  print('[main] looked up isolate: $lookedUp');

  // send a message to the isolate using the IsolateRef.
  receiverRef.send('foo bar', type: 'string', correlationId: 'abc');
}

// the entry point for the receiver isolate
receiver(IsolateContext isolateContext) {
  print('[$isolateContext] receiver started');

  // counter for received messages
  int msgCount = 0;

  // register a listener for messages sent to this isolate.
  isolateContext.onMessage.listen((message) async {
    print('[${isolateContext.path}] message received: ${message}');

    // reply message to sender
    message.replyTo?.send('re: ${message.content}');

    if (message.sender != null) {
      // look up sender by path
      IsolateRef lookedUpSender =
          await isolateContext.lookupIsolate(message.sender.path);
      print('[$isolateContext] looked up sender: $lookedUpSender');
    } else {
      IsolateRef spawnedIsolate =
          await isolateContext.spawnIsolate(new Uri(path: "/spawned"), spawned);
      spawnedIsolate.send("hello spawned!");
    }

    // if 3 messages received, shutdown the cluster node.
    msgCount++;
    if (msgCount == 3) {
      // spawn an isolate from an isolate using an uri
      await isolateContext.spawnIsolate(
          Uri.parse('/uri/isolate/'), Uri.parse('uri_isolate.dart'));

      // shutdown node
      isolateContext.shutdownNode();
    }
  });

  // register a shutdown request listener
  isolateContext.shutdownRequestListener = () {
    print('[$isolateContext] shutdown requested!');
    isolateContext.shutdownIsolate();
  };
}

sender(IsolateContext isolateContext) {
  print('[${isolateContext}] sender started');

  // listen to replies from receiver
  isolateContext.onMessage.listen(
      (msg) => print('[${isolateContext.path}] message received: $msg'));

  // register a listener for isolate up events. a reference to the newly spawned isolate is provided to the listener. the listener
  // has access to the properties of the spawned isolate and can send messages to it via the IsolateRef.
  isolateContext.onIsolateUp
      .where((ref) => ref.property('type') == 'receiver')
      .listen((ref) => ref.send(isolateContext.property('msg')));
}

spawned(IsolateContext isolateContext) {
  print('[$isolateContext] spawned started');
  isolateContext.onMessage
      .listen((msg) => print('[$isolateContext] message received: $msg'));
}

1. Depend on it

Add this to your package's pubspec.yaml file:


dependencies:
  isolate_cluster: "^0.15.1"

2. Install it

You can install packages from the command line:

with pub:


$ pub get

with Flutter:


$ flutter packages get

Alternatively, your editor might support pub get or packages get. Check the docs for your editor to learn more.

3. Import it

Now in your Dart code, you can use:


import 'package:isolate_cluster/isolate_cluster.dart';
        
Version Uploaded Documentation Archive
0.15.1 Mar 7, 2017 Go to the documentation of isolate_cluster 0.15.1 Download isolate_cluster 0.15.1 archive
0.15.0 Mar 6, 2017 Go to the documentation of isolate_cluster 0.15.0 Download isolate_cluster 0.15.0 archive
0.14.0 Feb 6, 2017 Go to the documentation of isolate_cluster 0.14.0 Download isolate_cluster 0.14.0 archive
0.13.0 Oct 27, 2016 Go to the documentation of isolate_cluster 0.13.0 Download isolate_cluster 0.13.0 archive
0.12.0 Oct 16, 2016 Go to the documentation of isolate_cluster 0.12.0 Download isolate_cluster 0.12.0 archive
0.11.1 Oct 6, 2016 Go to the documentation of isolate_cluster 0.11.1 Download isolate_cluster 0.11.1 archive
0.11.0 Oct 5, 2016 Go to the documentation of isolate_cluster 0.11.0 Download isolate_cluster 0.11.0 archive
0.10.0 Sep 14, 2016 Go to the documentation of isolate_cluster 0.10.0 Download isolate_cluster 0.10.0 archive
0.9.0 Sep 9, 2016 Go to the documentation of isolate_cluster 0.9.0 Download isolate_cluster 0.9.0 archive
0.8.0 Sep 9, 2016 Go to the documentation of isolate_cluster 0.8.0 Download isolate_cluster 0.8.0 archive

All 18 versions...

Analysis

This feature is new.
We welcome feedback.
More details: scoring.

We analyzed this package, and provided a score, details, and suggestions below.

  • tool failures on Feb 3, 2018
  • Dart: 2.0.0-dev.20.0
  • pana: 0.10.1

Scores

Popularity:
Describes how popular the package is relative to other packages. [more]
0 / 100
Health:
Code health derived from static analysis. [more]
94 / 100
Maintenance:
Reflects how tidy and up-to-date the package is. [more]
95 / 100
Overall score:
Weighted score of the above. [more]
47

Platforms

Detected platforms: Flutter, web, other

No platform restriction found in primary library package:isolate_cluster/isolate_cluster.dart.

Suggestions

  • Fix lib/cluster.dart.

    Strong-mode analysis of lib/cluster.dart failed with the following error:

    line: 184 col: 29
    The argument type 'List' can't be assigned to the parameter type 'FutureOr<List<IsolateRef>>'.

  • Fix issues reported by dartanalyzer.

    dartanalyzer reported 1 error(s) and 0 warning(s).

  • The description is too short.

    Add more detail about the package, what it does and what is its target use case. Try to write at least 60 characters.

  • Package is pre-v1 release.

    While there is nothing inherently wrong with versions of 0.*.*, it usually means that the author is still experimenting with the general direction API.

  • Use analysis_options.yaml.

    Rename old .analysis_options file to analysis_options.yaml.

Dependencies

Package Constraint Resolved Available
Direct dependencies
Dart SDK >=1.21.1 <2.0.0
logging ^0.11.2 0.11.3+1
uuid ^0.5.0 0.5.3
Transitive dependencies
charcode 1.1.1
collection 1.14.5
convert 2.0.1
crypto 2.0.2+1
typed_data 1.1.5
Dev dependencies
test ^0.12.6+2