AsyncEnumerator 4.0.2
dotnet add package AsyncEnumerator --version 4.0.2
NuGet\Install-Package AsyncEnumerator -Version 4.0.2
<PackageReference Include="AsyncEnumerator" Version="4.0.2" />
paket add AsyncEnumerator --version 4.0.2
#r "nuget: AsyncEnumerator, 4.0.2"
// Install AsyncEnumerator as a Cake Addin #addin nuget:?package=AsyncEnumerator&version=4.0.2 // Install AsyncEnumerator as a Cake Tool #tool nuget:?package=AsyncEnumerator&version=4.0.2
1: How to use this library?
See examples above. You can the core code and lots of useful extension methods in the Dasync.Collections
namespace.
2: Using CancellationToken
using Dasync.Collections;
IAsyncEnumerable<int> ProduceNumbers()
{
return new AsyncEnumerable<int>(async yield => {
await FooAsync(yield.CancellationToken);
});
}
3: Always remember about ConfigureAwait(false)
To avoid performance degradation and possible dead-locks in ASP.NET or WPF applications (or any SynchronizationContext
-dependent environment), you should always put ConfigureAwait(false)
in your await
statements:
using Dasync.Collections;
IAsyncEnumerable<int> GetValues()
{
return new AsyncEnumerable<int>(async yield =>
{
await FooAsync().ConfigureAwait(false);
// Yes, it's even needed for 'yield.ReturnAsync'
await yield.ReturnAsync(123).ConfigureAwait(false);
});
}
4: Clean-up on incomplete enumeration
Imagine such situation:
using Dasync.Collections;
IAsyncEnumerable<int> ReadValuesFromQueue()
{
return new AsyncEnumerable<int>(async yield =>
{
using (var queueClient = CreateQueueClient())
{
while (true)
{
var message = queueClient.DequeueMessageAsync();
if (message == null)
break;
await yield.ReturnAsync(message.Value);
}
}
});
}
Task<int> ReadFirstValueOrDefaultAsync()
{
return ReadValuesFromQueue().FirstOrDefaultAsync();
}
The FirstOrDefaultAsync
method will try to read first value from the IAsyncEnumerator
, and then will just dispose it. However, disposing AsyncEnumerator
does not mean that the queueClient
in the lambda function will be disposed automatically as well, because async methods are just state machines which need somehow to go to a particular state to do the clean-up.
To provide such behavior, when you dispose an AsyncEnumerator
before you reach the end of enumeration, it will tell to resume your async lambda function (at await yield.ReturnAsync()
) with the AsyncEnumerationCanceledException
(derives from OperationCanceledException
). Having such exception in your lambda method will break normal flow of enumeration and will go to terminal state of the underlying state machine, what will do the clean-up, i.e. dispose the queueClient
in this case. You don't need (and shouldn't) catch that exception type, because it's handled internally by AsyncEnumerator
. The same exception is thrown when you call yield.Break()
.
There is another option to do the cleanup on Dispose
:
using Dasync.Collections;
IAsyncEnumerator<int> GetQueueEnumerator()
{
var queueClient = CreateQueueClient();
return new AsyncEnumerable<int>(async yield =>
{
while (true)
{
var message = queueClient.DequeueMessageAsync();
if (message == null)
break;
await yield.ReturnAsync(message.Value);
}
},
onDispose: () => queueClient.Dispose());
}
5: Why is GetAsyncEnumeratorAsync async?
The IAsyncEnumerable.GetAsyncEnumeratorAsync()
method is async and returns a Task<IAsyncEnumerator>
, where the current implementation of AsyncEnumerable
always runs that method synchronously and just returns an instance of AsyncEnumerator
. Having interfaces allows you to do your own implementation, where classes mentioned above are just helpers. The initial idea was to be able to support database-like scenarios, where GetAsyncEnumeratorAsync()
executes a query first (what internally returns a pointer), and the MoveNextAsync()
enumerates through rows (by using that pointer).
6: Returning IAsyncEnumerable vs IAsyncEnumerator
When you implement a method that returns an async-enumerable collection you have a choice to return either IAsyncEnumerable
or IAsyncEnumerator
- the constructors of the helper classes AsyncEnumerable
and AsyncEnumerator
are absolutely identical. Both interfaces have same set of useful extension methods, like ForEachAsync
.
When you create an 'enumerable', you create a factory that produces 'enumerators', i.e. you can enumerate through a collection many times. On the other hand, creating an 'enumerator' is needed when you can through a collection only once.
7: Where is Reset or ResetAsync?
The Reset
method must not be on the IEnumerator
interface, and should be considered as deprecated. Create a new enumerator instead. This is the reason why the 'oneTimeUse' flag was removed in version 2 of this library.
8: How can I do synchronous for-each enumeration through IAsyncEnumerable?
You can use extension methods like IAsyncEnumerable.ToEnumerable()
to use built-in foreach
enumeration, BUT you should never do that! The general idea of this library is to avoid thread-blocking calls on worker threads, where converting an IAsyncEnumerable
to IEnumerable
will just defeat the whole purpose of this library. This is the reason why such synchronous extension methods are marked with [Obsolete]
attribute.
9: What's the difference between ForEachAsync and ParallelForEachAsync?
The ForEachAsync
allows you to go through a collection and perform an action on every single item in sequential manner. On the other hand, ParallelForEachAsync
allows you to run the action on multiple items at the same time where the sequential
order of completion is not guaranteed. For the latter, the degree of the parallelism is controlled by the maxDegreeOfParalellism
argument, however it does not guarantee to spin up the exact amount of threads, because it depends on the thread pool size and its occupancy at a moment of time. Such parallel approach is much better than trying to create a task for an action for every single item on the collection and then awaiting on all of them with Task.WhenAll
, because it adds less overhead to the runtime, better with memory usage, and helps with throttling-sensitive scenarios.
Product | Versions Compatible and additional computed target framework versions. |
---|---|
.NET | net5.0 was computed. net5.0-windows was computed. net6.0 was computed. net6.0-android was computed. net6.0-ios was computed. net6.0-maccatalyst was computed. net6.0-macos was computed. net6.0-tvos was computed. net6.0-windows was computed. net7.0 was computed. net7.0-android was computed. net7.0-ios was computed. net7.0-maccatalyst was computed. net7.0-macos was computed. net7.0-tvos was computed. net7.0-windows was computed. net8.0 was computed. net8.0-android was computed. net8.0-browser was computed. net8.0-ios was computed. net8.0-maccatalyst was computed. net8.0-macos was computed. net8.0-tvos was computed. net8.0-windows was computed. |
.NET Core | netcoreapp1.0 was computed. netcoreapp1.1 was computed. netcoreapp2.0 was computed. netcoreapp2.1 was computed. netcoreapp2.2 was computed. netcoreapp3.0 was computed. netcoreapp3.1 was computed. |
.NET Standard | netstandard1.4 is compatible. netstandard1.5 was computed. netstandard1.6 was computed. netstandard2.0 is compatible. netstandard2.1 is compatible. |
.NET Framework | net45 is compatible. net451 was computed. net452 was computed. net46 was computed. net461 is compatible. net462 was computed. net463 was computed. net47 was computed. net471 was computed. net472 was computed. net48 was computed. net481 was computed. |
MonoAndroid | monoandroid was computed. |
MonoMac | monomac was computed. |
MonoTouch | monotouch was computed. |
Tizen | tizen30 was computed. tizen40 was computed. tizen60 was computed. |
Universal Windows Platform | uap was computed. uap10.0 was computed. |
Xamarin.iOS | xamarinios was computed. |
Xamarin.Mac | xamarinmac was computed. |
Xamarin.TVOS | xamarintvos was computed. |
Xamarin.WatchOS | xamarinwatchos was computed. |
-
.NETFramework 4.5
- System.Threading.Tasks.Extensions (>= 4.5.0)
-
.NETFramework 4.6.1
- Microsoft.Bcl.AsyncInterfaces (>= 1.0.0)
- System.Threading.Tasks.Extensions (>= 4.5.2)
-
.NETStandard 1.4
- System.Threading.Tasks.Extensions (>= 4.5.0)
-
.NETStandard 2.0
- Microsoft.Bcl.AsyncInterfaces (>= 1.0.0)
- System.Threading.Tasks.Extensions (>= 4.5.2)
-
.NETStandard 2.1
- No dependencies.
NuGet packages (46)
Showing the top 5 NuGet packages that depend on AsyncEnumerator:
Package | Downloads |
---|---|
NBitcoin.Indexer
Library for querying data indexed by NBitcoin.Indexer on Azure Storage |
|
Elect.Core
.Net Core Utilities methods |
|
Carbon.Kit
Provides interfaces, abstractions and common functions which is the essence of Carbon Kit. |
|
Libplanet.Net
A peer-to-peer networking layer based on Libplanet. |
|
Halforbit.RecordStreams
Package Description |
GitHub repositories (10)
Showing the top 5 popular GitHub repositories that depend on AsyncEnumerator:
Repository | Stars |
---|---|
Flangvik/TeamFiltration
TeamFiltration is a cross-platform framework for enumerating, spraying, exfiltrating, and backdooring O365 AAD accounts
|
|
n00mkrad/text2image-gui
Somewhat modular text2image GUI, initially just for Stable Diffusion
|
|
RevoLand/Steam-Library-Manager
Open source utility to manage Steam, Origin and Uplay libraries in ease of use with multi library support. ||| Steam Games Database: https://stmstat.com
|
|
planetarium/libplanet
Blockchain in C#/.NET for on-chain, decentralized gaming
|
|
Texnomic/SecureDNS
Secure, Modern, Fully-Featured, All-In-One Cross-Architecture & Cross-Platform DNS Server Using .NET 8.0
|
Version | Downloads | Last updated |
---|---|---|
4.0.2 | 16,489,192 | 12/4/2019 |
4.0.1 | 186,348 | 10/22/2019 |
4.0.0 | 47,499 | 10/18/2019 |
3.1.0 | 139,604 | 9/23/2019 |
2.2.2 | 2,243,885 | 1/27/2019 |
2.2.1 | 1,479,484 | 5/29/2018 |
2.2.0 | 47,722 | 5/18/2018 |
2.1.1 | 1,197,655 | 1/20/2018 |
2.1.0 | 332,991 | 5/22/2017 |
2.0.1 | 60,302 | 2/13/2017 |
1.5.0 | 6,481 | 2/12/2017 |
1.4.2 | 4,111 | 2/6/2017 |
1.3.0 | 4,242 | 1/20/2017 |
1.2.3 | 10,870 | 1/6/2017 |
1.2.2 | 4,807 | 12/11/2016 |
1.2.1 | 3,246 | 12/10/2016 |
1.2.0 | 22,391 | 11/29/2016 |
1.1.3 | 3,440 | 11/28/2016 |
1.1.2 | 52,133 | 8/29/2016 |
1.0.3 | 6,637 | 4/28/2016 |
4.0.0: Use interfaces from Microsoft.Bcl.AsyncInterfaces package in NET Standard 2.0.
3.1.0: Add support for NET Standard 2.1, consolidate interface with Microsoft's implementation.
2.2.0: New extension methods: SelectMany, Append, Prepend, OfType, Concat, Distinct, ToDictionaryAsync, ToLookupAsync, AggregateAsync.
2.1.0: New extension methods: Batch, UnionAll, Single, SingleOrDefault, DefaultIfEmpty, Cast.
2.0.0: Revise design of the library: same features, but slight paradigm shift and interface breaking changes.
1.5.0: Add support for .NET Standard, minor improvements.
1.4.2: Add finalizer to AsyncEnumerator and call Dispose in ForEachAsync and ParallelForEachAsync extension methods.
1.4.0: Add new generic type AsyncEnumeratorWithState for performance optimization.
Now IAsyncEnumerator<T> is covariant.
Add ForEachAsync, ParallelForeachAsync, and LINQ-style extension methods for IAsyncEnumerator.
1.2.1: New Linq-style extension methods in System.Collections.Async namespace.
1.1.0: Add ParallelForEachAsync extension methods for IEnumerable<T> and IAsyncEnumerable<T> in System.Collections.Async namespace.