OLD | NEW |
1 // Copyright (c) 2012, the Dart project authors. Please see the AUTHORS file | 1 // Copyright (c) 2012, the Dart project authors. Please see the AUTHORS file |
2 // for details. All rights reserved. Use of this source code is governed by a | 2 // for details. All rights reserved. Use of this source code is governed by a |
3 // BSD-style license that can be found in the LICENSE file. | 3 // BSD-style license that can be found in the LICENSE file. |
4 | 4 |
5 /** | 5 /** |
6 * Support for asynchronous programming, | 6 * Support for asynchronous programming, |
7 * with classes such as Future and Stream. | 7 * with classes such as Future and Stream. |
8 * | 8 * |
9 * For an introduction to asynchronous programming in Dart, see the | 9 * Understanding [Future]s and [Stream]s is a prerequisite for |
10 * [dart:async section of the language tour] | 10 * writing just about any Dart program. |
11 * (https://www.dartlang.org/docs/dart-up-and-running/contents/ch03.html#ch03-as
ynchronous-programming). | 11 * |
| 12 * To use this library in your code: |
| 13 * |
| 14 * import 'dart:async'; |
| 15 * |
| 16 * ## Future |
| 17 * |
| 18 * A Future object represents a computation whose return value |
| 19 * might not yet be available. |
| 20 * The Future returns the value of the computation |
| 21 * when it completes at some time in the future. |
| 22 * Futures are often used for potentially lengthy computations |
| 23 * such as I/O and interaction with users. |
| 24 * |
| 25 * Many methods in the Dart libraries return Futures when |
| 26 * performing tasks. For example, when binding an HttpServer |
| 27 * to a host and port, the `bind()` method returns a Future. |
| 28 * |
| 29 * HttpServer.bind('127.0.0.1', 4444) |
| 30 * .then((server) => print('${server.isBroadcast}')) |
| 31 * .catchError(print); |
| 32 * |
| 33 * [Future.then] registers a callback function that runs |
| 34 * when the Future's operation, in this case the `bind()` method, |
| 35 * completes successfully. |
| 36 * The value returned by the operation |
| 37 * is passed into the callback function. |
| 38 * In this example, the `bind()` method returns the HttpServer |
| 39 * object. The callback function prints one of its properties. |
| 40 * [Future.catchError] registers a callback function that |
| 41 * runs if an error occurs within the Future. |
| 42 * |
| 43 * ## Stream |
| 44 * |
| 45 * A Stream provides an asynchronous sequence of data. |
| 46 * Examples of data sequences include user-generated events, |
| 47 * such as mouse clicks, and a stream of bytes read from a file. |
| 48 * The following example opens a file for reading. |
| 49 * [Stream.listen] registers a callback function that runs |
| 50 * each time more data is available. |
| 51 * |
| 52 * Stream<List<int>> stream = new File('quotes.txt').openRead(); |
| 53 * stream.transform(UTF8.decoder).listen(print); |
| 54 * |
| 55 * The stream emits a sequence of a list of bytes. |
| 56 * The program must interpret the bytes or handle the raw byte data. |
| 57 * Here, the code uses a UTF8 decoder (provided in the `dart:convert` library) |
| 58 * to convert the sequence of bytes into a sequence |
| 59 * of Dart strings. |
| 60 * |
| 61 * Another common use of streams is for user-generated events |
| 62 * in a web app: The following code listens for mouse clicks on a button. |
| 63 * |
| 64 * querySelector('#myButton').onClick.listen((_) => print('Click.')); |
12 * | 65 * |
13 * ## Other resources | 66 * ## Other resources |
14 * | 67 * |
15 * * [Using Future Based APIs] | 68 * * The [dart:async section of the library tour] |
16 * (https://www.dartlang.org/articles/using-future-based-apis/): A first look at | 69 * (https://www.dartlang.org/docs/dart-up-and-running/contents/ch03.html#ch03-as
ynchronous-programming): |
| 70 * A brief overview of asynchronous programming. |
| 71 * |
| 72 * * [Use Future-Based APIs] |
| 73 * (https://www.dartlang.org/docs/tutorials/futures/): A closer look at |
17 * Futures and how to use them to write asynchronous Dart code. | 74 * Futures and how to use them to write asynchronous Dart code. |
18 * | 75 * |
19 * * [Futures and Error Handling] | 76 * * [Futures and Error Handling] |
20 * (https://www.dartlang.org/articles/futures-and-error-handling/): Everything | 77 * (https://www.dartlang.org/articles/futures-and-error-handling/): Everything |
21 * you wanted to know about handling errors and exceptions when working with | 78 * you wanted to know about handling errors and exceptions when working with |
22 * Futures (but were afraid to ask). | 79 * Futures (but were afraid to ask). |
23 * | 80 * |
24 * * [The Event Loop and Dart](https://www.dartlang.org/articles/event-loop/): | 81 * * [The Event Loop and Dart](https://www.dartlang.org/articles/event-loop/): |
25 * Learn how Dart handles the event queue and microtask queue, so you can write | 82 * Learn how Dart handles the event queue and microtask queue, so you can write |
26 * better asynchronous code with fewer surprises. | 83 * better asynchronous code with fewer surprises. |
(...skipping 13 matching lines...) Expand all Loading... |
40 part 'future.dart'; | 97 part 'future.dart'; |
41 part 'future_impl.dart'; | 98 part 'future_impl.dart'; |
42 part 'schedule_microtask.dart'; | 99 part 'schedule_microtask.dart'; |
43 part 'stream.dart'; | 100 part 'stream.dart'; |
44 part 'stream_controller.dart'; | 101 part 'stream_controller.dart'; |
45 part 'stream_impl.dart'; | 102 part 'stream_impl.dart'; |
46 part 'stream_pipe.dart'; | 103 part 'stream_pipe.dart'; |
47 part 'stream_transformers.dart'; | 104 part 'stream_transformers.dart'; |
48 part 'timer.dart'; | 105 part 'timer.dart'; |
49 part 'zone.dart'; | 106 part 'zone.dart'; |
OLD | NEW |