Xfce Foundation Classes

Main Page  | Index |  Namespace List  |  Alphabetical List  |  Class List  |  File List

Xfc::G::Thread Class Reference

A GThread C++ wrapper interface. More...

#include <xfc/glib/thread.hh>

List of all members.

Public Types

• typedef sigc::slot< void > ThreadSlot

  Signature of the callback slot to execute in the new thread.
  

Public Member Functions

Accessors

• GThread * g_thread () const

  Get a pointer to the GThread structure.
  

• bool is_joinable () const

  Determines whether the thread is joinable.
  

• ThreadPriority get_priority () const

  Returns the thread priority.
  

Methods

• void join ()

  Waits until the thread finishes, that is, the callback slot as given to the constructor returns, or exit() is called by the thread.
  

• void set_priority (ThreadPriority priority)

  Sets the priority of thread to priority.
  

Static Public Member Functions

Constructors

• Thread * create (const ThreadSlot &slot, bool joinable, G::Error *error=0)

  Create a new thread with the default priority.
  

• Thread * create (const ThreadSlot &slot, unsigned long stack_size, bool joinable, bool bound, G::Error *error=0)

  Create a new thread with the default priority and the specified stack size.
  

Accessors

• bool supported ()

  This method returns, whether the thread system is initialized or not.
  

• Thread * self ()

  This method returns the Thread corresponding to the calling thread.
  

Methods

• void init (GThreadFunctions *vtable=0)

  Before you use a thread related method, call init() to initialize the thread system.
  

• void yield ()

  Gives way to other threads waiting to be scheduled.
  

• void exit ()

  Exits the current thread.
  

---

Detailed Description

A GThread C++ wrapper interface.

Threads act almost like processes, but unlike processes all threads of one process share the same memory. This is good, as it provides easy communication between the involved threads via this shared memory, and it is bad, because strange things (so called Heisenbugs) might happen, when the program is not carefully designed. Especially bad is, that due to the concurrent nature of threads no assumptions on the order of execution of different threads can be done unless explicitly forced by the programmer through synchronization primitives.

The aim of the thread related classes is to provide a portable means for writing multi-threaded software. There are primitives for mutexes to protect the access to portions of memory (Mutex, StaticMutex, RecMutex, StaticRecMutex, RWLock and StaticRWLock), there are primitives for condition variables to allow synchronization of threads (Condition) and finally there are primitives for thread-private data, that every thread has a private instance of (Private, StaticPrivate). Last but definitely not least there are primitives to portably create and manage threads (Thread).

A thread of execution has an initial function. For the program's initial thread, the initial function is main(). For a G::Thread, the initial function is the call() or operator() function of the slot object passed to G::Thread::create(). A thread of execution is finished executing when its initial function returns or is terminated by calling exit().

A Thread object has an associated state which is either joinable or non-joinable. If a thread is joinable you can wait for the threads termination by calling join(). If a thread is non-joinable, the thread will just disappear when its finished executing.

The lifetime of a thread of execution may be different from the thread object. After a call to join(), the thread of execution will no longer exist even though the thread object will continue to exist until the end of its normal lifetime. The converse is also true; if a thread object is destroyed without a call to join(), the thread of execution continues until its initial function returns.

---

Member Typedef Documentation

typedef sigc::slot<void> Xfc::G::Thread::ThreadSlot

Signature of the callback slot to execute in the new thread. Example: Method signature for ThreadSlot. void method();

---

Member Function Documentation

Thread* Xfc::G::Thread::create (  const ThreadSlot &  slot, unsigned long  stack_size, bool  joinable, bool  bound, G::Error *  error = 0 )  [static]

Create a new thread with the default priority and the specified stack size. Parameters: slot  The callback slot to execute in the new thread. stack_size  A stack size for the new thread. joinable  Should this thread be joinable? bound  Should this thread be bound to a system thread? error  The return location for a G::Error. Returns: A pointer to the new thread on success, or null if an error occurs. The new thread executes the callback slot slot. The slot is owned by this method and will be released when the thread terminates. This means that you can construct and pass a slot inline, as you would when pass a slot to a signal. If you want to keep the slot around you will have to store a referenced pointer to it somewhere. 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 threads termination by calling join(). Otherwise the thread will just disappear, when ready. If bound is true, the 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 calls the callback slot slot. If the thread could not be created successfully, error is set. Note: Only use this method when you really have to. The stack_size, and bound arguments should only be used for cases where it's inevitable.

Thread* Xfc::G::Thread::create (  const ThreadSlot &  slot, bool  joinable, G::Error *  error = 0 )  [static]

Create a new thread with the default priority. Parameters: slot  The callback slot to execute in the new thread. joinable  Should this thread be joinable? error  The return location for a G::Error, or null. Returns: A pointer to the new thread on success, or null if an error occurs. The new thread executes the callback slot slot. The slot is owned by this method and will be released when the thread terminates. This means that you can construct and pass a slot inline, as you would when pass a slot to a signal. If you want to keep the slot around you will have to store a referenced pointer to it somewhere. If joinable is true, you can wait for this threads termination by calling join(). Otherwise the thread will just disappear, when ready. The error argument can be null to ignore errors, or non-null to report errors. The error is set, if and only if the thread could not be created.

void Xfc::G::Thread::exit (   )  [static]

Exits the current thread. If another thread is waiting for that thread using join() and the current thread is joinable, the waiting thread will be woken up. Note: Never call exit() from within a thread of a ThreadPool, as that will mess up the bookkeeping and lead to funny and unwanted results.

void Xfc::G::Thread::init (  GThreadFunctions *  vtable = 0  )  [static]

Before you use a thread related method, call init() to initialize the thread system. Parameters: vtable  A function table of type GThreadFunctions, that provides the entry points to the thread system to be used. Most of the time you will only have to call init(null). Note you should only call init() with a non-null parameter if you really know what you are doing. init() must not be called directly or indirectly as a callback from GLib. Also no mutexes may be currently locked, while calling init(). Note, do not call gdk_threads_init(). This method calls gdk_threads_init() for you. init() can only be called once. On the second call it will abort with an error. If you want to make sure, that the thread system is initialized, you can do that too: Example: Checking if the thread system has been initialized. if (!G::Thread::supported()) G::Thread::init(); After that line either the thread system is initialized or the program will abort, if no thread system is available in GLib, i.e. either G_THREADS_ENABLED is not defined or G_THREADS_IMPL_NONE is defined. If no thread system is available and vtable is null or if not all elements of vtable are non-null, then G::Thread::init() will abort. To Initialize the thread system with errorcheck mutexes vtable must be null and G_ERRORCHECK_MUTEXES must be defined.

bool Xfc::G::Thread::is_joinable (   )  const

Determines whether the thread is joinable. Returns: true if the thread is joinable.

void Xfc::G::Thread::join (   )

Waits until the thread finishes, that is, the callback slot as given to the constructor returns, or exit() is called by the thread. All resources of thread including the GThread struct are released. The thread must have been created with joinable=true in the constructor.

Thread* Xfc::G::Thread::self (   )  [static]

This method returns the Thread corresponding to the calling thread. Returns: A pointer to the current thread.

void Xfc::G::Thread::set_priority (  ThreadPriority  priority  )

Sets the priority of thread to priority. Parameters: priority  A priority for the thread. 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.

bool Xfc::G::Thread::supported (   )  [static]

This method returns, whether the thread system is initialized or not. Returns: true if the thread system is initialized.

void Xfc::G::Thread::yield (   )  [static]

Gives way to other threads waiting to be scheduled. This method is often used as a way to make a busy wait less evil. But in most cases, you will encounter, there are better ways to do that. So in general you shouldn't use this function.

---

The documentation for this class was generated from the following file:

• thread.hh

---

Copyright © 2004-2005 The XFC Development Team

XFC 4.3