A thread package for Lua and LuaJIT.

The documentation for the threads library is organized as follows

• Introduction
• Installation
• Examples
• Library

threads relies on Torch7 for serialization. It uses pthread, and Windows thread implementation. One could easily get inspired from Torch serialization system to adapt the package to its own needs. Torch should be straighforward to install, so this dependency should be minor too.

At this time, if you have torch7 installed, the installation can easily achieved with luarocks:

luarocks install threads

A simple example is better than convoluted explanations:

local threads = require 'threads'

local nthread = 4
local njob = 10
local msg = "hello from a satellite thread"


local pool = threads.Threads(
   nthread,
   function(threadid)
      print('starting a new thread/state number ' .. threadid)
      gmsg = msg -- get it the msg upvalue and store it in thread state
   end
)

local jobdone = 0
for i=1,njob do
   pool:addjob(
      function()
         print(string.format('%s -- thread ID is %x', gmsg, __threadid))
         return __threadid
      end,

      function(id)
         print(string.format("task %d finished (ran on thread ID %x)", i, id))
         jobdone = jobdone + 1
      end
   )
end

pool:synchronize()

print(string.format('%d jobs done', jobdone))

pool:terminate()

Typical output:

starting a new thread/state number 1
starting a new thread/state number 3
starting a new thread/state number 2
starting a new thread/state number 4
hello from a satellite thread -- thread ID is 1
hello from a satellite thread -- thread ID is 2
hello from a satellite thread -- thread ID is 1
hello from a satellite thread -- thread ID is 2
hello from a satellite thread -- thread ID is 4
hello from a satellite thread -- thread ID is 2
hello from a satellite thread -- thread ID is 1
hello from a satellite thread -- thread ID is 3
task 1 finished (ran on thread ID 1)
hello from a satellite thread -- thread ID is 4
task 2 finished (ran on thread ID 2)
hello from a satellite thread -- thread ID is 4
task 3 finished (ran on thread ID 1)
task 4 finished (ran on thread ID 2)
task 5 finished (ran on thread ID 4)
task 9 finished (ran on thread ID 4)
task 10 finished (ran on thread ID 4)
task 8 finished (ran on thread ID 3)
task 6 finished (ran on thread ID 2)
task 7 finished (ran on thread ID 1)
10 jobs done

See a neural network threaded training example for a more advanced usage of threads.

• Mid-level:
  • Threads: a thread pool ;
  • Queue: a thread-safe task queue ; and
  • serialize: functions for serialization and deserialization.
  • safe: make a function thread-safe.
• Low-level:
  • Thread: a single thread with no artifice ;
  • Mutex: a thread mutex ;
  • Condition: a condition variable.
  • Atomic counter: lock free atomic counter

Soon some more high-level features will be proposed, built on top of Threads.

local threads = require 'threads'
local t = threads.Threads(4) -- create a pool of 4 threads

local Threads = require 'threads'
local t = Threads(4) -- create a pool of 4 threads

Internally, a Threads instance uses several Queues, i.e. thread-safe task queues:

• mainqueue is used by the queue threads to communicate serialized endcallback functions back to the main thread; and
• threadqueue is used by the main thread to communicate serialized callback function to the queue threads.
• threadspecificqueues are used by the main thread to communicate serialized callback function to a specific thread.

Internally, the queue threads consist of an infinite loop that waits for the next job to be available on the threadqueue queue. The queue threads can be switched from "specific" mode (in which case each thread i is looking at jobs put in its specific threadspecificqueues[i] queue, or non-specific mode (in which case, threads are looking at available jobs in threadqueue. Specific and non-specific mode can be switched with Threads:specific(boolean).

When a job is available, one of the threads executes it and returns the results back to the main thread via the mainqueue queue. Upon receipt of the results, an optional endcallback is executed on the main thread (see Threads:addjob()).

There are no guarantee that all jobs are executed until Threads:synchronize() is called.

Each thread has its own lua_State. However, we provide a serialization scheme which allows automatic sharing for several Torch objects (storages, tensors and tds types). Sharing of vanilla lua objects is not possible, but instances of classes that support serialization (eg. classic objects with using require 'classic.torch' or those created with torch.class) can be shared, but remember that only the memory in tensor storages and tds objects will be shared by the instances, other fields will be copies. Also if synchronization is required that must be implemented by the user (ie. with mutex).

threads.Threads(4,
   function(threadid)
      print("Initializing thread " .. threadid)
   end
)

Note that the id of each thread is also stored into the global variable __threadid (in each thread Lua state).
Notice about Upvalues:
When deserializing a callback, upvalues must be of known types. Since f1,f2,... in threads.Threads() are deserialized in order, we suggest that you make a separated f1 containing all the definitions and put the other code in f2,f3,.... e.g.

require 'nn'
local threads = require 'threads'
local model = nn.Linear(5, 10)
threads.Threads(
    2,
    function(idx)                       -- This code will crash
        require 'nn'                    -- because the upvalue 'model' 
        local myModel = model:clone()   -- is of unknown type before deserialization
    end
)

require 'nn'
local threads = require 'threads'
local model = nn.Linear(5, 10)
threads.Threads(
    2,
    function(idx)                      -- This code is OK.
        require 'nn'
    end,                               -- child threads know nn.Linear when deserializing f2
    function(idx)
        local myModel = model:clone()  -- because f1 has already been executed
    end
)

Switch the Threads system into specific (true) or non-specific (false) mode. In specific mode, one must provide the thread index which is going to execute a given job (when calling addjob()). In non-specific mode, the first available thread will execute the first available job.

Switching from specific to non-specific, or vice-versa, will first synchronize the current running jobs.

The id is the thread number that will be executing the given job. It must be passed in specific mode, and is absent in non-specific mode. The callback is a function that will be executed in each queue 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.

This method will return immediately, unless the Queue queue is full, in which case it will wait (i.e. block) until one of the queue threads retrieves a new job from the queue.

Before being executed in the queue thread, the callback and its optional ... arguments are serialized by the main thread and unserialized by the queue. Other than through the optional arguments, the main thread can also transfer data to the queue by using upvalues:

local upvalue = 10
pool:addjob(
   function()
      queuevalue = upvalue
      return 1
   end,
   function(inc)
      upvalue = upvalue + inc
   end
)

In the above example, each queue thread will have a global variable queuevalue 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, queuevalue would be nil.

In the same example, the queue 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.

In general, this method should not be called, except if one wants to use the async capabilities of the Threads class. Instead, synchronize() should be called to make sure all jobs are executed.

A serialization package (pkgname) should return a table of serialization functions when required (save and load). See serialize specifications for more details.

By default the serialization system uses the 'threads.serialize' sub-package, which leverages torch serialization.

The 'threads.sharedserialize' sub-package is also provided, which transparently shares the storages, tensors and tds C data structures. This approach is great if one needs to pass large data structures between threads. See the shared example for more details.

In specific mode, id must be a number and the function will return true if the corresponding thread queue is not full, false otherwise.

In non-specific mode, id should not be passed, and the function will return true if the global thread queue is not full, false otherwise.

The methods acceptsjob() and hasjob() allow you to use the threads.Threads in an asynchronous manner, without the need of calling synchronize(). See the asynchronous example for a typical test case.

Queue = require 'threads.queue'

The Queue constructor takes a single argument N which specifies the maximum size of the queue.

serialize = require 'threads.serialize'

Dive-in low-level features with the provided example.

The threads.Thread class simply starts a thread, and executes a given Lua code in this thread. It is up to the user to manage the event loop (if one is needed) to communicate with the thread. The class threads.Threads is an built upon this class.

Returns a thread id, and execute the code given as a string. The thread must be freed with free().

Standard mutex.

Returns a new mutex. If id is given, it must be a number returned by another mutex with id(), in which case the returned mutex is equivalent to the one uniquely referred by id.

A mutex must be freed with free().

Unlock the given mutex. This method call must follow a lock() call.

Standard condition variable.

Returns a new condition variable. If id is given, it must be a number returned by another condition variable with id(), in which case the returned condition is equivalent to the one uniquely referred by id.

A condition must be freed with free().

tds.AtomicCounter has been implemented to be used with sharedserialize to provide fast and safe lockless counting of progress (steps) between threads. See example for usage.