Future - Async Control

Essential utilities for mastering asynchronous code: implement automatic retries, set fallbacks for timeouts, and manage execution delays.

1. 🔁 Retry & Time Control

   retry() · Future<T>

   retries · int · required

   The total number of attempts to make before giving up.

   Show Parameters

   retries · int · required

   The total number of attempts to make before giving up.

   delay · Duration · default: "Duration.zero"

   The duration to wait between failed attempts.

   Retries the execution of this Future a specified number of times upon failure. Essential for handling transient network errors.

   // Retries the network call up to 3 times
   final data = await fetchUserData().retry(3, delay: 1.seconds);
   

   timeoutWithFallback() · Future<T>

   timeout · Duration · required

   The maximum duration to wait for the Future to complete.

   fallbackValue · T · required

   The value to return if the Future times out.

   Sets a timeout and provides a fallbackValue to return if the Future fails to complete in time.

   // Returns 0 if the computation takes longer than 5 seconds.
   final result = await complexCalculation()
       .timeoutWithFallback(Duration(seconds: 5), 0);
   

   runAfterDelay() · Future<T>

   delay · Duration · required

   The duration to wait before execution begins.

   Waits for a specified delay before starting the execution of this Future. Useful for simulating network latency in dev/testing.

   // Simulate a slow network with a 2-second minimum delay.
   final data = await fetchSettings().runAfterDelay(Duration(seconds: 2));
   

2. 🔍 Internal Status

   isComplete() · bool

   Checks if the Future has completed (either successfully or with an error). Note: This method starts the Future execution if it hasn’t begun.

   Futures

   final myFuture = Future.delayed(Duration(seconds: 2), () => 42);
   print(myFuture.isComplete()); // false (initially)
   

   wrapInCompleter() · Completer<T>

   Wraps this Future inside a Completer. An internal utility for managing Future state within other asynchronous flows.

   Futures

   final completer = someFuture.wrapInCompleter();