firka/flutter
firka/flutter
4
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Reorganize compute docs and add sample code (#100253)

Browse Source
This commit is contained in:
Michael Goderbauer 2022-03-17 18:45:21 -07:00 committed by GitHub
parent 7c73053f70
commit 3d46ab920b
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 61 additions and 32 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

93
packages/flutter/lib/src/foundation/isolates.dart
View File

@ -11,44 +11,83 @@ import '_isolates_io.dart'
///
/// {@macro flutter.foundation.compute.types}
///
/// Instances of [ComputeCallback] must be sendable between isolates i.e.
/// top-level functions, static methods or a closures that only capture objects
/// sendable between isolates or an instance methods which instance properties
/// are also sendable.
/// Instances of [ComputeCallback] must be functions that can be sent to an
/// isolate.
/// {@macro flutter.foundation.compute.callback}
///
/// {@macro flutter.foundation.compute.closure.note}
///
/// {@macro flutter.foundation.compute.limitations}
/// {@macro flutter.foundation.compute.types}
typedef ComputeCallback<Q, R> = FutureOr<R> Function(Q message);
/// The signature of [compute], which spawns an isolate, runs `callback` on
/// that isolate, passes it `message`, and (eventually) returns the value
/// returned by `callback`.
///
/// {@macro flutter.foundation.compute.usecase}
///
/// The function used as `callback` must be one that can be sent to an isolate.
/// {@macro flutter.foundation.compute.callback}
///
/// {@macro flutter.foundation.compute.types}
///
/// The `debugLabel` argument can be specified to provide a name to add to the
/// [Timeline]. This is useful when profiling an application.
typedef ComputeImpl = Future<R> Function<Q, R>(ComputeCallback<Q, R> callback, Q message, { String? debugLabel });
/// A function that spawns an isolate and runs the provided `callback` on that
/// isolate, passes it the provided `message`, and (eventually) returns the
/// value returned by `callback`.
///
/// {@template flutter.foundation.compute.usecase}
/// This is useful for operations that take longer than a few milliseconds, and
/// which would therefore risk skipping frames. For tasks that will only take a
/// few milliseconds, consider [SchedulerBinding.scheduleTask] instead.
/// {@endtemplate}
///
/// {@youtube 560 315 https://www.youtube.com/watch?v=5AxWC49ZMzs}
///
/// {@tool snippet}
/// The following code uses the [compute] function to check whether a given
/// integer is a prime number.
///
/// ```dart
/// Future<bool> isPrime(int value) {
/// return compute(_calculate, value);
/// }
///
/// bool _calculate(int value) {
/// if (value == 1) {
/// return false;
/// }
/// for (int i = 2; i < value; ++i) {
/// if (value % i == 0) {
/// return false;
/// }
/// }
/// return true;
/// }
/// ```
/// {@end-tool}
///
/// The function used as `callback` must be one that can be sent to an isolate.
/// {@template flutter.foundation.compute.callback}
/// Qualifying functions include:
///
/// * top-level functions
/// * static methods
/// * closures that only capture objects that can be sent to an isolate
///
/// Using closures must be done with care. Due to
/// [dart-lang/sdk#36983](https://github.com/dart-lang/sdk/issues/36983) a
/// closure may captures objects that, while not directly used in the closure
/// itself, may prevent it from being sent to an isolate.
/// {@endtemplate}
///
/// {@template flutter.foundation.compute.types}
/// The [compute] method accepts the following parameters:
///
/// * `Q` is the type of the message that kicks off the computation.
///
/// * `R` is the type of the value returned.
/// {@endtemplate}
///
/// The `callback` must be sendable between isolates i.e. a top-level function,
/// static method or a closure that only captures objects sendable between
/// isolates or an instance method which instance properties are also sendable.
///
/// {@template flutter.foundation.compute.closure.note}
/// However, using arbitrary closures should be done with great care because
/// it may be that the closure captures more variables than initially thought.
/// See the underlying [dart-lang/sdk#36983](https://github.com/dart-lang/sdk/issues/36983)
/// issue.
/// {@endtemplate}
///
/// {@template flutter.foundation.compute.limitations}
/// There are limitations on the values that can be sent and received to and
/// from isolates. These limitations constrain the values of `Q` and `R` that
/// are possible. See the discussion at [SendPort.send].
@ -56,17 +95,7 @@ typedef ComputeCallback<Q, R> = FutureOr<R> Function(Q message);
/// The same limitations apply to any errors generated by the computation.
/// {@endtemplate}
///
/// The `debugLabel` argument can be specified to provide a name to add to the
/// [Timeline]. This is useful when profiling an application.
typedef ComputeImpl = Future<R> Function<Q, R>(ComputeCallback<Q, R> callback, Q message, { String? debugLabel });
/// A function that spawns an isolate and runs a callback on that isolate. This
/// method should be used to execute parallel tasks that reduce the risk of
/// skipping frames.
///
/// {@youtube 560 315 https://www.youtube.com/watch?v=5AxWC49ZMzs}
///
/// See also:
///
/// * [ComputeImpl], for function parameters and usage details.
/// * [ComputeImpl], for the [compute] function's signature.
const ComputeImpl compute = isolates.compute;