isolate_cluster 0.17.0

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

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.17.0

  • Updated upper bound of SDK constraints to <3.0.0

Version 0.16.3

  • Downgraded dependency to package 'uuid' to be compatible with package 'mongo_dart'

Version 0.16.2

  • Dart 2 strong mode alignments.

Version 0.16.1

  • Dart SDK constraint is now >=2.0.0-dev.40.0 to support Dart package analysis.

Version 0.16.0

  • Updates to be Dart 2 compliant.
  • BREAKING CHANGE: The return type of EntryPoint is now FutureOr<void>.
  • Fixed some documentation issues.

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'));
}

Use this package as a library

1. Depend on it

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


dependencies:
  isolate_cluster: ^0.17.0

2. Install it

You can install packages from the command line:

with pub:


$ pub get

Alternatively, your editor might support pub 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.17.0 Jul 24, 2018 Go to the documentation of isolate_cluster 0.17.0 Download isolate_cluster 0.17.0 archive
0.16.3 Jul 17, 2018 Go to the documentation of isolate_cluster 0.16.3 Download isolate_cluster 0.16.3 archive
0.16.2 Jul 17, 2018 Go to the documentation of isolate_cluster 0.16.2 Download isolate_cluster 0.16.2 archive
0.16.1 Mar 28, 2018 Go to the documentation of isolate_cluster 0.16.1 Download isolate_cluster 0.16.1 archive
0.16.0 Mar 28, 2018 Go to the documentation of isolate_cluster 0.16.0 Download isolate_cluster 0.16.0 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

All 23 versions...

Popularity:
Describes how popular the package is relative to other packages. [more]
38
Health:
Code health derived from static analysis. [more]
99
Maintenance:
Reflects how tidy and up-to-date the package is. [more]
80
Overall:
Weighted score of the above. [more]
65
Learn more about scoring.

We analyzed this package on Aug 10, 2018, and provided a score, details, and suggestions below. Analysis was completed with status tool failures using:

  • Dart: 2.0.0
  • pana: 0.11.8

Platforms

Detected platforms: unsure

Error(s) prevent platform classification:

Fix dependencies in pubspec.yaml.

Issues and suggestions

Fix dependencies in pubspec.yaml.

Running pub upgrade failed with the following output:

ERR: The current Dart SDK version is 2.0.0.
 
 Because isolate_cluster depends on uuid >=0.0.7 <1.0.3 which requires SDK version <2.0.0, version solving failed.

Fix platform conflicts.

Error(s) prevent platform classification:

Fix dependencies in pubspec.yaml.

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 of the API.

Format lib/cluster.dart.

Run dartfmt to format lib/cluster.dart.

Format lib/helper.dart.

Run dartfmt to format lib/helper.dart.

Fix additional 3 files with analysis or formatting issues.

Additional issues in the following files:

  • lib/isolate.dart (Run dartfmt to format lib/isolate.dart.)
  • lib/isolate_cluster.dart (Run dartfmt to format lib/isolate_cluster.dart.)
  • lib/messages.dart (Run dartfmt to format lib/messages.dart.)

Dependencies

Package Constraint Resolved Available
Direct dependencies
Dart SDK >=2.0.0-dev.69.0 <3.0.0