gthread.Thread.Thread Class Reference

List of all members.

Detailed Description

Description 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 if the program is not carefully designed. In particular, due to the concurrent nature of threads, no assumptions on the order of execution of code running in different threads can be made, unless order is explicitly forced by the programmer through synchronization primitives. The aim of the thread related functions in GLib is to provide a portable means for writing multi-threaded software. There are primitives for mutexes to protect the access to portions of memory (GMutex, GStaticMutex, G_LOCK_DEFINE, GStaticRecMutex and GStaticRWLock). There are primitives for condition variables to allow synchronization of threads (GCond). There are primitives for thread-private data - data that every thread has a private instance of (GPrivate, GStaticPrivate). Last but definitely not least there are primitives to portably create and manage threads (GThread). You must call g_thread_init() before executing any other GLib functions in a threaded GLib program. After that, GLib is completely thread safe (all global data is automatically locked), but individual data structure instances are not automatically locked for performance reasons. So, for example you must coordinate accesses to the same GHashTable from multiple threads. The two notable exceptions from this rule are GMainLoop and GAsyncQueue, which are threadsafe and needs no further application-level locking to be accessed from multiple threads.


Public Member Functions

GThreadgetThreadStruct ()
 this (GThread *gThread)
 Sets our main struct and passes it to the parent class.
void * join ()
 Waits until thread finishes, i.e.
void setPriority (GThreadPriority priority)
 Changes the priority of thread to priority.

Static Public Member Functions

static void init (GThreadFunctions *vtable)
 If you use GLib from more than one thread, you must initialize the thread system by calling g_thread_init().
static int supported ()
 This function returns TRUE if the thread system is initialized, and FALSE if it is not.
static Thread create (GThreadFunc func, void *data, int joinable, GError **error)
 This function creates a new thread with the default priority.
static Thread createFull (GThreadFunc func, void *data, uint stackSize, int joinable, int bound, GThreadPriority priority, GError **error)
 This function creates a new thread with the priority priority.
static Thread self ()
 This functions returns the GThread corresponding to the calling thread.
static void yield ()
 Gives way to other threads waiting to be scheduled.
static void exit (void *retval)
 Exits the current thread.
static void foreac (GFunc threadFunc, void *userData)
 Call thread_func on all existing GThread structures.
static void gStaticMutexInit (GStaticMutex *mutex)
 Initializes mutex.
static void gStaticMutexLock (GStaticMutex *mutex)
 Works like g_mutex_lock(), but for a GStaticMutex.
static int gStaticMutexTrylock (GStaticMutex *mutex)
 Works like g_mutex_trylock(), but for a GStaticMutex.
static void gStaticMutexUnlock (GStaticMutex *mutex)
 Works like g_mutex_unlock(), but for a GStaticMutex.
static Mutex gStaticMutexGetMutex (GStaticMutex *mutex)
 For some operations (like g_cond_wait()) you must have a GMutex instead of a GStaticMutex.
static void gStaticMutexFree (GStaticMutex *mutex)
 Releases all resources allocated to mutex.

Protected Member Functions

void * getStruct ()
 the main Gtk struct as a void*

Protected Attributes

GThreadgThread
 the main Gtk struct


Constructor & Destructor Documentation

gthread.Thread.Thread.this ( GThread gThread  ) 

Sets our main struct and passes it to the parent class.


Member Function Documentation

static Thread gthread.Thread.Thread.create ( GThreadFunc  func,
void *  data,
int  joinable,
GError **  error 
) [static]

This function creates a new thread with the default priority.

If joinable is TRUE, you can wait for this threads termination calling g_thread_join(). Otherwise the thread will just disappear when it terminates. The new thread executes the function func with the argument data. If the thread was created successfully, it is returned. error can be NULL to ignore errors, or non-NULL to report errors. The error is set, if and only if the function returns NULL. func: a function to execute in the new thread. data: an argument to supply to the new thread. joinable: should this thread be joinable? error: return location for error. Returns: the new GThread on success.

static Thread gthread.Thread.Thread.createFull ( GThreadFunc  func,
void *  data,
uint  stackSize,
int  joinable,
int  bound,
GThreadPriority  priority,
GError **  error 
) [static]

This function creates a new thread with the priority priority.

If the underlying thread implementation supports it, the thread gets a stack size of 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 calling g_thread_join(). Otherwise the thread will just disappear when it terminates. 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 func with the argument data. If the thread was created successfully, it is returned. error can be NULL to ignore errors, or non-NULL to report errors. The error is set, if and only if the function returns NULL. Note It is not guaranteed that threads with different priorities really behave accordingly. On some systems (e.g. Linux) there are no thread 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 G_THREAD_PRIORITY_NORMAL here as a default. Note Only use g_thread_create_full() if you really can't use g_thread_create() instead. g_thread_create() does not take stack_size, bound, and priority as arguments, as they should only be used in cases in which it is unavoidable. func: a function to execute in the new thread. data: an argument to supply to 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? priority: a priority for the thread. error: return location for error. Returns: the new GThread on success.

static void gthread.Thread.Thread.exit ( void *  retval  )  [static]

Exits the current thread.

If another thread is waiting for that thread using g_thread_join() and the current thread is joinable, the waiting thread will be woken up and get retval as the return value of g_thread_join(). If the current thread is not joinable, retval is ignored. Calling g_thread_exit (retval); is equivalent to calling return retval; in the function func, as given to g_thread_create(). Note Never call g_thread_exit() from within a thread of a GThreadPool, as that will mess up the bookkeeping and lead to funny and unwanted results. retval: the return value of this thread.

static void gthread.Thread.Thread.foreac ( GFunc  threadFunc,
void *  userData 
) [static]

Call thread_func on all existing GThread structures.

Note that threads may decide to exit while thread_func is running, so without intimate knowledge about the lifetime of foreign threads, thread_func shouldn't access the GThread* pointer passed in as first argument. However, thread_func will not be called for threads which are known to have exited already. Due to thread lifetime checks, this function has an execution complexity which is quadratic in the number of existing threads. thread_func: function to call for all GThread structures user_data: second argument to thread_func Since 2.10

void* gthread.Thread.Thread.getStruct (  )  [protected]

the main Gtk struct as a void*

GThread* gthread.Thread.Thread.getThreadStruct (  ) 

static void gthread.Thread.Thread.gStaticMutexFree ( GStaticMutex mutex  )  [static]

Releases all resources allocated to mutex.

You don't have to call this functions for a GStaticMutex with an unbounded lifetime, i.e. objects declared 'static', but if you have a GStaticMutex as a member of a structure and the structure is freed, you should also free the GStaticMutex. mutex: a GStaticMutex to be freed.

static Mutex gthread.Thread.Thread.gStaticMutexGetMutex ( GStaticMutex mutex  )  [static]

For some operations (like g_cond_wait()) you must have a GMutex instead of a GStaticMutex.

This function will return the corresponding GMutex for mutex. mutex: a GStaticMutex. Returns: the GMutex corresponding to mutex.

static void gthread.Thread.Thread.gStaticMutexInit ( GStaticMutex mutex  )  [static]

Initializes mutex.

Alternatively you can initialize it with G_STATIC_MUTEX_INIT. mutex: a GStaticMutex to be initialized.

static void gthread.Thread.Thread.gStaticMutexLock ( GStaticMutex mutex  )  [static]

Works like g_mutex_lock(), but for a GStaticMutex.

mutex: a GStaticMutex.

static int gthread.Thread.Thread.gStaticMutexTrylock ( GStaticMutex mutex  )  [static]

Works like g_mutex_trylock(), but for a GStaticMutex.

mutex: a GStaticMutex. Returns: TRUE, if the GStaticMutex could be locked.

static void gthread.Thread.Thread.gStaticMutexUnlock ( GStaticMutex mutex  )  [static]

Works like g_mutex_unlock(), but for a GStaticMutex.

mutex: a GStaticMutex.

static void gthread.Thread.Thread.init ( GThreadFunctions vtable  )  [static]

If you use GLib from more than one thread, you must initialize the thread system by calling g_thread_init().

Most of the time you will only have to call g_thread_init (NULL). Note Do not call g_thread_init() with a non-NULL parameter unless you really know what you are doing. Note g_thread_init() must not be called directly or indirectly as a callback from GLib. Also no mutexes may be currently locked while calling g_thread_init(). g_thread_init() might 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 this: if (!g_thread_supported ()) g_thread_init (NULL); After that line, either the thread system is initialized or, if no thread system is available in GLib (i.e. either G_THREADS_ENABLED is not defined or G_THREADS_IMPL_NONE is defined), the program will abort. 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. Note To use g_thread_init() in your program, you have to link with the libraries that the command pkg-config --libs gthread-2.0 outputs. This is not the case for all the other thread related functions of GLib. Those can be used without having to link with the thread libraries. vtable: a function table of type GThreadFunctions, that provides the entry points to the thread system to be used.

void* gthread.Thread.Thread.join (  ) 

Waits until thread finishes, i.e.

the function func, as given to g_thread_create(), returns or g_thread_exit() is called by thread. All resources of thread including the GThread struct are released. thread must have been created with joinable=TRUE in g_thread_create(). The value returned by func or given to g_thread_exit() by thread is returned by this function. thread: a GThread to be waited for. Returns: the return value of the thread.

static Thread gthread.Thread.Thread.self (  )  [static]

This functions returns the GThread corresponding to the calling thread.

Returns: the current thread.

void gthread.Thread.Thread.setPriority ( GThreadPriority  priority  ) 

Changes the priority of thread to priority.

Note It is not guaranteed that threads with different priorities really behave accordingly. On some systems (e.g. Linux) there are no thread 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. thread: a GThread. priority: a new priority for thread.

static int gthread.Thread.Thread.supported (  )  [static]

This function returns TRUE if the thread system is initialized, and FALSE if it is not.

Note This function is actually a macro. Apart from taking the address of it you can however use it as if it was a function. Returns: TRUE, if the thread system is initialized.

static void gthread.Thread.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.


Member Data Documentation

GThread* gthread.Thread.Thread.gThread [protected]

the main Gtk struct


SourceForge.net Logo DSource.org Logo digitalmars.com Logo