Data type organization

.gitignore

@@ -19,3 +19,4 @@ website/node_modules
 website/build
 website/i18n/en.json
 website/yarn.lock
+.bsp/

docs/datatypes/concurrency/index.md

@@ -0,0 +1,12 @@
+---
+id: index
+title: "Summary"
+---
+
+- **[Promise](promise.md)** — A `Promise` is a model of a variable that may be set a single time, and awaited on by many fibers.
+- **[Semaphore](semaphore.md)** — A `Semaphore` is an asynchronous (non-blocking) semaphore that plays well with ZIO's interruption.
+- **[ZRef](zref.md)** — A `ZRef[EA, EB, A, B]` is a polymorphic, purely functional description of a mutable reference. The fundamental operations of a `ZRef` are `set` and `get`.
+  + **[Ref](ref.md)** — `Ref[A]` models a mutable reference to a value of type `A`. The two basic operations are `set`, which fills the `Ref` with a new value, and `get`, which retrieves its current content. All operations on a `Ref` are atomic and thread-safe, providing a reliable foundation for synchronizing concurrent programs.
+- **[ZRefM](zrefm.md)** — A `ZRefM[RA, RB, EA, EB, A, B]` is a polymorphic, purely functional description of a mutable reference. 
+  + **[RefM](refm.md)** — `RefM[A]` models a **mutable reference** to a value of type `A` in which we can store **immutable** data, and update it atomically **and** effectfully.
+- **[Queue](queue.md)** — A `Queue` is an asynchronous queue that never blocks, which is safe for multiple concurrent producers and consumers.

docs/datatypes/promise.md → docs/datatypes/concurrency/promise.md

@@ -1,19 +1,27 @@
 ---
-id: datatypes_promise
-title:  "Promise"
+id: promise
+title: "Promise"
 ---
 
 A `Promise[E, A]` is a variable of `IO[E, A]` type that can be set exactly once.
 
-Promises are used to build higher level concurrency primitives, and are often used in situations where multiple `Fiber`s
-need to coordinate passing values to each other.
+Promise is a **purely functional synchronization primitive** which represents a single value that may not yet be available. When we create a Promise, it always started with an empty value, then it can be completed exactly once at some point, and then it will never become empty or modified again.
 
-## Creation
+Promise is a synchronization primitive. So, it is useful whenever we want to wait for something to happen. Whenever we need to synchronize a fiber with another fiber, we can use Promise. It allows us to have fibers waiting for other fibers to do things. Any time we want to handoff of a work from one fiber to another fiber or anytime we want to suspend a fiber until some other fiber does a certain amount of work, well we need to be using a Promise. Also, We can use `Promise` with `Ref` to build other concurrent primitives, like Queue and Semaphore. 
+
+By calling `await` on the Promise, the current fiber blocks, until that event happens. As we know, blocking thread in ZIO, don't actually block kernel threads. They are semantic blocking, so when a fiber is blocked the underlying thread is free to run all other fibers.
+
+Promise is the equivalent of Scala's Promise. It's almost the same, except it has two type parameters, instead of one. Also instead of calling `future`, we need to call `await` on ZIO Promise to wait for the Promise to be completed.
+
+Promises can be failed with a value of type `E` and succeeded that is completed with success with the value of type `A`. So there are two ways we can complete a Promise, with failure or success and then whoever is waiting on the Promise will get back that failure or success. 
 
-Promises can be created using `Promise.make[E, A]`, which returns `UIO[Promise[E, A]]`. This is a description of creating a promise, but not the actual promise. Promises cannot be created outside of IO, because creating them involves allocating mutable memory, which is an effect and must be safely captured in IO.
 
 ## Operations
 
+### Creation
+
+Promises can be created using `Promise.make[E, A]`, which returns `UIO[Promise[E, A]]`. This is a description of creating a promise, but not the actual promise. Promises cannot be created outside of IO, because creating them involves allocating mutable memory, which is an effect and must be safely captured in IO.
+
 ### Completing
 
 You can complete a `Promise[E, A]` in few different ways:
@@ -44,9 +52,7 @@ val race: IO[String, Int] = for {
   } yield value
 ```
 
-The act of completing a Promise results in an `UIO[Boolean]`, where
-the `Boolean` represents whether the promise value has been set (`true`) or whether it was already set (`false`).
-This is demonstrated below:
+The act of completing a Promise results in an `UIO[Boolean]`, where the `Boolean` represents whether the promise value has been set (`true`) or whether it was already set (`false`). This is demonstrated below:
 
 ```scala mdoc:silent
 val ioPromise1: UIO[Promise[Exception, String]] = Promise.make[Exception, String]
@@ -64,7 +70,7 @@ To re-iterate, the `Boolean` tells us whether or not the operation took place su
 was set with the value or the error.
 
 ### Awaiting
-You can get a value from a Promise using `await`, calling fiber will suspend until Promise is completed.
+We can get a value from a Promise using `await`, calling fiber will suspend until Promise is completed.
 
 ```scala mdoc:silent
 val ioPromise3: UIO[Promise[Exception, String]] = Promise.make[Exception, String]
@@ -73,18 +79,16 @@ val ioGet: IO[Exception, String] = ioPromise3.flatMap(promise => promise.await)
 
 ### Polling
 The computation will suspend (in a non-blocking fashion) until the Promise is completed with a value or an error.
-If you don't want to suspend and you only want to query the state of whether or not the Promise has been completed,
-you can use `poll`:
+
+If we don't want to suspend, and we only want to query the state of whether or not the Promise has been completed, we can use `poll`:
 
 ```scala mdoc:silent
 val ioPromise4: UIO[Promise[Exception, String]] = Promise.make[Exception, String]
 val ioIsItDone: UIO[Option[IO[Exception, String]]] = ioPromise4.flatMap(p => p.poll)
 val ioIsItDone2: IO[Option[Nothing], IO[Exception, String]] = ioPromise4.flatMap(p => p.poll.get)
 ```
 
-If the Promise was not completed when you called `poll` then the IO will fail with the `Unit` value otherwise,
-you obtain an `IO[E, A]`, where `E` represents if the Promise completed with an error and `A` indicates
-that the Promise successfully completed with an `A` value.
+If the Promise was not completed when we called `poll` then the IO will fail with the `Unit` value otherwise, we obtain an `IO[E, A]`, where `E` represents if the Promise completed with an error and `A` indicates that the Promise successfully completed with an `A` value.
 
 `isDone` returns `UIO[Boolean]` that evaluates to `true` if promise is already completed.
 
@@ -105,10 +109,8 @@ val program: ZIO[Console with Clock, IOException, Unit] =
     fiberA          <-  sendHelloWorld.fork
     fiberB          <-  getAndPrint.fork
     _               <-  (fiberA zip fiberB).join
-    } yield ()
+  } yield ()
 ```
 
-In the example above, we create a Promise and have a Fiber (`fiberA`) complete that promise after 1 second and a second
-Fiber (`fiberB`) will call `await` on that Promise to obtain a `String` and then print it to screen. The example prints
-`hello world` to the screen after 1 second. Remember, this is just a description of the program and not the execution
+In the example above, we create a Promise and have a Fiber (`fiberA`) complete that promise after 1 second and a second Fiber (`fiberB`) will call `await` on that Promise to obtain a `String` and then print it to screen. The example prints `hello world` to the screen after 1 second. Remember, this is just a description of the program and not the execution
 itself.

docs/datatypes/queue.md → docs/datatypes/concurrency/queue.md

@@ -1,6 +1,6 @@
 ---
-id: datatypes_queue
-title:  "Queue"
+id: queue
+title: "Queue"
 ---
 
 `Queue` is a lightweight in-memory queue built on ZIO with composable and transparent back-pressure. It is fully asynchronous (no locks or blocking), purely-functional and type-safe.