Table of Contents


qthread_init, qthread_initialize - initialize the qthread library


#include <qthread.h>

qthread_init (qthread_shepherd_id_t nshepherds);

qthread_initialize ();


Use these functions to initialize the qthreads environment before using any other qthread functions. The qthread_init() function is deprecated in favor of qthread_initialize() which will attempt to auto-detect the correct number of shepherds for the system. The number of shepherds can be forcibly specified with the environment variable QTHREAD_NUM_SHEPHERDS. The qthread_init() function is a wrapper around qthread_initialize() that simply exports the QTHREAD_NUM_SHEPHERDS environment variable. If QTHREAD_NUM_SHEPHERDS is 0 or unset, the library will attempt to guess the correct number of shepherds, defaulting to a single shepherd if no information about the system could be found. Shepherds will attempt to pin themselves to processors using whatever CPU affinity libraries are available.


The operation of qthread_init() is modified by several environment variables. All environment variables may begin with either QTHREAD_ or QT_; they are treated the same by Qthreads. The following environment variables may be considered (not all apply to all environments):
This variable controls what kind of status information is printed during initialization. If this variable is set to "1", Qthreads will print the number of shepherds, the number of workers per shepherd, and the stack size of each qthread to stdout. If this variable is set to "2", Qthreads will additionally print the name and value of every environment variable that it checks.
If this variable is set to "no", then the shepherds will not pin themselves to specific locations.
This variable is used to control the verbosity of debug messages that get printed at runtime. Higher numbers increase the verbosity; a value of 0 is the same as being unset, which prevents debug messages from being printed. This is only applicable if debugging has been enabled when the library was built.
This variable adjusts the size of the stacks that will be created for each thread. Changes to this value during the course of the program run are ignored; the value is only considered when qthread_init() is run.
This variable specifies how many shepherds to create.
This variable specifies how many worker threads to assign to each shepherd. This setting is ignored by some schedulers that only allow one worker per shepherd.
This variable specifies how much hardware parallelism to use. It allows the number of shepherds and worker threads per shepherd to be chosen according to the machine topology while only specifying how many may be running. If this number does not divide evenly among the appropriate number of shepherds, extra workers will be created but will begin in a disabled state.
This variable controls the amount of memory preallocated for storing argument data per task. Not all tasks have memory preallocated for argument data, but when they do, the amount is controlled by this environment variable.
This variable is similar to the previous variable, but instead of argument data, it controls the size of the preallocated per-task scratchpad.
This variable applies to certain work-stealing schedulers (such as the default Sherwood scheduler) and controls the number of tasks stolen during load-balancing operations. By default, or when this variable is set to zero, half of the victim’s work is stolen. Otherwise, thief workers will attempt to steal at most this many tasks.
This variable controls the maximum number of threads that can be spawned to service the I/O subsystem’s queue. In effect, it limits the amount of OS overhead that the I/O subsystem can consume.
This variable controls how long each I/O subsystem thread will wait for additional work before exiting.
This variable is used to control shepherd affinity. Essentially, it sets the physical boundary that the shepherd will represent. Currently only used when using the hwloc library. Valid values are: node, cache, socket, core, pu, L1cache, L2cache, L3cache, and L4cache.
This variable is used to control worker thread affinity; essentially it controls worker spacing. For example, one could force a single shepherd to cover a whole node with the QTHREAD_SHEPHERD_BOUNDARY, and then use this variable to put one worker on each socket. The valid values are the same as for QTHREAD_SHEPHERD_BOUNDARY, but this one MUST be lower in the topology hierarchy than the shepherd boundary. The default is "pu".

Return Value

On success, the system is ready to fork threads and 0 is returned. On error, an non-zero error code is returned.


Not enough memory could be allocated.

See Also


Table of Contents