Merge pull request #138 from marktwtn/doc-change

Update documents

README.md

@@ -1,6 +1,6 @@
 # dcurl - Multi-threaded Curl implementation
 
-[![Build Status](https://travis-ci.org/DLTcollab/dcurl.svg?branch=develop)](https://travis-ci.org/DLTcollab/dcurl)
+[![Build Status](https://badge.buildkite.com/46ec07b122bde13f984c241fe8b38e64698c5c0d816ee6c7e4.svg)](https://buildkite.com/dltcollab/dcurl-test)
 ![Supported IRI version](https://img.shields.io/badge/Supported%20IRI%20Version-1.6.0-brightgreen.svg)
 ![Release version](https://img.shields.io/github/release-pre/DLTcollab/dcurl.svg)
 

docs/build-n-test.md

@@ -1,12 +1,12 @@
 # Building and Testing
 
 ## Prerequisites
-* You need to configure paths and flags of OpenCL installation in `mk/opencl.mk`.
 * Check JDK installation and set environment variable `JAVA_HOME` if you wish to specify.
 * If target platform lacks of Intel SSE instructions, multi-threaded pure C implementation would be used as the fallback.
+* Install the OpenCL and GPU driver before calculating the PoW with GPU.
 * For FPGA-based hardware accelerator, [Lampa Lab's Cyclone V FPGA PoW](https://github.com/LampaLab/iota_fpga) is taken as the basis.
      - File `soc_system.rbf` is only valid for DE10-nano board, and you have to synthesize to get appropriate `soc_system.rbf` for Arrow SoCKit board.
-     - [RBF file](https://github.com/ajblane/dcurl/releases/tag/v1.0-SoCKit) can be downloaded from our release.
+     - [RBF file](https://github.com/DLTcollab/iota_fpga/releases/tag/v0.3-sockit) can be downloaded from our release.
      - Moreover, you need to download [Lampa Lab-provided Linux image](https://github.com/LampaLab/iota_fpga/releases/tag/v0.1) to flash into the micro-SD card. The root password is `123456`.
 
 

docs/threading-model.md

@@ -0,0 +1,28 @@
+# Threading model
+In `dcurl`, it calls the APIs provided by the `libtuv` submodule to use the threads and thread pool.
+
+## Thread pool size
+The thread pool size initialization is written in the function `init_once()`.\
+The environment variable `UV_THREADPOOL_SIZE` can be used to overwrite the default pool size.\
+Default pool size: 4\
+Maximum pool size: 128
+
+The current `dcurl` implementation can not affect the thread pool size. 
+
+## Thread pool mechanism
+The thread pool and the work request queue are global.\
+Work request can be treated as the function you would like to request the thread to execute.
+
+In the thread pool initialization phase, the threads are created and execute the infinite loop function `worker()`.\
+The infinite loop makes the thread blocked with the function `uv_cond_wait()`, and it can be unblocked with the function `uv_cond_signal()`.
+
+The function `uv_queue_work()` push the work request into the queue and unblock one of the blocked threads.
+Then the unblocked thread pops out the work request from the queue and execute it.\
+If all the threads are busy, the first thread finishing its job would check the non-empty queue, pop out the work request and execute it.
+
+In `dcurl`, it calls the function `uv_queue_work()` and passes the arguments with the PoW calculation function pointer and necessary data.\
+If the thread pool is large enough, the specified number of threads (which is the argument of `dcurl_entry()`) can be unblocked and fully utilized.\
+Otherwise, the `dcurl` would not be able to use as many threads as it specified at the same time.
+
+## Thread affinity
+The current thread pool mechanism does not take thread affinity into consideration.