Glib::Thread Class Reference

Represents a running thread. More...

#include <glibmm/thread.h>

Classes
class	Exit
	Exception class used to exit from a thread. More...

Public Member Functions
	Thread (const Thread &)=delete
Thread &	operator= (const Thread &)=delete
void	join ()
	Waits until the thread finishes. More...
bool	joinable () const
	Returns whether the thread is joinable. More...
void	set_priority (ThreadPriority priority)
	Changes the priority of the thread to priority. More...
ThreadPriority	get_priority () const
	Returns the priority of the thread. More...
GThread *	gobj ()
const GThread *	gobj () const

Static Public Member Functions
static Thread *	create (const sigc::slot< void > & slot, bool joinable=true)
	Creates a new thread with the priority THREAD_PRIORITY_NORMAL. More...
static Thread *	self ()
	Returns the Thread* corresponding to the calling thread. More...
static Thread *	create (const sigc::slot< void > & slot, unsigned long stack_size, bool joinable, bool bound, ThreadPriority priority)
	Creates a new thread with the priority priority. More...
static void	yield ()
	Gives way to other threads waiting to be scheduled. More...

Related Functions
(Note that these are not member functions.)
Thread *	wrap (GThread * gobject)

Detailed Description

Represents a running thread.

An instance of this class can only be obtained with create(), self(), or wrap(GThread*). It's not possible to delete a Thread object. If the thread is not joinable, its resources will be freed automatically when it exits. Otherwise, if the thread is joinable, you must call join() to avoid a memory leak.

Note

g_thread_exit() is not wrapped, because that function exits a thread without any cleanup. That's especially dangerous in C++ code, since the destructors of automatic objects won't be invoked. Instead, you can throw a Thread::Exit exception, which will be caught by the internal thread entry function.

You might have noticed that the thread entry slot doesn't have the usual void* return value. If you want to return any data from your thread you can pass an additional output argument to the thread's entry slot.

Deprecated:

Use Glib::Threads::Thread instead.

Constructor & Destructor Documentation

Thread()

Glib::Thread::Thread ( const Thread &  )

delete

Member Function Documentation

create() [1/2]

static Thread * Glib::Thread::create ( const sigc::slot< void > &  slot, bool  joinable = true  )

static

Creates a new thread with the priority THREAD_PRIORITY_NORMAL.

If joinable is true, you can wait for this thread's termination by calling join(). Otherwise the thread will just disappear, when ready.

The new thread executes the function or method slot points to. You can pass additional arguments using sigc::bind(). If the thread was created successfully, it is returned, otherwise a ThreadError exception is thrown.

Because sigc::trackable is not thread safe, if the slot represents a non-static class method (that is, it is created by sigc::mem_fun()), the class concerned should not derive from sigc::trackable.

Parameters

slot	A slot to execute in the new thread.
joinable	This parameter is now ignored because Threads are now always joinable.

Returns

The new Thread* on success.

Exceptions

Glib::ThreadError

create() [2/2]

static Thread * Glib::Thread::create ( const sigc::slot< void > &  slot, unsigned long  stack_size, bool  joinable, bool  bound, ThreadPriority  priority  )

static

Creates a new thread with the priority priority.

The stack gets the size stack_size or the default value for the current platform, if stack_size is 0.

If joinable is true, you can wait for this thread's termination by calling join(). Otherwise the thread will just disappear, when ready. If bound is true, this thread will be scheduled in the system scope, otherwise the implementation is free to do scheduling in the process scope. The first variant is more expensive resource-wise, but generally faster. On some systems (e.g. Linux) all threads are bound.

The new thread executes the function or method slot points to. You can pass additional arguments using sigc::bind(). If the thread was created successfully, it is returned.

Because sigc::trackable is not thread safe, if the slot represents a non-static class method (that is, it is created by sigc::mem_fun()), the class concerned should not derive from sigc::trackable.

Note

It is not guaranteed, that threads with different priorities really behave accordingly. On some systems (e.g. Linux) only root can increase priorities. On other systems (e.g. Solaris) there doesn't seem to be different scheduling for different priorities. All in all try to avoid being dependent on priorities. Use Glib::THREAD_PRIORITY_NORMAL here as a default.

Only use the extended create(const sigc::slot<void>&, unsigned long, bool, bool, ThreadPriority) function, when you really can't use the simple create(const sigc::slot<void>&, bool) instead. The latter overload does not take stack_size, bound and priority as arguments, as they should only be used for cases, where it is inevitable.

Parameters

slot	A slot to execute in the new thread.
stack_size	A stack size for the new thread, or 0.
joinable	Should this thread be joinable?
bound	Should this thread be bound to a system thread?
priority	A priority for the thread.

Returns

The new Thread* on success.

Exceptions

Glib::ThreadError

Deprecated:

Use the simpler create() method instead, because all Threads are now joinable, and bounds and priority parameters now have no effect.

get_priority()

ThreadPriority Glib::Thread::get_priority

(

)

const

Returns the priority of the thread.

Returns

The thread's priority.

Deprecated:

Thread priorities no longer have any effect.

gobj() [1/2]

GThread * Glib::Thread::gobj ( )

inline

gobj() [2/2]

const GThread * Glib::Thread::gobj ( ) const

inline

join()

void Glib::Thread::join

(

)

Waits until the thread finishes.

Waits until the thread finishes, i.e. the slot, as given to create(), returns or g_thread_exit() is called by the thread. (Calling g_thread_exit() in a C++ program should be avoided.) All resources of the thread including the Glib::Thread object are released. The thread must have been created with joinable = true.

joinable()

bool Glib::Thread::joinable

(

)

const

Returns whether the thread is joinable.

Returns

Whether the thread is joinable.

Deprecated:

All threads are now joinable.

operator=()

Thread & Glib::Thread::operator= ( const Thread &  )

delete

self()

static Thread * Glib::Thread::self ( )

static

Returns the Thread* corresponding to the calling thread.

Returns

The current thread.

set_priority()

void Glib::Thread::set_priority

(

ThreadPriority

priority

)

Changes the priority of the thread to priority.

Note

It is not guaranteed, that threads with different priorities really behave accordingly. On some systems (e.g. Linux) only root can increase priorities. On other systems (e.g. Solaris) there doesn't seem to be different scheduling for different priorities. All in all try to avoid being dependent on priorities.

Parameters

priority

A new priority for the thread.

Deprecated:

Thread priorities no longer have any effect.

yield()

static void Glib::Thread::yield ( )

static

Gives way to other threads waiting to be scheduled.

This function is often used as a method to make busy wait less evil. But in most cases, you will encounter, there are better methods to do that. So in general you shouldn't use this function.

Friends And Related Function Documentation

wrap()

Thread * wrap ( GThread *  gobject )

related

Deprecated:

Use Glib::Threads::wrap(GThread*) instead.