Module threads

The threads module provides functions for running code on the threads of a thread group — for example, application threads started via box.cfg{app_threads = ...}.

Below is a list of threads functions.

See also a comprehensive example of using application threads.

Parameters:

• group_name (string) — the name of a thread group, for example 'app' for application threads.
• func_name (string) — the name of a function. The function must be exported (see threads.export()).
• args (table, optional) — an array of values passed into expr as its Lua varargs (...).
• opts (table, optional) — dispatch options, including target — which thread(s) in the group to run expr on.

Currently, the only available option for call() and eval() functions is target, which must be set to either all or any or the ordinal thread number in the group (1-based). It determines the set of threads on which the function will be called:

• if set to all, the function will be called on all threads (default);
• if set to any, the function will be called on a thread picked randomly;
• if set to a number, the function will be called on the thread with the specified ordinal number in the group.

Returns

table — an array of results, one per target thread.

On success, both call() and eval() functions return an array of results, one per each thread where the code was executed:

• If the code was executed on one thread (the target was set to any or a number), the array will contain exactly one element.
• If the target was set to all, the number of elements in the array will equal the number of threads in the group.

If an error occurs while executing the function on any thread, the exception is re-raised.

Parameters:

• group_name (string) — the name of a thread group, for example 'app' for application threads.
• expr (string) — a Lua expression (source code) to evaluate on the target thread(s). Inside the expression, ... refers to the values passed in args.
• args (table, optional) — an array of values passed into expr as its Lua varargs (...).
• opts (table, optional) — dispatch options, including target — which thread(s) in the group to run expr on.

See more information on opts in threads.call() description above.

Returns

table — an array of results, one per target thread. See more information on return values in threads.call() description above.

If evaluating expr fails on any of the target threads, the error from the last failing thread is re-raised.

Example:

 
box.cfg{app_threads = 1}box.schema.space.create('test')box.space.test:create_index('primary')box.space.test:replace({1, 'x'})local rv = box.read_view.open({name = 'shared_read_view'})local threads = require('threads')threads.eval('app', [[  local rv = box.read_view.open({id = ...})  return rv.space.test:select()]], {rv.id})

Parameters:

• func_name (string) — the name of a local function that will be used for calling this function from threads.call().
• func (string) — implementation of a local function.

Returns

None

Example:

 
local threads = require('threads')box.iproto.export('test_func', function()    local info = threads.info()    return string.format('Hello from thread %s/%d',                         info.group_name, info.thread_id)end)

Parameters:

None

Returns

table with information about configured thread groups and the current thread. This table contains the following fields:

• group_name — name of the group to which the current thread belongs
• thread_id — ordinal number of the thread in its group
• groups — array of all thread groups. Each element here is a table with fields name and size.

Example

Having this configuration:

 
threads:  groups:    - name: app      size: 2    - name: sharding      size: 4groups:  group-001:    replicasets:      replicaset-001:        instances:          instance-001: {}

We launch tarantool in the interactive mode:

 
tarantool -n instance-001 -c config.yaml -i

Here is what threads.info() returns in the main thread:

 
tarantool> threads = require('threads')---...tarantool> threads.info()---- group_name: tx  thread_id: 1  groups:  - name: tx    size: 1  - name: app    size: 2  - name: sharding    size: 4...