class SF::Thread
inherits Reference
#
Utility class to manipulate threads
Threads provide a way to run multiple parts of the code in parallel. When you launch a new thread, the execution is split and both the new thread and the caller run in parallel.
To use a SF::Thread
, you construct it directly with the
function to execute as the entry point of the thread.
SF::Thread
has multiple template constructors, which means
that you can use several types of entry points:
- non-member functions with no argument
- non-member functions with one argument of any type
- functors with no argument (this one is particularly useful for compatibility with boost/std::%bind)
- functors with one argument of any type
- member functions from any class with no argument
The function argument, if any, is copied in the SF::Thread
instance, as well as the functor (if the corresponding
constructor is used). Class instances, however, are passed
by pointer so you must make sure that the object won't be
destroyed while the thread is still using it.
The thread ends when its function is terminated. If the
owner SF::Thread
instance is destroyed before the
thread is finished, the destructor will wait (see wait()
)
Usage examples:
# example 1: non member function with one argument
void threadFunc(int argument)
// [...]
end
thread = SF::Thread.new(&threadFunc, 5)
thread.launch() # start the thread (internally calls threadFunc(5))
# example 2: member function
class Task
public:
void run()
// [...]
end
end
Task task
thread = SF::Thread.new(&Task.run, &task)
thread.launch() # start the thread (internally calls task.run())
# example 3: functor
struct Task
void operator()()
// [...]
end
end
thread = SF::Thread.new(Task())
thread.launch() # start the thread (internally calls operator() on the Task instance)
Creating parallel threads of execution can be dangerous:
all threads inside the same process share the same memory space,
which means that you may end up accessing the same variable
from multiple threads at the same time. To prevent this
kind of situations, you can use mutexes (see SF::Mutex
).
See also: SF::Mutex
Included modules
SF::NonCopyable
Constructors#
.new(function : -> )
#
Construct the thread from a functor with an argument
This constructor works for function objects, as well as free functions. It is a template, which means that the argument can have any type (int, std::string, void*, Toto, ...).
Use this constructor for this kind of function:
void function(int arg)
# --- or ----
struct Functor
void operator()(std::string arg)
end
Note: this does not run the thread, use launch()
.
- function - Functor or free function to use as the entry point of the thread
- argument - argument to forward to the function
Methods#
#finalize
#
Destructor
This destructor calls wait()
, so that the internal thread
cannot survive after its SF::Thread
instance is destroyed.
#launch
#
Run the thread
This function starts the entry point passed to the thread's constructor, and returns immediately. After this function returns, the thread's function is running in parallel to the calling code.
#terminate
#
Terminate the thread
This function immediately stops the thread, without waiting for its function to finish. Terminating a thread with this function is not safe, and can lead to local variables not being destroyed on some operating systems. You should rather try to make the thread function terminate by itself.
#wait
#
Wait until the thread finishes
This function will block the execution until the thread's function ends.
Warning
If the thread function never ends, the calling thread will block forever. If this function is called from its owner thread, it returns without doing anything.