-
Notifications
You must be signed in to change notification settings - Fork 1.6k
/
async.dart
131 lines (128 loc) · 5.02 KB
/
async.dart
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
// Copyright (c) 2012, 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.
/// Support for asynchronous programming,
/// with classes such as Future and Stream.
///
/// [Future]s and [Stream]s are the fundamental building blocks
/// of asynchronous programming in Dart. They are supported
/// directly in the language through `async` and `async*`
/// functions, and are available to all libraries through
/// the `dart:core` library.
///
/// This library provides further tools for creating, consuming
/// and transforming futures and streams, as well as direct access to
/// other asynchronous primitives like [timers][Timer],
/// [microtasks][scheduleMicrotask] and [zones][Zone].
///
/// To use this library in your code:
/// ```dart
/// import 'dart:async';
/// ```
/// ## Future
///
/// A Future object represents a computation whose return value
/// might not yet be available.
/// The Future returns the value of the computation
/// when it completes at some time in the future.
/// Futures are often used for potentially lengthy computations
/// such as I/O and interaction with users.
///
/// Many methods in the Dart libraries return `Future`s when
/// performing tasks. For example, when binding an `HttpServer`
/// to a host and port, the `bind()` method returns a Future.
/// ```dart
/// HttpServer.bind('127.0.0.1', 4444)
/// .then((server) => print('${server.isBroadcast}'))
/// .catchError(print);
/// ```
/// [Future.then] registers a callback function that runs
/// when the Future's operation, in this case the `bind()` method,
/// completes successfully.
/// The value returned by the operation
/// is passed into the callback function.
/// In this example, the `bind()` method returns the HttpServer
/// object. The callback function prints one of its properties.
/// [Future.catchError] registers a callback function that
/// runs if an error occurs within the Future.
///
/// ## Stream
///
/// A Stream provides an asynchronous sequence of data.
/// Examples of data sequences include individual events, like mouse clicks,
/// or sequential chunks of larger data, like multiple byte lists with the
/// contents of a file
/// such as mouse clicks, and a stream of byte lists read from a file.
/// The following example opens a file for reading.
/// [Stream.listen] registers callback functions that run
/// each time more data is available, an error has occurred, or
/// the stream has finished.
/// Further functionality is provided on [Stream], implemented by calling
/// [Stream.listen] to get the actual data.
/// ```dart
/// Stream<List<int>> stream = File('quotes.txt').openRead();
/// stream.transform(utf8.decoder).forEach(print);
/// ```
/// This stream emits a sequence of lists of bytes.
/// The program must then handle those lists of bytes in some way.
/// Here, the code uses a UTF-8 decoder (provided in the `dart:convert` library)
/// to convert the sequence of bytes into a sequence
/// of Dart strings.
///
/// Another common use of streams is for user-generated events
/// in a web app: The following code listens for mouse clicks on a button.
/// ```dart
/// querySelector('#myButton').onClick.forEach((_) => print('Click.'));
/// ```
/// ## Other resources
///
/// * The [dart:async section of the library tour][asynchronous-programming]:
/// A brief overview of asynchronous programming.
///
/// * [Use Future-Based APIs][futures-tutorial]: A closer look at Futures and
/// how to use them to write asynchronous Dart code.
///
/// * [Futures and Error Handling][futures-error-handling]: Everything you
/// wanted to know about handling errors and exceptions when working with
/// Futures (but were afraid to ask).
///
/// * [The Event Loop and Dart](https://dart.dev/articles/event-loop/):
/// Learn how Dart handles the event queue and microtask queue, so you can
/// write better asynchronous code with fewer surprises.
///
/// * [test package: Asynchronous Tests][test-readme]: How to test asynchronous
/// code.
///
/// [asynchronous-programming]: https://dart.dev/guides/libraries/library-tour#dartasync---asynchronous-programming
/// [futures-tutorial]: https://dart.dev/codelabs/async-await
/// [futures-error-handling]: https://dart.dev/guides/libraries/futures-error-handling
/// [test-readme]: https://pub.dev/packages/test
///
/// {@category Core}
library dart.async;
import "dart:collection" show HashMap;
import "dart:_internal"
show
CastStream,
CastStreamTransformer,
checkNotNullable,
EmptyIterator,
IterableElementError,
nullFuture,
printToZone,
printToConsole,
Since,
typeAcceptsNull;
part 'async_error.dart';
part 'broadcast_stream_controller.dart';
part 'deferred_load.dart';
part 'future.dart';
part 'future_impl.dart';
part 'schedule_microtask.dart';
part 'stream.dart';
part 'stream_controller.dart';
part 'stream_impl.dart';
part 'stream_pipe.dart';
part 'stream_transformers.dart';
part 'timer.dart';
part 'zone.dart';