diff options
author | Alfredo Canziani <alfredo.canziani@gmail.com> | 2015-04-13 19:14:56 +0300 |
---|---|---|
committer | Alfredo Canziani <alfredo.canziani@gmail.com> | 2015-04-13 19:14:56 +0300 |
commit | 3d4db9b1fa5db46d38aaca8f7fb0cdae8d8ff8cb (patch) | |
tree | 7c2f64be17939e59ca91ecf131de2a09231e6552 | |
parent | af3104b265342f5aff6dcd610645d4a042e851ae (diff) |
Removed trailing white spaces
-rw-r--r-- | README.md | 120 | ||||
-rw-r--r-- | examples/simple.lua | 2 |
2 files changed, 61 insertions, 61 deletions
@@ -30,7 +30,7 @@ The magic of the *threads* package lies in the seven following points: <a name="install"/> # Installation # -At this time *threads* relies on two other packages: +At this time *threads* relies on two other packages: * [Torch7](torch.ch) (for serialization) ; and * [SDL2](https://github.com/torch/sdl2-ffi/blob/master/README.md) for threads. @@ -41,7 +41,7 @@ very portable, I believe this dependency should not be a problem. If there are enough requests, I might propose alternatives to SDL2 threads. Torch is used for full serialization. One could easily get inspired from -Torch serialization system to adapt the package to its own needs. +Torch serialization system to adapt the package to its own needs. Torch should be straighforward to install, so this dependency should be minor too. @@ -109,7 +109,7 @@ for i=1,njob do -- note that we can manipulate upvalues of the main thread -- as this callback is ran in the main thread! - jobdone = jobdone + 1 + jobdone = jobdone + 1 end ) end @@ -164,33 +164,33 @@ more advanced usage of `threads`. # Library # The library consists of two main classes and a serialization library: - + * [Threads](#threads.main) : a thread pool ; * [Worker](#worker) : a thread-safe task queue ; and * [serialize](#serialize) : functions for serialization and deserialization. <a name='threads.main'/> ## Threads ## -This class is used to manage a set of worker threads. The class is +This class is used to manage a set of worker threads. The class is returned upon requiring the package: ```lua Threads = require 'threads' ``` -Internally, a Threads instance uses two [Workers](#worker), +Internally, a Threads instance uses two [Workers](#worker), i.e. thread-safe task queues: - + * `mainworker` is used by the worker threads to communicate serialized `endcallback` functions back to the main thread ; and * `threadworker` is used by the main thread to communicate serialized `callback` function to the worker threads. - -It is important to note that there is only one `threadworker` such that there is no way of -knowing which `callback` job will be executed by which worker thread. -Internally, the worker threads consist of an infinite loop that waits for -the next job to be available on the `threadworker` queue. When a job is -available, one of the threads executes it and returns the results -back to the main thread via the `mainworker` queue. Upon receipt of the -results, an optional `endcallback` is executed on the main thread + +It is important to note that there is only one `threadworker` such that there is no way of +knowing which `callback` job will be executed by which worker thread. +Internally, the worker threads consist of an infinite loop that waits for +the next job to be available on the `threadworker` queue. When a job is +available, one of the threads executes it and returns the results +back to the main thread via the `mainworker` queue. Upon receipt of the +results, an optional `endcallback` is executed on the main thread (see [Threads:addjob](#threads.addjob)). Each thread has its own [lua_State](http://www.lua.org/pil/24.1.html). @@ -198,11 +198,11 @@ Each thread has its own [lua_State](http://www.lua.org/pil/24.1.html). <a name='threads'/> ### Threads(N,[f1,f2,...]) ### Argument `N` of this constructor specifies the number of worker threads -that will be spawned. The optional arguments `f1,f2,...` can be a list -of functions to execute in each worker thread. To be clear, all of -these functions will be executed in each thread. However, each optional -function `f` takes an argument `threadIdx` which is a number between -`1` and `N` identifying each thread. This could be used to make each +that will be spawned. The optional arguments `f1,f2,...` can be a list +of functions to execute in each worker thread. To be clear, all of +these functions will be executed in each thread. However, each optional +function `f` takes an argument `threadIdx` which is a number between +`1` and `N` identifying each thread. This could be used to make each thread have different behaviour. Example: @@ -216,24 +216,24 @@ Threads(4, <a name='threads.addjob'/> ### Threads:addjob(callback, [endcallback, ...]) ### This method is used to queue jobs to be executed by the pool of worker threads. -The `callback` is a function that will be executed in each worker thread -with the optional `...` arguments. +The `callback` is a function that will be executed in each worker thread +with the optional `...` arguments. The `endcallback` is a function that will be executed in the main thread -(the one calling this method). It defaults to `function() end`. +(the one calling this method). It defaults to `function() end`. -This method will return immediately, unless the [Worker](#worker) queue -is full, in which case it will wait (i.e. block) until one of the worker +This method will return immediately, unless the [Worker](#worker) queue +is full, in which case it will wait (i.e. block) until one of the worker threads retrieves a new job from the queue. -Before being executed in the worker thread, the `callback` and its -optional `...` arguments are serialized -by the main thread and unserialized by the worker. Other than through -the optional arguments, the main thread can also transfer data to +Before being executed in the worker thread, the `callback` and its +optional `...` arguments are serialized +by the main thread and unserialized by the worker. Other than through +the optional arguments, the main thread can also transfer data to the worker by using upvalues: ```lua local upvalue = 10 threads:addjob( - function() + function() workervalue = upvalue return 1 end, @@ -242,44 +242,44 @@ threads:addjob( end ) ``` -In the above example, each worker thread will have a global variable `workervalue` -which will contain a copy of the main thread's `upvalue`. Note that -if the main thread's upvalue were global, as opposed to `local` +In the above example, each worker thread will have a global variable `workervalue` +which will contain a copy of the main thread's `upvalue`. Note that +if the main thread's upvalue were global, as opposed to `local` it would not be an upvalue, and therefore would not be serialized along -with the `callback`. In which case, `workervalue` would be `nil`. +with the `callback`. In which case, `workervalue` would be `nil`. -In the same example, the worker also communicates a value to the main thread. -This is accomplished by having the `callback` return one ore many values which -will be serialized and unserialized as arguments to the `endcallback` function. -In this case a value of `1` is received by the main thread as argument `inc` to the +In the same example, the worker also communicates a value to the main thread. +This is accomplished by having the `callback` return one ore many values which +will be serialized and unserialized as arguments to the `endcallback` function. +In this case a value of `1` is received by the main thread as argument `inc` to the `endcallback` function, which then uses it to increment `upvalue`. This -demonstrates how communication between threads is easily achieved using -the `addjob` method. +demonstrates how communication between threads is easily achieved using +the `addjob` method. <a name='threads.dojob'/> ### Threads:dojob() ### -This method is used to tell the main thread to execute the next -`endcallback` in the queue (see [Threads:addjob](#threads.addjob)). If +This method is used to tell the main thread to execute the next +`endcallback` in the queue (see [Threads:addjob](#threads.addjob)). If no such job is available, the main thread of execution will wait (i.e. block) -until the `mainthread` Worker (i.e. queue) is filled with a job. -Therefore, it is important that every call to `dojob` be preceded by +until the `mainthread` Worker (i.e. queue) is filled with a job. +Therefore, it is important that every call to `dojob` be preceded by a call to `addjob`. <a name='threads.synchronize'/> ### Threads:synchronize() ### -This method will call [dojob](#threads.dojob) until all `callbacks` -and corresponding `endcallbacks` are executed on the worker and main -threads, respectively. This method will also raise an error for any +This method will call [dojob](#threads.dojob) until all `callbacks` +and corresponding `endcallbacks` are executed on the worker and main +threads, respectively. This method will also raise an error for any errors raised in the pool of worker threads. <a name='threads.terminate'/> ### Threads:terminate() ### -This method will call [synchronize](#threads.synchronize), +This method will call [synchronize](#threads.synchronize), terminate each worker and free their memory. <a name='worker'/> ## Worker ## -This class is in effect a thread-safe task queue. The class is +This class is in effect a thread-safe task queue. The class is returned upon requiring the sub-package: ```lua @@ -287,23 +287,23 @@ Worker = require 'threads.worker' ``` ### Worker(N) ### -The Worker constructor takes a single argument `N` which specifies the -maximum size of the queue. +The Worker constructor takes a single argument `N` which specifies the +maximum size of the queue. <a name='worker.addjob'/> ### Worker:addjob(callback, [...]) ### -This method is called by a thread to *put* a job in the queue. -The job is specified in the form of a `callback` function taking arguments `...`. -Both the `callback` function and `...` arguments are serialized before being -*put* into the queue. If the queue is full, i.e. it has more than +This method is called by a thread to *put* a job in the queue. +The job is specified in the form of a `callback` function taking arguments `...`. +Both the `callback` function and `...` arguments are serialized before being +*put* into the queue. If the queue is full, i.e. it has more than `N` jobs, the calling thread will wait (i.e. block) until a job is retrieved by another thread. <a name='worker.dojob'/> ### [res] Worker:dojob() ### -This method is called by a thread to *get*, unserialize and execute a job inserted -via [addjob](#worker.addjob) from the queue. A calling thread will wait -(i.e. block) until a new job can be retrieved. It returns to the calller +This method is called by a thread to *get*, unserialize and execute a job inserted +via [addjob](#worker.addjob) from the queue. A calling thread will wait +(i.e. block) until a new job can be retrieved. It returns to the calller whatever the job function returns after execution. <a name='serialize'/> @@ -316,11 +316,11 @@ serialize = require 'threads.serialize' <a name='serialize.save'/> ### [code_p, sz] serialize.save(func) ### -This function serializes function `func`. It returns +This function serializes function `func`. It returns * `code_p` : a constant ffi pointer to a C `char` array ; and * `sz` : the size of this array. - + <a name='serialize.load'/> ### [obj] serialize.load(code_p, sz) ### This function unserializes the outputs of a [serialize.save](#serialize.save). diff --git a/examples/simple.lua b/examples/simple.lua index cc3e408..81b510c 100644 --- a/examples/simple.lua +++ b/examples/simple.lua @@ -30,7 +30,7 @@ for i=1,njob do function(id) print(string.format("task %d finished (ran on thread ID %x)", i, id)) - jobdone = jobdone + 1 + jobdone = jobdone + 1 end ) end |