blob: b41d8d94a457c03ccc7cafb8d580f3722caf72c7 [file] [log] [blame]
// Copyright (c) 2023, the Dart project authors. Please see the AUTHORS file
// for details. All rights reserved. Use of this source code is governed by a
// BSD-style license that can be found in the LICENSE file.
import 'dart:async';
import 'dart:convert';
import 'dart:io';
import 'dart:isolate';
import 'package:stream_channel/isolate_channel.dart';
import 'package:stream_channel/stream_channel.dart';
Future<void> main() async {
// A StreamChannel<T>, is in simplest terms, a wrapper around a Stream<T> and
// a StreamSink<T>. For example, you can create a channel that wraps standard
// IO:
var stdioChannel = StreamChannel(stdin, stdout);
// Like a Stream<T> can be transformed with a StreamTransformer<T>, a
// StreamChannel<T> can be transformed with a StreamChannelTransformer<T>.
// For example, we can handle standard input as strings:
var stringChannel = stdioChannel
.transformStream(const LineSplitter());
// You can implement StreamChannel<T> by extending StreamChannelMixin<T>, but
// it's much easier to use a StreamChannelController<T>. A controller has two
// StreamChannel<T> members: `local` and `foreign`. The creator of a
// controller should work with the `local` channel, while the recipient should
// work with the `foreign` channel, and usually will not have direct access to
// the underlying controller.
var ctrl = StreamChannelController<String>(); {
// Do something useful here...
// You can also pipe events from one channel to another.
await ctrl.local.sink.close();
// The StreamChannel<T> interface provides several guarantees, which can be
// found here:
// By calling `StreamChannel<T>.withGuarantees()`, you can create a
// StreamChannel<T> that provides all guarantees.
var dummyCtrl0 = StreamChannelController<String>();
var guaranteedChannel = StreamChannel.withGuarantees(, dummyCtrl0.foreign.sink);
// To close a StreamChannel, use `sink.close()`.
await guaranteedChannel.sink.close();
// A MultiChannel<T> multiplexes multiple virtual channels across a single
// underlying transport layer. For example, an application listening over
// standard I/O can still support multiple clients if it has a mechanism to
// separate events from different clients.
// A MultiChannel<T> splits events into numbered channels, which are
// instances of VirtualChannel<T>.
var dummyCtrl1 = StreamChannelController<String>();
var multiChannel = MultiChannel<String>(dummyCtrl1.foreign);
var channel1 = multiChannel.virtualChannel();
await multiChannel.sink.close();
// The client/peer should also create its own MultiChannel<T>, connected to
// the underlying transport, use the corresponding ID's to handle events in
// their respective channels. It is up to you how to communicate channel ID's
// across different endpoints.
var dummyCtrl2 = StreamChannelController<String>();
var multiChannel2 = MultiChannel<String>(dummyCtrl2.foreign);
var channel2 = multiChannel2.virtualChannel(;
await channel2.sink.close();
await multiChannel2.sink.close();
// Multiple instances of a Dart application can communicate easily across
// `SendPort`/`ReceivePort` pairs by means of the `IsolateChannel<T>` class.
// Typically, one endpoint will create a `ReceivePort`, and call the
// `IsolateChannel.connectReceive` constructor. The other endpoint will be
// given the corresponding `SendPort`, and then call
// `IsolateChannel.connectSend`.
var recv = ReceivePort();
var recvChannel = IsolateChannel<void>.connectReceive(recv);
var sendChannel = IsolateChannel<void>.connectSend(recv.sendPort);
// You must manually close `IsolateChannel<T>` sinks, however.
await recvChannel.sink.close();
await sendChannel.sink.close();
// You can use the `Disconnector` transformer to cause a channel to act as
// though the remote end of its transport had disconnected.
var disconnector = Disconnector<String>();
var disconnectable = stringChannel.transform(disconnector);
disconnectable.sink.add('Still connected!');
await disconnector.disconnect();
// Additionally:
// * The `DelegatingStreamController<T>` class can be extended to build a
// basis for wrapping other `StreamChannel<T>` objects.
// * The `jsonDocument` transformer converts events to/from JSON, using
// the `json` codec from `dart:convert`.
// * `package:json_rpc_2` directly builds on top of
// `package:stream_channel`, so any compatible transport can be used to
// create interactive client/server or peer-to-peer applications (i.e.
// language servers, microservices, etc.