elgopher · May 4, 2022 · May 5, 2022 · May 6, 2022 · May 6, 2022 · May 6, 2022
diff --git a/README.md b/README.md
@@ -7,7 +7,7 @@
 
 ## What it can be used for?
 
-To speed up application performance **without** sacrificing *data consistency* and *data durability* or making source code/architecture complex.
+To **increase** database-driven web application **throughput** without sacrificing *data consistency* and *data durability*  or making source code and architecture complex.
 
 The **batch** package simplifies writing Go applications that process incoming requests (HTTP, GRPC etc.) in a batch manner:
 instead of processing each request separately, they group incoming requests to a batch and run whole group at once.
@@ -20,18 +20,21 @@ Thanks to this small library, you can create relatively simple code without the
 
 Normally a web application is using following pattern to modify data in the database:
 
-1. **Load resource** from database. Resource is some portion of data 
-such as set of records from relational database, document from Document-oriented database or value from KV store.
-Lock the entire resource pessimistically or optimistically (by reading version number).
-2. **Apply change** to data
-3. **Save resource** to database. Release the pessimistic lock. Or run
-atomic update with version check (optimistic lock).
+1. **Load resource** from database. **Resource** is some portion of data 
+such as set of records from relational database, document from Document-oriented database or value from KV store
+(in Domain-Driven Design terms it is called an [aggregate](https://martinfowler.com/bliki/DDD_Aggregate.html)).
+Lock the entire resource [optimistically](https://www.martinfowler.com/eaaCatalog/optimisticOfflineLock.html) 
+by reading version number.
+2. **Apply change** to data in plain Go
+3. **Save resource** to database. Release the lock by running
+atomic update with version check.
 
-But such architecture does not scale well if number of requests 
+But such architecture does not scale well if the number of requests 
 for a single resource is very high
 (meaning hundreds or thousands of requests per second). 
 The lock contention in such case is very high and database is significantly 
-overloaded. Practically, the number of concurrent requests is limited.  
+overloaded. Also, round-trips between application server and database add latency.
+Practically, the number of concurrent requests is severely limited.  
 
 One solution to this problem is to reduce the number of costly operations.
 Because a single resource is loaded and saved thousands of times per second 
@@ -60,13 +63,13 @@ processor := batch.StartProcessor(
 )
 
 // And use the processor inside http/grpc handler or technology-agnostic service.
-// ResourceKey can be taken from request parameter.
-err := processor.Run(resourceKey, func(r *YourResource) {
+// ctx is a standard context.Context and resourceKey can be taken from request parameter
+err := processor.Run(ctx, resourceKey, func(r *YourResource) {
     // Here you put the code which will executed sequentially inside batch  
 })
 ```
 
-For real-life example see [example web application](_example).
+**For real-life example see [example web application](https://github.com/elgopher/batch-example).**
 
 ## Installation
 
@@ -88,7 +91,8 @@ For both cases you need to deploy **multiple servers** and put a **load balancer
 Please note though, that you have to carefully configure the load balancing algorithm. 
 _Round-robin_ is not an option here, because sooner or later you will have problems with locking 
 (multiple server instances will run batches on the same resource). 
-Ideal solution is to route requests based on parameters or URL. 
-For example some http parameter could be a resource key. You can instruct load balancer
-to calculate hash on this parameter value and always route requests with this param value 
-to the same backend (of course if all backends are still available).
+Ideal solution is to route requests based on URL path or query string parameters. 
+For example some http query string parameter could have a resource key. You can instruct load balancer
+to calculate hash on this parameter and always route requests with the same key 
+to the same backend. If backend will be no longer available the load balancer should route request to a different 
+server. 
diff --git a/_example/http/http.go b/_example/http/http.go
diff --git a/_example/main.go b/_example/main.go
diff --git a/_example/store/file.go b/_example/store/file.go
diff --git a/_example/train/error.go b/_example/train/error.go
diff --git a/_example/train/service.go b/_example/train/service.go
diff --git a/_example/train/train.go b/_example/train/train.go