Concurrency overview page update (#5402)

This is the first PR of two that will update isolate documentation. It
was decided that we should split [the original
PR](#5332) into two.

This PR updates documentation at language/concurrency with more
information.

Fixes #3720

---

- [x] I’ve reviewed the contributor guide and applied the relevant
portions to this PR.
- [x] This PR doesn’t contain automatically generated corrections or
text (Grammarly, LLMs, and similar).
- [x] This PR follows the [Google Developer Documentation Style
Guidelines](https://developers.google.com/style) — for example, it
doesn’t use _i.e._ or _e.g._, and it avoids _I_ and _we_ (first person).
- [x] This PR uses [semantic line
breaks](https://github.com/dart-lang/site-shared/blob/main/doc/writing-for-dart-and-flutter-websites.md#semantic-line-breaks)
of 80 characters or fewer.

---------

Co-authored-by: Marya <111139605+MaryaBelanger@users.noreply.github.com>
Co-authored-by: Parker Lougheed <parlough@gmail.com>

examples/concurrency/lib/await_for_syntax.dart

@@ -0,0 +1,6 @@
+Stream<int> sumStream(Stream<int> stream) async* {
+  var sum = 0;
+  await for (final value in stream) {
+    yield sum += value;
+  }
+}

examples/concurrency/lib/future_syntax.dart

@@ -0,0 +1,14 @@
+// ignore_for_file: unused_element
+import 'dart:io';
+
+// #docregion
+Future<String> _readFileAsync(String filename) {
+  final file = File(filename);
+
+  // .readAsString() returns a Future.
+  // .then() registers a callback to be executed when `readAsString` resolves.
+  return file.readAsString().then((contents) {
+    return contents.trim();
+  });
+}
+// #enddocregion

examples/concurrency/lib/isolate_run_syntax.dart

@@ -0,0 +1,11 @@
+import 'dart:isolate';
+
+// #docregion
+int slowFib(int n) => n <= 1 ? 1 : slowFib(n - 1) + slowFib(n - 2);
+
+// Compute without blocking current isolate.
+void fib40() async {
+  var result = await Isolate.run(() => slowFib(40));
+  print('Fib(40) = $result');
+}
+// #enddocregion

examples/concurrency/lib/isolate_spawn_syntax.dart

@@ -0,0 +1,52 @@
+import 'dart:async';
+import 'dart:convert';
+import 'dart:isolate';
+
+// #docregion
+class Worker {
+  late SendPort _sendPort;
+  final Completer<void> _isolateReady = Completer.sync();
+
+  Future<void> parseJson(String message) async {
+    await _isolateReady.future;
+    _sendPort.send(message);
+  }
+
+  Future<void> spawn(Function(Map<String, dynamic>) onReceiveMessage) async {
+    final receivePort = ReceivePort();
+    receivePort.listen((message) {
+      if (message is SendPort) {
+        _sendPort = message;
+        _isolateReady.complete();
+      } else if (message is Map<String, dynamic>) {
+        onReceiveMessage(message);
+      }
+    });
+    await Isolate.spawn(_readAndComputeOnIsolate, receivePort.sendPort);
+  }
+
+  static void _readAndComputeOnIsolate(SendPort port) {
+    final receivePort = ReceivePort();
+    port.send(receivePort.sendPort);
+
+    receivePort.listen((dynamic message) async {
+      if (message is String) {
+        final decoded = jsonDecode(message);
+        port.send(decoded);
+      }
+    });
+  }
+}
+// #enddocregion
+
+// This method represents your app-specific functionality.
+// After the Isolate decodes a large bit of json, it will be received here
+void onReceiveMessage(Map<String, dynamic> message) {
+  print(message);
+}
+
+void main() async {
+  final worker = Worker();
+  await worker.spawn(onReceiveMessage);
+  await worker.parseJson('{"key":"value"}');
+}

examples/concurrency/lib/stream_syntax.dart

@@ -0,0 +1 @@
+Stream<int> stream = Stream.periodic(const Duration(seconds: 1), (i) => i * i);

src/_data/side-nav.yml

@@ -97,10 +97,10 @@
           permalink: /language/modifier-reference
     - title: Concurrency
       children:
+        - title: Overview
+          permalink: /language/concurrency
         - title: Asynchronous support
           permalink: /language/async
-        - title: Isolates
-          permalink: /language/concurrency
     - title: Null safety
       expanded: false
       children:

src/guides/language/coming-from/swift-to-dart.md

@@ -2407,7 +2407,7 @@ and won't be covered here.
 Each isolate has its own event loop.
 For more information, see [How isolates work][].
 
-[How isolates work]: /language/concurrency#how-isolates-work
+[How isolates work]: /language/concurrency
 
 ### Futures
 

src/language/async.md

@@ -3,11 +3,11 @@ title: Asynchrony support
 description: Information on writing asynchronous code in Dart.
 short-title: Async
 prevpage:
-  url: /language/modifier-reference
-  title: Class modifiers reference
-nextpage:
   url: /language/concurrency
   title: Concurrency
+nextpage:
+  url: /null-safety
+
 ---
 
 <?code-excerpt replace="/ *\/\/\s+ignore_for_file:[^\n]+\n//g; /(^|\n) *\/\/\s+ignore:[^\n]+\n/$1/g; /(\n[^\n]+) *\/\/\s+ignore:[^\n]+\n/$1\n/g; / *\/\/\s+ignore:[^\n]+//g; /([A-Z]\w*)\d\b/$1/g"?>