Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update README and related docs #1933

Merged
merged 13 commits into from
May 16, 2023
7 changes: 7 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -194,3 +194,10 @@ nuget.exe
*.v3.ncrunchproject
*.v3.ncrunchsolution
/Rx.NET/Source/.NCrunch_*/StoredText

# Windows Store app package directories and files
AppPackages/
BundleArtifacts/
Package.StoreAssociation.xml
_pkginfo.txt
*.appx
6 changes: 5 additions & 1 deletion AUTHORS.txt
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,11 @@ Arthur Watson
Gert Drapers
Mark Shields
Eric Rozell
Oren Novotny
Claire Novotny
Geoffrey Huntley
David Karnok
Daniel C. Weber


Rx.js and Ix.js:
Matthew Podwysocki
Expand Down
52 changes: 52 additions & 0 deletions Ix.NET/Documentation/Museum/OldReadme.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,52 @@
# The pre-2023 README

By early 2023, the main README had become a bit of a dumping ground for information, most of which was at an inappropriate level of detail for someone visiting the repo for the first time to find out what it was about.

However, most of the information in there would be of some use to someone, so we've moved the more obscure bits out into this file so that they don't vanish entirely.

## A Brief Intro

(**Note:** none of this was untrue, but it focused on detail without really saying what Rx is actually for.)

The Reactive Extensions (Rx) is a library for composing asynchronous and event-based programs using observable sequences and LINQ-style query operators. Using Rx, developers *__represent__* asynchronous data streams with [Observables](https://docs.microsoft.com/dotnet/api/system.iobservable-1), *__query__* asynchronous data streams using [LINQ operators](http://msdn.microsoft.com/en-us/library/hh242983.aspx), and *__parameterize__* the concurrency in the asynchronous data streams using [Schedulers](http://msdn.microsoft.com/en-us/library/hh242963.aspx). Simply put, Rx = Observables + LINQ + Schedulers.

Whether you are authoring a traditional desktop or web-based application, you have to deal with asynchronous and event-based programming from time to time. Desktop applications have I/O operations and computationally expensive tasks that might take a long time to complete and potentially block other active threads. Furthermore, handling exceptions, cancellation, and synchronization is difficult and error-prone.

Using Rx, you can represent multiple asynchronous data streams (that come from diverse sources, e.g., stock quote, tweets, computer events, web service requests, etc.), and subscribe to the event stream using the `IObserver<T>` interface. The `IObservable<T>` interface notifies the subscribed `IObserver<T>` interface whenever an event occurs.

Because observable sequences are data streams, you can query them using standard LINQ query operators implemented by the Observable extension methods. Thus you can filter, project, aggregate, compose and perform time-based operations on multiple events easily by using these standard LINQ operators. In addition, there are a number of other reactive stream specific operators that allow powerful queries to be written. Cancellation, exceptions, and synchronization are also handled gracefully by using the extension methods provided by Rx.

Rx complements and interoperates smoothly with both synchronous data streams (`IEnumerable<T>`) and single-value asynchronous computations (`Task<T>`) as the following diagram shows:


<table>
<th></th><th>Single return value</th><th>Multiple return values</th>
<tr>
<td>Pull/Synchronous/Interactive</td>
<td>T</td>
<td>IEnumerable&lt;T&gt;</td>
</tr>
<tr>
<td>Push/Asynchronous/Reactive</td>
<td>Task&lt;T&gt;</td>
<td>IObservable&lt;T&gt;</td>
</tr>
</table>

Additional documentation, video, tutorials and HOL are available on [MSDN](https://docs.microsoft.com/en-us/previous-versions/dotnet/reactive-extensions/hh242985(v=vs.103)), on [*Introduction to Rx*](http://introtorx.com/), [*ReactiveX*](http://reactivex.io/), and [ReactiveUI](https://reactiveui.net/).


## Flavors of Rx

* __Rx.NET__: *(this repository)* The Reactive Extensions (Rx) is a library for composing asynchronous and event-based programs using observable sequences and LINQ-style query operators.
* [RxJS](https://github.com/ReactiveX/rxjs): The Reactive Extensions for JavaScript (RxJS) is a library for composing asynchronous and event-based programs using observable sequences and LINQ-style query operators in JavaScript which can target both the browser and Node.js.
* [RxJava](https://github.com/ReactiveX/RxJava): Reactive Extensions for the JVM – a library for composing asynchronous and event-based programs using observable sequences for the Java VM.
* [RxScala](https://github.com/ReactiveX/RxScala): Reactive Extensions for Scala – a library for composing asynchronous and event-based programs using observable sequences
* [RxCpp](https://github.com/Reactive-Extensions/RxCpp): The Reactive Extensions for Native (RxCpp) is a library for composing asynchronous and event-based programs using observable sequences and LINQ-style query operators in both C and C++.
* [RxPy](https://github.com/ReactiveX/RxPY): The Reactive Extensions for Python 3 (Rx.Py) is a set of libraries to compose asynchronous and event-based programs using observable collections and LINQ-style query operators in Python 3.


## Applications

* [Tx](https://github.com/Reactive-Extensions/Tx): a set of code samples showing how to use LINQ to events, such as real-time standing queries and queries on past history from trace and log files, which targets ETW, Windows Event Logs and SQL Server Extended Events.
* [LINQ2Charts](http://linq2charts.codeplex.com): an example for Rx bindings. Similar to existing APIs like LINQ to XML, it allows developers to use LINQ to create/change/update charts in an easy way and avoid having to deal with XML or other underneath data structures. We would love to see more Rx bindings like this one.
21 changes: 21 additions & 0 deletions Ix.NET/Documentation/ReleaseHistory/Ix.v5-and-before.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
# Ix Release History v5.0 and Older

In addition to the original `System.Interactive` library, and the `System.Interactive.Async` library that added the same functionality for `IAsyncEnumerable<T>`, the Ix.NET project also includes `System.Linq.Async`, which defines for `IAsyncEnumerable<T>` the same LINQ operators that are built into the .NET runtime libraries for `IEnumerable<T>`.

## V5.1

Removed various `IEnumerable<T>` min and max extension methods because .NET 6.0 now has built-in equivalents.

Fixed bug causing duplicate emissions from `Delay`.


## V5.0

`System.Linq.Async` adds support for C# 8.0's nullable reference types feature.


## v4.0

Ix Async 4.0 has a breaking change from prior versions due to `IAsyncEnumerable<T>` being added to the .NET runtime libraries. In earlier versions, Ix Async defined its own version of this interface, but v4.0 has been modified to use the definition now built into the runtime. This enables the `IAsyncEnumerable` implementations in Ix Async to be consumed by the [async streams](https://github.com/dotnet/roslyn/blob/master/docs/features/async-streams.md) language feature that was added in C# 8. This means for .NET Standard 2.1 and .NET Core 3 targets, we use the in-box interfaces for `IAsyncEnumerable<T>` and friends. On other platforms, we use the `IAsyncEnumerable` definition from `Microsoft.Bcl.AsyncInterfaces`, supplying a full implementation of the Rx-like LINQ operators Ix has long defined for `IEnumerable<T>`. The types will unify to the system ones where the platform provides it.

The .NET runtime libraries did not add a full LINQ to Objects implementation for `IAsyncEnumerable<T>`. Whereas `IEnumerable<T>` offers standard operators such as `Where`, `Single`, and `GroupBy`, enabling use of the LINQ query expression syntax, this is not available out of the box with .NET for `IAsyncEnumerable<T>`. Since earlier versions of this library had already done most of the relevant work to implement these operators on its pre-v4.0 version of `IAsyncEnumerable<T>`, v4.0 of Ix also builds the `System.Linq.Async` library, making LINQ to Objects available for `IAsyncEnumerable<T>`.
9 changes: 9 additions & 0 deletions Ix.NET/Documentation/ReleaseHistory/Ix.v6.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
# Ix Release History v6.0


## v6.0.1

First release with version number updated to v6.0.x. (At the time, Rx and Ix were attempting to follow a policy of keeping version numbers aligned with the .NET runtime libraries.)

Added `MinByWithTies` and `MaxByWithTies` to reinstate functionality that was lost in v5.1. (When .NET 6.0 added its own MinBy/MaxBy, Ix v5.1 removed its methods, but some of those did things the .NET 6.0 versions can't.)