Getting Started

Add the package, then use Icicle in each file that needs a scope,

dotnet add package Icicle
using Icicle;

A TaskScope is created with one of the When... factories.

A fully parallel scope looks like this,


// within a using block, create a scope and configure it
using TaskScope scope = new TaskScope.WhenAll(); // run all tasks at the same time
// now add tasks to the scope to run
ResultHandle t1 = scope.Add(async ct => await Task.Delay(TimeSpan.FromSeconds(1), ct));
ResultHandle t2 = scope.Add(async ct => await Task.Delay(TimeSpan.FromSeconds(1), ct));
ResultHandle t3 = scope.Add(async ct => await Task.Delay(TimeSpan.FromSeconds(1), ct));
// now run them all; should run for around a second
RunToken token = await scope.Run();

Values can also be returned from the added tasks,


using TaskScope scope = new TaskScope.WhenAll();
// added tasks
ResultHandle<string> t1 = scope.Add(async ct =>
{
    await Task.Delay(TimeSpan.FromSeconds(1), ct);
    return "Hello";
});
ResultHandle<string> t2 = scope.Add(async ct =>
{
    await Task.Delay(TimeSpan.FromSeconds(1), ct);
    return "World";
});
// now run them all; should run for around a second
var token = await scope.Run();
// set the value to "Hello World"
Assert.Equal("Hello World", $"{t1.Value(token)} {t2.Value(token)}");

The usage rules for TaskScope are as follows,

  1. Add can be called as many times as required up until Run has completed (nested calls to Add are supported)

    
    using TaskScope scope = new TaskScope.WhenAll();
    // keep adding
    ResultHandle t1 = scope.Add(async ct => await Task.Delay(TimeSpan.FromSeconds(1), ct));
    ResultHandle t2 = scope.Add(async ct => await Task.Delay(TimeSpan.FromSeconds(1), ct));
    ResultHandle t3 = scope.Add(async ct =>
    {
        await Task.Delay(TimeSpan.FromSeconds(1), ct);
        // and nest as well
        _ = scope.Add(async ct => await Task.Delay(TimeSpan.FromSeconds(1), ct));
    });
    // run them
    RunToken token = await scope.Run();
    // cannot call Add or Run from this point on
    Assert.Throws<TaskScopeCompletedException>(() =>
        scope.Add(async ct => await Task.Delay(TimeSpan.FromSeconds(1), ct))
    );
    
    
  2. Run can only be called once, and nothing runs until it is

The rules above give the scope these semantics,

  • No child task starts until Run is called, and each one then follows the execution rules of the scope and its configuration. A windowSize passed to TaskScope.WhenAll for example runs at most windowSize tasks at a time

  • A fault in any child task cancels the scope

  • Cancellation only reaches tasks that have started; tasks that have not started never do

  • Values are read from ResultHandle<T> and ResultHandle after Run returns

    
    using TaskScope scope = new TaskScope.WhenAll();
    ResultHandle<string> t1 = scope.Add(async ct =>
    {
        await Task.Delay(TimeSpan.FromSeconds(1), ct);
        return "Hello";
    });
    RunToken token = await scope.Run(); // get token here
    string result = t1.Value(
        // pass it here
        token
    );
    Assert.Equal("Hello", result);