Merge branch 'master' of github.com:fsprojects/FSharpx.Async

Author: forki

docs/content/library/AsyncSeq.fsx

@@ -8,9 +8,9 @@ similar to `list<'a>` with the difference being that each head and tail node or
 in `Async`. `AsyncSeq` also bears similarity to `IObservable<'a>` with the former being pull-based and the
 latter push-based. Analogs for most operations defined for `Seq`, `List` and `IObservable` are also defined for 
 `AsyncSeq`. The power of `AsyncSeq` lies in that many of these operations also have analogs based on `Async` 
-allowing one to compose complex asynchronous workflows.
+allowing composition of complex asynchronous workflows.
 
-The `AsyncSeq` type is located in the `FSharpx.Async.dll assembly which can be loaded in F# Interactive as follows:
+The `AsyncSeq` type is located in the `FSharpx.Async.dll` assembly which can be loaded in F# Interactive as follows:
 *)
 
 #r "../../../bin/FSharpx.Async.dll"
@@ -31,16 +31,16 @@ let asyncS = asyncSeq {
 
 (**
 Another way to generate an asynchronous sequence is using the `Async.unfoldAsync` function. This
-function takes another function which can generate individual elements based on a state and 
+function accepts as an argument a function which can generate individual elements based on a state and 
 signal completion of the sequence.
 
 For example, suppose that you're writing a program which consumes the Twitter API and stores tweets
-which satisfy some criteria into a database. There are several asynchronous request-reply operations at play - 
+which satisfy some criteria into a database. There are several asynchronous request-reply interactions at play - 
 one to retrieve a batch of tweets from the Twitter API, another to determine whether a tweet satisfies some
 criteria and finally an operation to write the desired tweet to a database. 
 
 Given the type `Tweet` to represent an individual tweet, the operation to retrieve a batch of tweets can 
-be modeled with a type `int -> Async<(Tweet[] * int) option>` where the incoming `int` represents the 
+be modeled with type `int -> Async<(Tweet[] * int) option>` where the incoming `int` represents the 
 offset into the tweet stream. The asynchronous result is an `Option` which when `None` indicates the
 end of the stream, and otherwise contains the batch of retrieved tweets as well as the next offset.
 
@@ -60,10 +60,10 @@ let tweetBatches : AsyncSeq<Tweet[]> =
   AsyncSeq.unfoldAsync getTweetBatch 0
 
 (**
-The asynchronous sequence `tweetBatches` will when iterated consume the entire tweet stream.
+The asynchronous sequence `tweetBatches` will when iterated, incrementally consume the entire tweet stream.
 
 Next, suppose that the tweet filtering function makes a call to a web service which determines
-whether a particular tweet should be stored in the database. This function can be modeled with
+whether a particular tweet is of interest and should be stored in the database. This function can be modeled with
 type `Tweet -> Async<bool>`. We can flatten the `tweetBatches` sequence and then filter it as follows:
 *)
 
@@ -92,7 +92,7 @@ let storeFilteredTweets : Async<unit> =
 
 (**
 Note that the value `storeFilteredTweets` is an asynchronous computation of type `Async<unit>`. At this point,
-it is a **representation** of the workflow which consists of reading batches of tweets, filtering them and storing them
+it is a *representation* of the workflow which consists of reading batches of tweets, filtering them and storing them
 in the database. When executed, the workflow will consume the entire tweet stream. The entire workflow can be
 succinctly declared and executed as follows:
 *)
@@ -113,9 +113,9 @@ composed using familiar operations on sequences. Furthermore, it will be execute
 
 The central difference between `seq<'a>` and `AsyncSeq<'a>` two can be illustrated by introducing the notion of time. 
 Suppose that generating subsequent elements of a sequence requires an IO-bound operation. Invoking long 
-running IO-bound operations from within a `seq<'a>` will **block** the thread which calls `MoveNext` on the 
-corresponding `IEnumerator`. An `AsyncSeq` can use facilities provided by the F# `Async` type to make more efficient 
-use of system resources.
+running IO-bound operations from within a `seq<'a>` will *block* the thread which calls `MoveNext` on the 
+corresponding `IEnumerator`. An `AsyncSeq` on the other hand can use facilities provided by the F# `Async` type to make 
+more efficient use of system resources.
 *)
 
 let withTime = seq {
@@ -134,8 +134,9 @@ let withTime' = asyncSeq {
 
 (**
 When the asynchronous sequence `withTime'` is iterated, the calls to `Async.Sleep` won't block threads. Instead,
-the **continuation** of the sequence will be scheduled by a `ThreadPool` thread, while the calling thread
-will be free to perform other work. Overall, a `seq<'a>` can be viewed as a special case of an `AsyncSeq<'a>`.
+the *continuation* of the sequence will be scheduled by `Async` while the calling thread will be free to perform other work. 
+Overall, a `seq<'a>` can be viewed as a special case of an `AsyncSeq<'a>` where subsequent elements are retrieved
+in a blocking manner.
 *)
 
 
@@ -144,16 +145,16 @@ will be free to perform other work. Overall, a `seq<'a>` can be viewed as a spec
 
 Both `IObservable<'a>` and `AsyncSeq<'a>` represent collections of items and both provide similar operations
 for transformation and composition. The central difference between the two is that the former is push-based 
-and the latter is pull-based. Consumers of an `IObservable<'a>` **subscribe** to receive notifications about
-new items or completion. By contrast, consumers of an `AsyncSeq<'a>` **retrieve** subsequent items on their own
+and the latter is pull-based. Consumers of an `IObservable<'a>` *subscribe* to receive notifications about
+new items or the end of the sequence. By contrast, consumers of an `AsyncSeq<'a>` *retrieve* subsequent items on their own
 terms. Some domains are more naturally modeled with one or the other, however it is less clear which is a more
 suitable tool for a specific task. In many cases, a combination of the two provides the optimal solution and 
 restricting yourself to one, while simplifying the programming model, can lead one to view all problems as a nail.
 
 A more specific difference between the two is that `IObservable<'a>` subscribers have the basic type `'a -> unit` 
 and are therefore inherently synchronous and imperative. The observer can certainly make a blocking call, but this 
 can defeat the purpose of the observable sequence all together. Alternatively, the observer can spawn an operation, but
-this can break composition because one can no longer rely on the observer operation returning to determine that it has 
+this can break composition because one can no longer rely on the observer returning to determine that it has 
 completed. With the observable model however, we can model blocking operations through composition on sequences rather
 than observers.
 
@@ -190,6 +191,8 @@ module Observable =
   let bind (f:'a -> IObservable<'b>) (o:IObservable<'a>) : IObservable<'b> =
     failwith "TODO"
 
+  /// Filter an observable sequence using a predicate producing a observable
+  /// which emits a single boolean value.
   let filterObs (f:'a -> IObservable<bool>) : IObservable<'a> -> IObservable<'a> =
     bind <| fun a -> 
       f a
@@ -198,9 +201,12 @@ module Observable =
         | false -> None
       )
 
+  /// Filter an observable sequence using a predicate which returns an async
+  /// computation producing a boolean value.
   let filterAsync (f:'a -> Async<bool>) : IObservable<'a> -> IObservable<'a> =
     filterObs (f >> ofAsync)
 
+  /// Maps over an observable sequence using an async-returning function.
   let mapAsync (f:'a -> Async<'b>) : IObservable<'a> -> IObservable<'b> =
     bind (f >> ofAsync)
 
@@ -236,17 +242,22 @@ over their generation. On the other hand, the program at hand will process the t
 they are being generated. Moreover, the underlying Twitter API will likely utilize a request-reply protocol to retrieve batches of 
 tweets from persistent storage. As such, the distinction between push vs. pull becomes less interesting. If the underlying source 
 is truly push-based, then one can buffer its output and consume it using an asynchronous sequence. If the underlying source is pull-based, 
-then one can turn it into an observable sequence by first pulling, then pushing. In a real-time reactive system, notifications must be pushed 
-immediately without delay. This point however is moot since neither `IObservable<'a>` nor `Async<'a>` are well suited for 
-real-time systems.
+then one can turn it into an observable sequence by first pulling, then pushing. Note however that in a true real-time reactive system, 
+notifications must be pushed immediately without delay.
+
+Upon closer inspection, the consumption approaches between the two models aren't all too different. While `AsyncSeq` is pull based,
+it is usually consumed using an operator such as `AsyncSeq.iterAsync` as shown above. This is a function of type 
+`('a -> Async<unit>) -> AsyncSeq<'a> -> Async<unit>` where the first argument is a function `'a -> Async<unit>` which performs 
+some work on an item of the sequence and is applied repeatedly to subsequent items. In a sense, `iterAsync` *pushes* values to this 
+function. The primary difference from observers of observable sequences is the return type `Async<unit>` rather than simply `unit`.
 *)
 
 
 (**
 ### Performance Considerations
 
 While an asynchronous computation obviates the need to block an OS thread for the duration of an operation, it isn't always the case
-that this will improve the overall performance of an application. Note however that an async computation does not **require** a
+that this will improve the overall performance of an application. Note however that an async computation does not *require* a
 non-blocking operation, it simply allows for it. Also of note is that unlike calling `IEnumerable.MoveNext()`, consuming
 and item from an asynchronous sequence requires several allocations. Usually this is greatly outweighed by the
 benefits, it can make a difference in some scenarios.

docs/content/terminology.md

@@ -10,7 +10,7 @@ concepts and hopefully alleviate some confusion.
 ## Thread
 
 A thread in this scope refers to a [managed thread](https://msdn.microsoft.com/en-us/library/6kac2kdh(v=vs.110).aspx). 
-A thread is a basic unit to which an OS allocates CPU resources. A **managed** thread usually maps directly to
+A thread is a basic unit to which an OS allocates CPU resources. A *managed* thread usually maps directly to
 an OS thread, however it is possible for a CLR host to override this behavior. A thread has a corresponding context 
 consisting of a pointer to the code being executed as well as stack and register state. 
 
@@ -21,26 +21,26 @@ information about ordering.
 
 ## Context Switch
 
-A context switch occurs when the OS scheduler decides to the thread to which it allocates CPU resources.
+A context switch occurs when the OS scheduler decides to change the thread to which it allocates CPU resources.
 In order to do this, it must save the context of the thread which is giving up use of the CPU and reconstitute
 the context of the thread which is next in line. Context switches occur for a number of reasons. 
-It occurs naturally as part of preemptive scheduling - threads run for a **time slice** or **quantum** until another
+It occurs naturally as part of preemptive scheduling - threads run for a *time slice* or *quantum* until another
 thread is given a chance to run. Another reason is when a thread explicitly yields its time slice, such as with a call to
 `Thread.Sleep`.
 
 ## Synchronous vs. Asynchronous
 
 An operation is synchronous if the caller must wait for it to complete before making progress. 
-More specifically, the calling **thread** may **block** until the synchronous operation is complete. 
+More specifically, the calling *thread* may *block* until the synchronous operation is complete. 
 Note that a CPU-bound task exhibits behavior similar to blocking.
 
 An operation is asynchronous if the request to begin the operation and the result of the operation can
 be delivered through different channels. This provides a convenient mechanism to encapsulate waiting. In other words, 
 an asynchronous operations decouples the means of sending the request from the means of receiving a response. 
 
-This decoupling allows one to in turn decouple the **logical** notion of an operation from the **physical**
+This decoupling allows one to in turn decouple the *logical* notion of an operation from the *physical*
 details of how it is executed. For example, an asynchronous operation to download a web page is a single 
-logical operation. Due to its asynchronous nature however, the underlying implementation can start the 
+*logical* operation. Due to its asynchronous nature however, the underlying implementation can start the 
 operation on one thread and then deliver the completion notification through a different thread
 (such as an IO completion thread managed by the ThreadPool). In the meantime, the calling thread is free
 to perform other work. In fact, the completion notification can even be handled by the same thread