Amb, Materialize and Dematerialize

Paul blogs about our lack of in depth documentation on some cryptic api names.

So here is some description of the names and behavior of Amb, Materialize and Dematerialize.

Amb's name comes from a long history, it was named by John McCarthy the inventor of LISP in 1961. It stands for Ambiguous, meaning that the result can be either of the passed in values. In our case it is actually not 100% ambiguous as we return the first to ever produce a value.

As for the Materialize and Dematerialize operators, these operators convert an IObservable<T> to and IObservable<Notification<T>> and back. If you look at Notification<T> you can see that it has a kind and a value property. The kind can be one of three values OnNext, OnError and OnCompleted. These map exactly to the 3 different values an Observable/Observer pair can contain. Now what Materialize does it takes the values from each of the 3 different streams in the IObservable and represents each of these as Notifications of that value and reposts them on the OnNext stream.

Now you might want to ask why you would need these operators and it turns out that these operators are very usefull for implementing other operators. e.g. for the implementation of Replay. Replay caches each and every value in the source observable and plays all values back the moment somebody subscribes to the output observable. We could have written this with 3 queues, a queue for each of the 3 streams, but that makes the logic very hard to maintain as we need to make sure everything is replayed in the right order. By calling Materialize on the source observable, we now only have to maintain one queue: a Queue of Notifications.

If you are writing your own operator and find it hard to deal with the exception and completed cases, chances are that Materialize/Dematerialize can help you.

On a side note, System.Interactive ships Amb, and Materialize/Dematerialize for Enumerable as well, where they are just as useful.

Hope this explains these cryptic operators. 

Update 1: fixed missing text, added some more details.