Documented the offloading mechanism design

docs/index.md

@@ -15,22 +15,29 @@
 **b6b** is especially useful as:
 
 1. A more powerful, yet simple alternative to shell scripting
-2. A thin layer above C and system calls, which provides exceptions, garbage collection and a dynamic type system
+2. A thin layer above C and system calls, which provides exceptions, garbage collection, easy parallelism and a dynamic type system
 3. An embedded interpreter in a big software project
 4. An extremely lightweight scripting language, for rapid development of fault-tolerant embedded software
 
-# License
+# Design
+
+**b6b** is implemented as a library, *libb6b*. This library exposes a rich API that allows applications to embed **b6b**. For example, **b6b** also includes an interactive interpreter application built on top of *libb6b*.
+
+Each **b6b** interpreter uses two threads:
+
+1. The "interpreter thread", the thread which calls the *libb6b* API to create an interpreter instance and run a script through it
+2. The "offloading thread", spawned during the initialization of the interpreter
 
-    Copyright 2017 Dima Krasner
+**b6b** implements multi-threading using fibers (or, green threads) while a simple, round-robin scheduler relies on voluntary preemption to prevent starvation. **All these threads run on a single native thread: the interpreter thread.**
 
-    Licensed under the Apache License, Version 2.0 (the "License");
-    you may not use this file except in compliance with the License.
-    You may obtain a copy of the License at
+Therefore, **b6b**'s implementation of multi-threading does not benefit from SMP, but it is lock-free, lightweight, safe (for example, safe for embedding in heavily multi-threaded applications) and simple, which are far more important design considerations for the uses cases **b6b** shines at.
+
+As many system calls are non-blocking by nature, most operations in **b6b** are non-blocking as well. However, under multi-threaded scenarios, the interpreter thread **delegates blocking or slow operations** (such as compression or file creation) to the offloading thread, while the interpreter thread continues to run other fibers.
+
+Since multiple script threads may perform blocking operations **at the same time**, this offloading mechanism is mostly useful in situations such as an event-based server, where the only blocking operation is waiting for more events, while previous events are dealt with in coroutines.
+
+# License
 
-        http://www.apache.org/licenses/LICENSE-2.0
+**b6b** is free and unencumbered software released under the terms of the [Apache License Version 2.0](https://www.apache.org/licenses/LICENSE-2.0); see *COPYING* for the license text.
 
-    Unless required by applicable law or agreed to in writing, software
-    distributed under the License is distributed on an "AS IS" BASIS,
-    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-    See the License for the specific language governing permissions and
-    limitations under the License.
+For a list of its authors and contributors, see *AUTHORS*.