Catch me on twitter @jvgogh to keep in touch.

Thanks,

Jeffrey 

(Reposted due to layout issues)

Previously in these series we saw:

• Reading a stream asynchronously
• Reading strings asynchronously, line by line
• Writing an observable to a stream
• Buffering output to a stream

All previous posts dealt with interacting between observable and IO Streams. Next in these series, we’re going to take a look at a place we could use these operations in a real server appication: ASP.NET.

IHttpHandler

ASP.NET provides a lot of functionality to make building webpages easy. This functionality can be grouped into different layers. At the bottom layer lies the technology that we’re going to focus in this post:
IHttpHandler.

IHttpHandler is the base interface that is used to expose request to the webserver to ASP.NET. It comes in two flavors: IHttpHandler and IHttpAsyncHandler.

The reason for having the second version is exactly as described in the beginning of these series: scaling a webserver doesn’t work when blocking a whole thread for a single response.
In most webserver scenarios, a request will face many delays that are not processor bound, e.g.:

• Reading a file from (remote) disk
• Accessing a database

As such, implementing IHttpAsyncHandler is often the best way to go.

Unfortunately, implementations of this interface can get very nasty. The interface itself follows the begin/end invoke pattern and when making multiple asynchronous calls as described above, coordinating these calls can get a nightmare.

Let’s see if we can improve on this pattern.

ObservableHttpHandler

At heart of this interface is the following set of operations:

• For each request send to a specified URL of the webserver, a method is called that will be responsible for processing this request.
• This method will receive an HttpContext object. This object provides information on the request and allows the method to send a response.
• The method can spin up any amount of asynchronous work to process the request.
• Once all asynchronous work is done and the response is sent, the method needs to signal it is done processing the request.

In the Rx world, this can be modeled as follows:

    public IObservable<Unit> ProcessRequestAsObservable(HttpContext context)

As ASP.NET doesn’t know about this pattern, we’ll have to convert between the Asynchronous pattern it knows about (IHttpAsyncHandler) and the pattern we prefer.

We’ll create an abstract base class that will do this work for us.

First, we’ll implement the IHttpAsyncHandler interface. We’ll do this explicitly so these methods don’t show up in our public API surface.

    public abstract class ObservableHttpHandler : IHttpAsyncHandler
    {
        public abstract IObservable<Unit> ProcessRequestAsObservable(HttpContext context);

        IAsyncResult IHttpAsyncHandler.BeginProcessRequest(HttpContext context,
            AsyncCallback cb, object extraData)
        {
            ...
        }

        void IHttpAsyncHandler.EndProcessRequest(IAsyncResult result)
        {
            ...
        }

        bool IHttpHandler.IsReusable
        {
            get { ... }
        }

        void IHttpHandler.ProcessRequest(HttpContext context)
        {
            ...
        }
    }

Let’s see how to implement these methods. We’ll start with the methods that IHttpAsyncHandler inherits from IHttpHandler:

IsReusable: return true as we don’t plan to maintain state in this class.

ProcessRequest: the method that is called if the request has to be processed synchronously. We will forward to the asynchronous version and block until the work has completed:

    void IHttpHandler.ProcessRequest(HttpContext context)
    {
        var gate = new ManualResetEvent(false);
        AsyncCallback cb = (_ => gate.Set());
        ((IHttpAsyncHandler)this).BeginProcessRequest(context, cb, null);
        gate.WaitOne();
    }

AsyncResult

As the BeginProcessRequest method follows the begin/endinvoke pattern, we’ll have to return something that implements the IAsyncResult interface. So let’s start off with a simple implementation of this interface:

    private class SimpleAsyncResult : IAsyncResult
    {
        private readonly ManualResetEvent asyncWaitHandler;
        private Exception exception;

        public SimpleAsyncResult(object asyncState)
        {
            AsyncState = asyncState;
            asyncWaitHandler = new ManualResetEvent(false);
        }

        public object AsyncState
        {
            get; private set;
        }

        public WaitHandle AsyncWaitHandle
        {
            get { return asyncWaitHandler; }
        }

        public bool CompletedSynchronously
        {
            get { return false; }
        }

        public bool IsCompleted
        {
            get;
            private set;
        }

        internal void Success()
        {
            Complete();
        }

        internal void Fail(Exception exception)
        {
            this.exception = exception;
            Complete();
        }

        private void Complete()
        {
            IsCompleted = true;
            asyncWaitHandler.Set();
        }

        internal void CheckResult()
        {
            if (exception != null)
                throw exception;
        }
    }

SimpleAsyncResult will allow us to communicate to ASP.NET that the request has finished processing as well as pass along any exception that happened along the way.

UPDATE: After posting this post, my coworker Stephen Toub from the TPL team pointed out, that instead of implementing SimpleAsyncResult, we could have reused Task as it also implements IAsyncResult.
I’ll leave it up as an exercise for the reader to do this.

BeginProcessRequest

The first thing we’ll do in BeginProcessRequest is to create an instance of this new class:

    var asyncResult = new SimpleAsyncResult(extraData); 

Next we need to know how to kick off the computation. We’ll call the ProcessRequestAsObservable method and store the observable:

    var observable = ProcessRequestAsObservable(context);

Now it is time to kick off the computation by subscribing to the observable. As the observable only contains Unit values, we only care about completion either success or failure:

    observable.Subscribe(
        _ => { },
        e=>
        {
            asyncResult.Fail(e);
            cb(asyncResult);
        },
        () =>
        {
            asyncResult.Success();
            cb(asyncResult);
        });

In both cases, we signal completion to the SimpleAsyncResult and call the callback that ASP.NET provided us. In the case of failure, we do provide the SimpleAsyncResult with the exception that occurred.
Finally we’ll return the SimpleAsyncResult object back to ASP.NET:

    return asyncResult;

EndProcessRequest

As the exception is now stuck as instance state in the SimpleAsyncResult instance, we’ll need to provide ASP.NET with a way to get the exception out of there. This is done by implementing the EndProcessRequest method:

    ((SimpleAsyncResult) result).CheckResult(); 

Complete Implementation

With that the complete implementation of ObservableHttpHandler is:

    public abstract class ObservableHttpHandler : IHttpAsyncHandler
    {
        public abstract IObservable<Unit> ProcessRequestAsObservable(HttpContext context);

        IAsyncResult IHttpAsyncHandler.BeginProcessRequest(HttpContext context,
            AsyncCallback cb, object extraData)
        {
            var asyncResult = new SimpleAsyncResult(extraData);
            var observable = ProcessRequestAsObservable(context);
            observable.Subscribe(
                _ => { },
                e =>
                {
                    asyncResult.Fail(e);
                    cb(asyncResult);
                },
                () =>
                {
                    asyncResult.Success();
                    cb(asyncResult);
                });
            return asyncResult;
        }

        void IHttpAsyncHandler.EndProcessRequest(IAsyncResult result)
        {
            ((SimpleAsyncResult)result).CheckResult();
        }

        bool IHttpHandler.IsReusable
        {
            get { return true; }
        }

        void IHttpHandler.ProcessRequest(HttpContext context)
        {
            var gate = new ManualResetEvent(false);
            AsyncCallback cb = (_ => gate.Set());
            ((IHttpAsyncHandler)this).BeginProcessequest(context, cb, null);
            gate.WaitOne();
        }

        private class SimpleAsyncResult : IAsyncResult
        {
            private readonly ManualResetEvent asyncWaitHandler;
            private Exception exception;

            public SimpleAsyncResult(object asyncState)
            {
                AsyncState = asyncState;
                asyncWaitHandler = new ManualResetEvent(false);
            }

            public object AsyncState
            {
                get;
                private set;
            }

            public WaitHandle AsyncWaitHandle
            {
                get { return asyncWaitHandler; }
            }

            public bool CompletedSynchronously
            {
                get { return false; }
            }

            public bool IsCompleted
            {
                get;
                private set;
            }

            internal void Success()
            {
                Complete();
            }

            internal void Fail(Exception exception)
            {
                this.exception = exception;
                Complete();
            }

            private void Complete()
            {
                IsCompleted = true;
                asyncWaitHandler.Set();
            }
 
            internal void CheckResult()
            {
                if (exception != null)
                    throw exception;
            }
        }
    }

Usage

Now that the implementation is done, it is time to take a look how we would use this new base class:

Imagine an HttpHandler that will asynchronously read in a big movie file, e.g. in 1mb chunks and sends each chunk to the client asynchronously:

    public class BigVideoHandler : ObservableHttpHandler
    {
        public override IObservable<System.Unit> ProcessRequestAsObservable(HttpContext context)
        {
            var fs = new FileStream(@"d:\videos\video1.wmv", FileMode.Open,
                FileAccess.Read, FileShare.Read, 2 << 19, true);
            context.Response.ContentType = "video/x-ms-wmv";
            return fs.AsyncRead(2 << 19).WriteToStream(context.Response.OutputStream);
        }
    }

NOTE: To use this HTTP Handler, it needs to be registered with the webserver. As this is different per webserver, please read this MSDN article on how to do so.

Even though many asynchronous operations are going on here, the code still looks very concise. The code inside ProcessRequestAsObservable can use any IObservable implementation and any of the Rx operators to orchestrate many asynchronous operations.

What’s next

The HttpHandler pattern is very powerful; it can be used to represent nearly any kind of HTTP request. As it is very low on the stack though, you’ll have to do a lot of manual work. Next in these series we’ll take a look how Rx can help out asynchronous programming in ASP.NET MVC.

• Reading a stream asynchronously
• Reading strings asynchronously, line by line
• Writing an observable to a stream

The last post finished with a warning regarding sending to many small chunks of data to the stream asynchronously.

In this post we’ll take a look at avoiding that problem by buffering the stream until a minimum size has been reached.

Signature & Pattern

As our WriteToStream method expects a IObservable<byte[]> as its input, our transformation is going to go from IObservable<byte[]> to IObservable<byte[]>:

    public static IObservable<byte[]> MinimumBuffer(this IObservable<byte[]> source,

        int bufferSize)

We’re going to be working on an existing observable and produce a new observable out of that. So this is a good fit for the Observable.CreateWithDisposable pattern:

    return Observable.CreateWithDisposable<byte[]>(observer =>

    {

        … 
    }     

Requirements

Let’s look at the task at hand, there are a couple of things we need to do:

• Subscribe to the original observable
• Handle OnNext messages

• Add the message to a buffer
• Fire out a new array based on the content of the buffer when buffer becomes bigger than bufferSize
• Clear the buffer

• Send through OnError messages immediately
• Complete the stream, sending out any remaining data in the buffer on an OnCompleted message.
• Return a disposable object that will unsubscribe the original subscription.

Implementation

As we need a buffer that can be accessed through out the subscription, we begin our observable.CreateWithDisposable body with allocating a list to hold that buffer:

    var data = new List<byte>();

Next, we’re going to subscribe to the original stream. As that is the only subscription we’re going to manage, we’ll return the disposable object from that subscription as the object maintaining the subscription to our output stream:

    return source.Subscribe(value =>

    {                           

        …

    },

    error=>

    {

        …

    },

    () =>

    {

        …

    });

Now it is time to fill in the details of the subscription.

First we’ll tackle the OnNext messages:

    data.AddRange(value);

    if (data.Count > bufferSize)

    {

        observer.OnNext(data.ToArray());

        data.Clear();

    }

    observer.OnError(error);

This statement can be reduced to a lambda expression and even further to a method group, which we’ll see in the final code.

Once we get an OnCompleted message, we could be in the situation that the buffer still contains data, but hasn’t reached the boundary of bufferSize.

In that case, we should empty the buffer before sending out OnCompleted to our subscribers:

    if (data.Count > 0)

        observer.OnNext(data.ToArray());

    observer.OnCompleted();

Final Code

And with that, we have the full implementation of our buffering operator:

    public static IObservable<byte[]> MinimumBuffer(this IObservable<byte[]> source,
        int bufferSize)

    {

        return Observable.CreateWithDisposable<byte[]>(observer =>

        {

            var data = new List<byte>();

            return source.Subscribe(value =>

            {                           

                data.AddRange(value);

                if (data.Count > bufferSize)

                {

                    observer.OnNext(data.ToArray());

                    data.Clear();

                }

            },

            observer.OnError,

            () =>

            {

                if (data.Count > 0)

                    observer.OnNext(data.ToArray());

                observer.OnCompleted();

            });

        });

    }

    source.MinimumBuffer(2 << 16).WriteToStream(stream);

What’s next?

We’ve spent quite some time so far in these series on talking about Streams.
Next we’ll take a look at how we could use these stream operations from ASP.NET.
We’ll try to plug Rx into the IHttpAsyncHandler mechanism and use our stream operators from within that pattern.

As the video goes into great detail on why you’d want to test Rx this way, I won’t go into details here. However as the video briefly touches on a lot of different subjects, here is a sample to get you started writing tests using this functionality.

First we’re going to create a base class that will provide some helpers to our test:

   public abstract class Test

     {

        public Recorded<Notification<T>> OnNext<T>(long ticks, T value)

        {

            return new Recorded<Notification<T>>(ticks, new Notification<T>.OnNext(value));

        }

        public Recorded<Notification<T>> OnCompleted<T>(long ticks)

        {

            return new Recorded<Notification<T>>(ticks, new Notification<T>.OnCompleted());

        }

        public Recorded<Notification<T>> OnError<T>(long ticks, Exception exception)

        {

            return new Recorded<Notification<T>>(ticks,
                new Notification<T>.OnError(exception));

        }

        public Subscription Subscribe(long start, long end)

        {

            return new Subscription(start, end);

        }

        public Subscription Subscribe(long start)

        {

            return new Subscription(start);

        }

    }

Next we’re going to write a test to test the behavior of the Select operator. We’re using the Visual Studio Test Framework here, but it really can be done in any framework.

Here is the skeleton code of our test:

    [TestClass]

    public class SelectTest : Test

    {

        [TestMethod]

        public void Select_Complete()

        {

        }

    }

Let’s start filling in the blanks:

First we’ll create a test scheduler:

    var scheduler = new TestScheduler();

    var xs = scheduler.CreateHotObservable(

                OnNext(180, 1),

                OnNext(210, 2),

                OnNext(240, 3),

                OnNext(290, 4),

                OnNext(350, 5),

                OnCompleted<int>(400),

                OnNext(410, -1),

                OnCompleted<int>(420),

                OnError<int>(430, new MockException(-1)));

Notice that this observable doesn’t follow the contract of Rx, as it produces more messages after the first OnCompleted. This is ok as we want to test that the Select operator still behaves correctly in this case.

Next we want to run the Select operator over this observable.

The test scheduler code has a set of details to make our live easier:

• execute the code creating the observable at virtual time 100
• subscribe to the resulting observable at virtual time 200
• unsubscribe from the subscription at virtual time 1000

These are merely defaults, you’re free to change these around, but they have worked out well in most cases for our testing.

So with this information, we tell the test scheduler what to do to create the observable and run the test:

    var results = scheduler.Run(() => xs.Select(x =>

            {

                invoked++;

                return x + 1;

            }));

In this test, we side effect inside the select, to ensure that it gets invoked exactly as many times as we expect next to this we increment each value coming through by one, to ensure that the select operator is indeed doing the job it’s supposed to do.

Next we need to make sure that the resulting observable contained exactly the values we expected at exactly the right virtual time we expected.

The Run method helps us out here as it gives us back an IEnumerable<Recorded<Notification<int>>.

With the help of the AssertEqual extension method, we can verify the results.

    results.AssertEqual(

                OnNext(210, 3),

                OnNext(240, 4),

                OnNext(290, 5),

                OnNext(350, 6),

                OnCompleted<int>(400));

   xs.Subscriptions.AssertEqual(Subscribe(200, 400));

Finally we check if the Select operator has been called exactly as frequent as we’d expected:

    Assert.AreEqual(4, invoked);

Our final test code looks as follows:

    [TestClass]

    public class SelectTest : Test

    {

        [TestMethod]

        public void Select_Complete()

        {

            var scheduler = new TestScheduler();

            var invoked = 0;

            var xs = scheduler.CreateHotObservable(

                OnNext(180, 1),

                OnNext(210, 2),

                OnNext(240, 3),

                OnNext(290, 4),

                OnNext(350, 5),

                OnCompleted<int>(400),

                OnNext(410, -1),

                OnCompleted<int>(420),

                OnError<int>(430, new MockException(-1)));

            var results = scheduler.Run(() => xs.Select(x =>

            {

                invoked++;

                return x + 1;

            }));

            results.AssertEqual(

                OnNext(210, 3),

                OnNext(240, 4),

                OnNext(290, 5),

                OnNext(350, 6),

                OnCompleted<int>(400));

            xs.Subscriptions.AssertEqual(

                Subscribe(200, 400));

            Assert.AreEqual(4, invoked);

        }

    }

We have just implemented our first Rx test. It is the Hello World equivalent for Rx testing. This operator doesn’t involve a lot of complicated scheduling, but it shows all the required basics for using this kind of testing on more complicated scenarios.

Let us know what you think, if anything is missing or can be simplified. As always, feedback is most welcome at our forum.

• Reading a stream asynchronously
• Reading strings asynchronously, line by line

Next, I would like us to take a look at writing an observable to a stream asynchronously.

Requirements

When we write an observable to a stream, there are several issues we have to deal with:

1.       We want to write all data in the observable to the file.

2.       These values should be written to the file in order.

3.       We want to be notified once the whole file has been written.

From 1 and 3 we can derive the signature for our method:

public static IObservable<Unit> WriteToStream(
    this IObservable<byte[]> source, Stream stream)

Data Corruption

Point 2 is interesting. Given that we are in an asynchronous world, we have to be very careful of potential data corruption. We want to make sure that if one piece of data is in process of being written to a file, the next piece of data comes in doesn’t corrupt the first write.

When doing the research for this post, I initially wrote a Drain operator that would avoid these kinds of issues.

I was almost ready to post about this operator, when I found something interesting that was deeply buried inside the MSDN documentation for BeginWrite:

“The current position in the stream is updated when you issue the asynchronous read or write, not when the I/O operation completes. Multiple simultaneous asynchronous requests render the request completion order uncertain.”

In order words, the position of the stream is updated synchronously in the call to BeginWrite. This means that a chunk in the file of the exact size of your data is reserved for each call to BeginWrite. This will ensure that no data corruptions happen because of simultaneous writes.

Because of the following two guarantees Rx gives us:

·         The grammar is OnNext* (OnCompleted| OnError)?

·         All calls to IObserver are serialized.

We can safely call BeginWrite any time a message comes in.

The second sentence talks about the completion order. The uncertain order is not important for us. We are only interesting in knowing that all operations have completed.

Out with the Drain operator

Given these new facts, we can throw away the Drain operator. I’ll keep the code around and will blog about in the future. As I’m sure there are scenarios were we will need it.

So let’s see how to code up the solution without Drain.

BeginWrite

First we’re going to need an observable version of BeginWrite:

var asyncWrite = Observable.FromAsyncPattern<
    byte[], int, int>(stream.BeginWrite, stream.EndWrite);

Next we want to call asyncWrite for each block of data that comes in to our source observable.

SelectMany

The preferred way to create new asynchronous operations from an observable is to use the SelectMany operator. (SelectMany has other fine uses, but this is a common one).

You can skip this section if you’re already familiar with SelectMany.

The SelectMany operator takes a selector function argument. This selector function gets called for every value sent through the source observable. The selector should return an observable for each value.

The SelectMany operator merges results from all observables produced by the selector function into a single observable that is returned to the user.

The observable returned from SelectMany fires OnCompleted once all observables produced by the selector have completed.

The returned observable fires OnError in the following cases:

·         An error occurred in the source stream.

·         An exception was thrown by the selector function.

·         An error occurred in any of the produced observables.

WriteToStream Implementation

We’ll use SelectMany in our WriteToStream operator as follows:

source.SelectMany(data => asyncWrite(data, 0, data.Length))

We now have an IObservable<Unit> that will fire an OnNext message with Unit for each separate write. After which, the observable will fire OnCompleted to signal that all data has been written.

To clean up our operator, we want to get rid of the unnecessary Unit messages coming through. We want to make sure though that we still get notified of either completion or errors that might have happened. We remove all OnNext messages by using the Where operator that filters every single OnNext message:

return source.SelectMany(data => asyncWrite(data, 0, data.Length))
    .Where(_ => false);

The final version of our operator looks like this:

public static IObservable<Unit> WriteToStream(
    this IObservable<byte[]> source, Stream stream)

{

    var asyncWrite = Observable.FromAsyncPattern<

        byte[], int, int>(stream.BeginWrite, stream.EndWrite);

    return source.SelectMany(data =>
        asyncWrite(data, 0, data.Length)).Where(_ => false);

}

WARNING: As this operator starts writing any piece of data it receives immediately, this can lead to performance issues when writing many small chunks of data.

Next in these series, we’ll look at how we can create a buffer to only save out bigger chunks of data to avoid this potential performance issue.

StreamReader

The .NET BCL provides a synchronous way of writing the pattern we described above through the StreamReader class, unfortunately this class doesn’t provide asynchronous versions of methods like ReadLine. So we’ll have to cook up something ourselves.

That doesn’t mean of course, we can’t learn from what the implementation of StreamReader. So we’re off to the reference source to take a look at DEVDIV_TFS\Dev10\Releases\RTMRel\ndp\clr\src\BCL\System\IO\StreamReader.cs\1305376\StreamReader.cs. Here we find a couple of interesting things about StreamReader/ReadLine:

• It uses a buffer that reads from the underlying stream
• It uses the Encoding class to go from byte[] to strings
• As encoding can span multiple buffer reads, a lot of logic happens here to avoid issues around that.
• When ReadLine is called, it walks through this buffer to find the next new line (\r, \r\n or \n). Whenever it finds that or finds the end of the file, it builds a string and returns the value.

Let’s try to convert this to the async pattern. We’re going to ignore the encoding part for now as that would clutter the sample and we’re going to assume ASCII encoding.

• We’ll use the AsyncRead method from our previous sample to push asynchronous reads of byte[] to us.
• We’ll return an IObservable<string> that will be pushed lines in the file.
• We’ll build a buffer of characters until we hit a new line or the end of the file
• Once we hit that condition, we fire out a call to OnNext to push out the line we build up. After which we’ll clear the buffer.

So let’s get started. First we define the signature of this method:

public static IObservable<string> AsyncReadLines(
    this Stream stream, int bufferSize)

Next we’re going to write a buffering IObservable that works based on the original IObservable from AsyncRead. Often, these kind of operations could be done by doing a transformation on the AsyncRead observable e.g. with the Scan operator. However, as we also want to do some work when the source observable completes (at the end of the file) it is best to write a custom implementation using Observable.CreateWithDisposable.

Observable.CreateWithDisposable & Observable.Create

These methods are convenient helpers to allow you to write concrete implementations of IObservable without having to deal with a lot of the clutter. The signature of Observable.CreateWithDisposable is the following:

public static IObservable<TSource> CreateWithDisposable<TSource>(
    Func<IObserver<TSource>, IDisposable> subscribe)

Now, if you look at the IObservable interface definition:

public interface IObservable<TSource>

{

    IDisposable Subscribe(IObserver<TSource> observer);

}

You’ll see that the signature of the Func<> passed into CreateWithDisposable looks a lot alike the signature of the Subscribe method of the IObservable interface. Well that’s completely correct. Observable.CreateWithDisposable is a trick that we’re using in Rx to work around the fact that C# doesn’t support anonymous inner-types. In languages that support anonymous inner types, you would write something like this:

public static IObservable<string> AsyncReadLines(
    this Stream stream, int bufferSize)

{

    return new IObservable<string>

    {

        public IDisposable Subscribe(IObserver<string> observer)

        {

            ...

        }

    }

}

Working around the lack of anonymous inner-types, we can now write something like this:

public static IObservable<string> AsyncReadLines(
    this Stream stream, int bufferSize)

{

    return Observable.CreateWithDisposable<string>(observer =>

    {

        ...

    }

}

Next to providing a convenient way of writing Observable implementations inline, the Observable.CreateWithDisposable operator provides another handy feature that otherwise would require a lot of plumbing: It wraps any observer passed into Subscribe in an observer that does two nifty things:

·         When the Observable stream is done (either by firing OnError or Oncompleted, it automatically disposes the subscription to the Observable, cleaning up any state as soon as possible.

·         It ensures that once OnError or OnCompleted is called once, no more messages are sent through to any of the OnNext, OnError or OnCompleted messages, to ensure the Rx contract of OnNext* (OnError|OnCompleted)?

Observable.Create is almost the same as Observable.CreateWithDisposable. The only difference is that the subscribe Func<> returns an Action instead of an IDisposable. The idea is the same here, you don’t have to create an implementation of IDisposable, but use an action as your anonymous inner type version of IDisposable.Dispose.

AsyncReadLines Implementation

Ok, let’s get back to the problem at hand. We’ve got the wireframe for our method; now let’s look at the details.

First we’re going to start with calling our AsyncRead method from the previous blog entry:

var blocks = AsyncRead(stream, bufferSize);

Now this still works on byte[] and we said we wanted to work in ASCII, so let’s convert that:

var blocks = AsyncRead(stream, bufferSize)
    .Select(block=>Encoding.ASCII.GetString(block));

Next we want to do something with the data inside the source IObservable. The only way to get to that data is to subscribe to the stream:

var subscription = blocks.Subscribe(data =>

    {

        ...

    },

    exception =>

    {

        ...

    },

    () =>

    {

        ...

    });

We’ll also have to make a decision on how the user can unsubscribe the observer they passed to our observable. In this case, when the user unsubscribes from our observable, we need to unsubscribe from the subscription we made ourselves, so we’ll modify the code to return the subscription we received ourselves:

return blocks.Subscribe(data =>

    {

        ...

    },

    exception =>

    {

        ...

    },

    () =>

    {

        ...

    });

Now that we’ve hooked up to the source observable, we get a call every time new data is available. This data is presented as a string that potentially contains several lines. So let’s write some code to parse that string. We’re going to walk through the string and look for \r, \r\n or \n tokens. If we find one of those were at the end of a line and we’ll have to take some action. If we’re not at the end of a line, we put the character in a temporary buffer (a StringBuilder).

var sb = new StringBuilder();

for (var i = 0; i < data.Length; i++)

{

    var atEndofLine = false;

    var c = data[i];

    if (c == '\r')

    {

        atEndofLine = true;

        var j = i + 1;

        if (j < data.Length && data[j] == '\n')

            i++;

    }

    else if (c == '\n')

    {

        atEndofLine = true;

    }

    if (atEndofLine)

    {

        produceCurrentLine();

    }

    else

    {

        sb.Append(c);

    }

}

Before we look at what we want to do when we see an end of line (the produceCurrentLine call), let’s take a look at what we should do in case of OnError or OnComplete coming through on the source observable.

As Rx likes to maintain abort semantics for exceptions, we’re going to pass any exception that comes in on the source IObservable through right away, so we’ll make any call to OnError pass through to the subscribing observer:

exception =>

{

    observer.OnError(exception);

}

This can be simplified by converting the statement lambda into a method group:

observer.OnError

For OnCompleted we’ll have to do some more work. Imagine a file that doesn’t have a newline at the end of the file, we still like to send out this string. So when our source signals OnCompleted, we’ll have to do the same work as when we hit a newline character inside our OnNext. So we’re going to share that code. After we’ve produced the current line, we fire OnCompleted.

() =>

{

    produceCurrentLine();

    observer.OnCompleted();

});

Now let’s implement produceCurrentLine. We need to get the string out of the buffer, reinitialize the buffer and send the string to onNext:

Action produceCurrentLine = () =>

{

    var text = sb.ToString();

    sb.Length = 0;

    observer.OnNext(text);

};

And with that we have the full implementation of our AsyncReadLines operator:

public static IObservable<string> AsyncReadLines(
    this Stream stream, int bufferSize)

{

    return Observable.CreateWithDisposable<string>(observer =>

    {

        var sb = new StringBuilder();

        var blocks = AsyncRead(stream, bufferSize).Select(
            block => Encoding.ASCII.GetString(block));

        Action produceCurrentLine = () =>

        {

            var text = sb.ToString();

            sb.Length = 0;

            observer.OnNext(text);

        };

        return blocks.Subscribe(data =>

        {

            for (var i = 0; i < data.Length; i++)

            {

                var atEndofLine = false;

                var c = data[i];

                if (c == '\r')

                {

                    atEndofLine = true;

                    var j = i + 1;

                    if (j < data.Length && data[j] == '\n')

                        i++;

                }

                else if (c == '\n')

                {

                    atEndofLine = true;

                }

                if (atEndofLine)

                {

                    produceCurrentLine();

                }

                else

                {

                    sb.Append(c);

                }

            }

        },

        observer.OnError,

        () =>

        {

            produceCurrentLine();

            observer.OnCompleted();

        });

    });

}

The following program shows how to use this operator:

// bufferSize > 64k as per BeginRead spec: https://msdn.microsoft.com/en-us/library/zxt5ahzw.aspx

var bufferSize = 2 << 16;

// constructor of FileStream that enables asynchronous operations

var stream = new FileStream(@"d:\temp\input.txt", FileMode.Open, FileAccess.Read, FileShare.Read, bufferSize, true);

stream.AsyncReadLines(bufferSize).Run(Console.WriteLine);

What’s next?

In these series, we’ve seen how to asynchronously read from a file. In this post, we learned how to create an operator that buffers data and sends out this buffer in useful chunks. Next we’ll tackle writing to a file asynchronously and see what kind of specific challenges that operation brings.

There have been many samples showing Rx on the client. In these samples, Rx is often used for UI operations (such as Drag Drop) and/or network requests (e.g. dictionary suggest). What I haven’t seen much of is samples of using Rx on the server. Well it’s time to change that!

These series will focus on scenarios where you could use Rx on the server. I’ll start out with a couple of posts on reading and writing asynchronously from and to System.IO.Stream objects. After that I plan to discuss using Rx for Asynchronous ASP.NET programming, followed by anything else that might come up..

This will be a pretty advanced series, probably at the 300 level. If I go too fast, feel free to post comments or ask questions on the Rx forum

So with that, let’s jump right into part 1:

Asynchronous System.IO.Stream reading

First of all, why do we care about asynchronous reading? The Wikipedia page on Asynchonous I/O gives a good description on why: We don’t want to block on slow IO operations. This is something that can be of importance on a client application as well, but in a server application it quickly becomes critical. With hundreds of clients, servers often cannot afford to have a thread blocked on IO. 

So that’s where Asynchronous I/O comes in. The .NET BCL exposes this pattern through the BeginRead/EndRead & BeginWrite/EndWrite methods. While this provides a more optimal way of dealing with slow I/O from a runtime perspective, it isn’t really an optimal way of writing your code. As each separate asynchronous operation requires a Begin/End pair as well as a set of delegates, you can quickly get into spaghetti code. So let’s take a look if we can improve on this pattern with Rx.

In order to give Rx access to the Asynchronous I/O operations, we’re first going to convert the BeginRead/EndRead pattern into a Rx pattern:

var asyncRead = Observable.FromAsyncPattern<byte[], int, int, int>(
     stream.BeginRead, stream.EndRead);

What does this mean? FromAsyncPattern takes the something that follows the Begin* End* pattern and converts it into a Func<arguments, IObservable<returnvalue>>. When somebody calls this Func<>, the following happens:

• the arguments passed in to the returned Func<> are passed into to the Begin* method.
• Additionally the right steps are taken to hookup the Begin* to a callback that is called once the asynchronous action is completed.
• The func returns an IObservable<returnvalue>. The concrete implementation of this IObservable<returnvalue> is an AsyncSubject<returnvalue>.
• Once the callback gets called, the return value of the asynchronous computation is retrieved by calling End*. This value is then sent to the AsyncSubject by calling OnNext & OnCompleted.

NOTE: The fact that the concrete implementation of the IObservable returned here is an AsyncSubject, means that this observable is ‘HOT’. The reason for this is that the async operation might have completed before you’re able to subscribe to the IObservable that you get back. Without an AsyncSubject, there could be a race condition in which you would miss the result.

In the case of stream.BeginRead & stream.EndRead, the type arguments to FromAsyncPattern are: the first three arguments to BeginRead: array, offset, numBytes, followed by the return value of EndRead: The number of bytes read from the stream, between 0 and the number of bytes you requested.

For this case, the return value of FromAsyncPattern will have the following signature:
Func<byte[], int,int, IObservable<int>>

So let’s see how we can use this new asyncRead function: 

// bufferSize > 64k as per BeginRead spec
// https://msdn.microsoft.com/en-us/library/zxt5ahzw.aspx
var bufferSize = 2 << 16; 

// constructor of FileStream that enables asynchronous operations
// https://msdn.microsoft.com/en-us/library/7db28s3c.aspx
var stream = new FileStream(@"d:\temp\input.txt", FileMode.Open, FileAccess.Read,
    FileShare.Read, bufferSize, true);  

var asyncRead = Observable.FromAsyncPattern<byte[], int, int, int>(stream.BeginRead,
    stream.EndRead);

var buffer = new byte[bufferSize];
var oiRead = asyncRead(buffer, 0, bufferSize);
oiRead.Run(bytesRead =>
    Console.WriteLine("The program read {0} bytes asynchronously", bytesRead));

Clearly the beginning of something beautiful :). Although several things don’t look natural yet:

• The observable contains the amount of bytes read, the data is state maintained outside of the operation (in the buffer).
• User code will have to deal with partially filled buffers if less bytes were available than the buffer size.
• The operation only reads once and will need to be repeated if the file is larger than bufferSize or if the stream wasn’t ready to provide all contents of the file

let’s try to tackle the first to points first:

We’ll factor out the code into an extension method on Stream and select in the value of the buffer into the observable:

public static IObservable<byte[]> AsyncRead(this Stream stream, int bufferSize)
{
    var asyncRead = Observable.FromAsyncPattern<byte[], int, int, int>(
        stream.BeginRead, stream.EndRead);  

    var buffer = new byte[bufferSize];  

    return asyncRead(buffer, 0, bufferSize).Select(readBytes =>
    {
        var newBuffer = new byte[readBytes];
        Array.Copy(buffer, newBuffer, readBytes);

        return newBuffer;
    });
}

This small refactoring has made the usage of the code quite a bit cleaner:

stream.AsyncRead(bufferSize).Run(bytes => DoSomethingWithData(bytes));

Now let’s try to tackle the last issue. We want to keep the signature we created above, however the IObservable<byte[]> should not fire OnNext a single time. It should fire OnNext with as many byte[] instances as it takes to completely read the stream. The reason we want to fire several times, and not once at the end when all data is read in is that we’re potentially dealing with very big files (imagine reading in a 50GB file in 1MB chunks).

One thing that could come to mind is to to try to use the Repeat operator to accomplish this. That will not work unfortunately as the Repeat operator only work on ‘Cold’ observables. If we were to use repeat on the observable returned by asyncRead, it would indefinately return the value produced by the first call to BeginRead.

So what can we do instead? We want to make repeated calls to asyncRead, retrieving new observables and concatenating as long as the amount of bytes read is greater than 0. We also want to make sure only one asyncRead operation is in flight at a time to maintain ordering. This is a pretty imperative operation that we want to do in an asynchronous fashion. In Rx, the preferred way to do these kind of operations is using the Iterate operator.

The Iterate Operator

One of the signatures for the Iterate operator is as follows:

public static IObservable<TResult> Iterate<TResult>(Func<IObserver<TResult>, IEnumerable<IObservable<object>>> iteratorMethod)

A pretty complex signature. It takes a function that get’s passed in an IObservable<TResult> as an argument, and returns an IEnumerable that yields values of IObservable<object> and somehow turns it into an IObservable<TResult>

The reason for this signature, is to make Rx play nice with the C# Iterator pattern. It allows users to write asynchronous code, returning IObservables while writing code that looks imperative. If you’re unfamiliar with the C# iterator pattern’s normal use case, I suggest you visit the link above first.

The way the C# Iterator pattern does it’s normal job is by taking the user code that looks imperative and wrap it inside out and build  a state-machine. The state-machine keeps track of the control-flow and invokes parts of the user code when it hits the right state. Normally a state transition happens when code calling the C# Iterator pattern needs the next value from the IEnumerable (MoveNext). The state-machine invokes a piece of the user code until the next yield return or break. After which control is returned to the code calling the state-machine.

We can use this for Rx as well. In this case, instead of yield returning a value, we yield return the Observable we’re waiting for to complete. The user code will yield control and the Iterator operator will ensure that the user-code gets control back the moment the Observable is complete. As the return is now taken up by our signaling of Observable completion, we need another way to produce values to the outside world. That’s where the IObserver argument comes in. This is our handle to producing values to the outside world.

So let’s see the Iterate operator in action:

As C# currently doesn’t support the Iterator pattern inside lambdas, we’ll have to call out to a helper method first:

static IObservable<byte[]> AsyncRead(this Stream stream, int bufferSize)
{
    return Observable.Iterate<byte[]>(result =>
        AsyncReadHelper(result, stream, bufferSize));
}

Next we’ll build the skeleton for our helper:

private static IEnumerable<IObservable<object>> AsyncReadHelper(
    IObserver<byte[]> result, Stream stream, int bufferSize)
{
    var asyncRead = Observable.FromAsyncPattern<byte[], int, int, int>(
        stream.BeginRead, stream.EndRead);
    var buffer = new byte[bufferSize];  

    while (true)
    {
       …
    }
}

What to put inside the while? In order to match the method’s signature, it’ll have to be something like this:

yield return asyncRead(buffer, 0, bufferSize);

This will yield control back to the Iterator operator until the asyncRead completes after which the next line of the method is called.There are however several problems with that:

• asyncRead returns IObservable<int>. As int is a value type and .NET variance on generics doesn’t allow casting from a value type to object.
• we’re not only interested in the completion of the asyncRead, but we' also like to know how many bytes were read so we can size our output array accordingly.

This is where the Start Operator comes in:

public static ListObservable<TSource> Start<TSource>(
    this IObservable<TSource> source)

This operator takes any IObservable<T> and turns it into an object that implements IList<T> and IObservable<object>. As the source observable fires out values on OnNext, it will cache these values and make them available through the IList<T> implementation. Further it will fire OnCompleted on the IObservable<Object> interface once OnCompleted comes in on the source observable.

With the Start operator, we can now finish our AsyncReadHelper implementation: 

private static IEnumerable<IObservable<object>> AsyncReadHelper(
    IObserver<byte[]> result, Stream stream, int bufferSize)
{
    var asyncRead = Observable.FromAsyncPattern<byte[], int, int, int>(
        stream.BeginRead, stream.EndRead);
    var buffer = new byte[bufferSize];

 

   while (true)
    {
        var read = asyncRead(buffer, 0, bufferSize).Start();
        yield return read;

        // As asyncRead returns an AsyncSubject,
        // and the Iterator operator takes care of exceptions,
        // we know at this point there will always be exactly one value in the list.

 
        var bytesRead = read[0];
        if (bytesRead == 0)
        {
            // End of file      
            yield break;
        }

        var outBuffer = new byte[bytesRead];
        Array.Copy(buffer, outBuffer, bytesRead);

        // Fire out to the outer Observable
        result.OnNext(outBuffer);
    }
}

And with that we have an extension method that will read the whole file asynchronously, exposing the data as an IObservable<byte[]>, opening a world of possibilities of windowing, grouping, and other operations we can do on the data.

Temperature of AsyncRead

Our original version of AsyncRead was hot, our new version is neither hot, nor cold, more like luke-warm. Even though code created using the Iterator operator is generally cold, this is not the case here. As the System.IO.Stream object in .NET maintains state, so does our usage of it. The stream keeps track of the position in the file. If we were to subscribe two observers to this operator, unexpected things will happen. First it depends on if the specific Stream even supports two asynchronous reads at the same time. If it does, it will be a race, some of the data will be on the first observer and some will be on the second observer. Because of this it is best to only attach one observer to AsyncRead. If you really want to attach multiple observers, use the Publish operator on the resulting observable before subscribing.

What’s next?

So far we’ve seen how to use some advanced Rx operators to create an operator that will read in a file asynchronously and create an IObservable<byte[]> to signal the availability of the data. An operation that can be very useful on servers. Imagine an implementation of IHttpAsyncHandler that wants to dynamically read in a file on a slow network share. 

A set of byte[] might not be the most convenient way to look at the contents of a file though. Just like how in the synchronous world one would often prefer a StreamReader with functions like ReadLine over reading a byte[]. Next in this series we’ll talk about creating an asynchronous version of StreamReader functionality.

Attached to this post are the Rx bindings for node.js. With them you can use Rx to write asynchronous webservers. E.g. the Hello World sample from the homepage of the node.js project can be rewritten as follows:

var sys = require("sys");
var http = require('./rx_http');
var serverData = http.createServer();serverData.Delay(2000).Subscribe(function(details)
{
    details.response.writeHead(200, { 'Content-Type': 'text/html' });
    details.response.write("Hello World");
    details.response.end();
});
serverData.server.listen(8000);
sys.puts('Server running at https://127.0.0.1:8000/');

of course, this is just a simple hello world. With operators like SelectMany and the bindings to all the file system operators, we can write great asynchronous webservers, but that is for a future post. Please let me know if you like these bindings. I’ll try to keep them up-to-date as both Rx.JS and node.js development continue.

To use these bindings, copy rx.js from the official Rx download and add the files from this zip to the same directory.

Saturday April 17th 3:45PM - 4:15PM.

For those without tickets, videos will be posted afterwards ]]> https://docs.microsoft.com/archive/blogs/jeffva/time-flies-like-an-arrow-in-script Fri, 26 Mar 2010 11:22:13 GMT https://blogs.msdn.microsoft.com/jeffva/2010/03/26/time-flies-like-an-arrow-in-script/ As kouPhax requested this on the Rx forum, I decided to post a port to Script# of the Time flies like an arrow sample that ships with Rx for JavaScript.

Rx for JavaScript already ships with a binding for Script#, so that will make our lives a lot easier (you can find the binding in <InstallPath>\Redist\ScriptSharp\RxJs.dll)

For this sample I'll assume you have Script# 0.5.6.0 installed from Nikhil's Script# site.

We start off with creating a Script# enabled website:

Next we open the Scriplet editor for the default Scriplet in the project:

We’ll make Script# aware of Rx by adding a reference to the RxJS.Dll:

As well as the rx.js JavaScript file

Next we’ll add the container div to the body of the Html page:

<div id="container"></div>

Now it is time to do some coding: