Warning, /frameworks/threadweaver/README.md is written in an unsupported language. File is not indexed.
0001 # ThreadWeaver 0002 0003 Helper for multithreaded programming 0004 0005 ## Introduction 0006 0007 ThreadWeaver is a helper for multithreaded programming. It uses a job-based 0008 interface to queue tasks and execute them in an efficient way. 0009 0010 You simply divide the workload into jobs, state the dependencies between the jobs 0011 and ThreadWeaver will work out the most efficient way of dividing the work between 0012 threads within a set of resource limits. 0013 0014 See the information on [use cases](@ref usecases) and 0015 [why multithreading can help](@ref multithreading), as well as the usage 0016 section below, for more detailed information. 0017 0018 0019 0020 ## Usage 0021 0022 If you are using CMake, you need to have 0023 0024 find_package(KF6ThreadWeaver NO_MODULE) 0025 0026 (or similar) in your CMakeLists.txt file, and you need to link to 0027 KF6::ThreadWeaver. 0028 0029 ThreadWeaver is a Job queue. It executes jobs in threads it internally manages. 0030 The minimum and maximum number of threads provided by a Weaver is set by the 0031 user. Jobs are regular QObjects, which allows users to connect to the `done()` 0032 signal to be notified when the Job has been executed. The Weaver class provides 0033 objects that handle a number of threads called the inventory. Users usually 0034 acquire a reference to a WeaverInterface object. 0035 0036 Jobs may depend on other jobs. A job will only execute if all jobs it depends 0037 on are already finished. In this, dependencies reorder job execution. If no 0038 dependencies are declared, jobs are executed in queueing order. Multiple 0039 dependencies are possible, which allows the creation of complex flow graphs 0040 that are automatically executed by the Weaver. It is important, though, to 0041 avoid circular dependencies. Two jobs that depend on each other in both 0042 directions will simply never be executed, since the dependencies will never 0043 resolve. 0044 0045 Threads are created on demand and do not exit until the containing weaver is 0046 deleted. Threads have an eager policy in trying to execute jobs out of the 0047 queue. The managing Weaver blocks them if no jobs are available. 0048 0049 WeaverObservers are used to receive more informative events about the thread 0050 states and job execution. They can be used to provide progress or debugging 0051 information or to implement GUIs to show the thread activity. Observers can be 0052 attached to Weavers and will disconnect automatically when they are deleted. 0053 0054 ### Job Execution 0055 0056 In general, jobs are executed in the order they are queued, if they have no 0057 unresolved dependencies. This behaviour can be used to balance I/O, network and 0058 CPU load. The SMIV example shows how this can be done. 0059 0060 ### Emitting Signals from Jobs 0061 0062 To notify the application's GUI of progress or other events, it may be 0063 desirable to emit signals from the Job objects that can be connected to the 0064 main thread. Since the job will be executed in another thread, such signals are 0065 delivered asynchronously. 0066 0067 The Job class in the ThreadWeaver library itself contains such a helper class 0068 that can be used as a reference for this approach. 0069 0070 ## Porting 0071 0072 Documentation about porting your code to newer versions is described in `docs/PORTING.md` 0073