Deprecated thread API

Deprecated thread API — old thread APIs (for reference only)

Includes

#include <glib.h>

Description

These APIs are deprecated. You should not use them in new code. This section remains only to assist with understanding code that was written to use these APIs at some point in the past.

Functions

g_thread_supported ()

gboolean
g_thread_supported ();

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

For language bindings, g_thread_get_initialized() provides the same functionality as a function.

Returns

TRUE, if the thread system is initialized


g_thread_create ()

GThread *
g_thread_create (GThreadFunc func,
                 gpointer data,
                 gboolean joinable,
                 GError **error);

g_thread_create has been deprecated since version 2.32 and should not be used in newly-written code.

Use g_thread_new() instead

This function creates a new thread.

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.

This function returns a reference to the created thread only if joinable is TRUE. In that case, you must free this reference by calling g_thread_unref() or g_thread_join(). If joinable is FALSE then you should probably not touch the return value.

Parameters

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, or NULL

 

Returns

the new GThread on success


g_thread_create_full ()

GThread *
g_thread_create_full (GThreadFunc func,
                      gpointer data,
                      gulong stack_size,
                      gboolean joinable,
                      gboolean bound,
                      GThreadPriority priority,
                      GError **error);

g_thread_create_full has been deprecated since version 2.32 and should not be used in newly-written code.

The bound and priority arguments are now ignored. Use g_thread_new().

This function creates a new thread.

Parameters

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

ignored

 

priority

ignored

 

error

return location for error.

 

Returns

the new GThread on success.


g_thread_set_priority ()

void
g_thread_set_priority (GThread *thread,
                       GThreadPriority priority);

g_thread_set_priority has been deprecated since version 2.32 and should not be used in newly-written code.

Thread priorities no longer have any effect.

This function does nothing.

Parameters

thread

a GThread.

 

priority

ignored

 

g_thread_foreach ()

void
g_thread_foreach (GFunc thread_func,
                  gpointer user_data);

g_thread_foreach has been deprecated since version 2.32 and should not be used in newly-written code.

There aren't many things you can do with a GThread, except comparing it with one that was returned from g_thread_create(). There are better ways to find out if your thread is still alive.

Call thread_func on all GThreads that have been created with g_thread_create().

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.

Parameters

thread_func

function to call for all GThread structures

 

user_data

second argument to thread_func

 

Since: 2.10


g_mutex_new ()

GMutex *
g_mutex_new ();

g_mutex_new has been deprecated since version 2.32 and should not be used in newly-written code.

GMutex can now be statically allocated, or embedded in structures and initialised with g_mutex_init().

Allocates and initializes a new GMutex.

Returns

a newly allocated GMutex. Use g_mutex_free() to free


g_mutex_free ()

void
g_mutex_free (GMutex *mutex);

g_mutex_free has been deprecated since version 2.32 and should not be used in newly-written code.

GMutex can now be statically allocated, or embedded in structures and initialised with g_mutex_init().

Destroys a mutex that has been created with g_mutex_new().

Calling g_mutex_free() on a locked mutex may result in undefined behaviour.

Parameters

mutex

a GMutex

 

g_cond_new ()

GCond*
g_cond_new ();

g_cond_new has been deprecated since version 2.32 and should not be used in newly-written code.

GCond can now be statically allocated, or embedded in structures and initialised with g_cond_init().

Allocates and initializes a new GCond.

Returns

a newly allocated GCond. Free with g_cond_free()


g_cond_free ()

void
g_cond_free (GCond *cond);

g_cond_free has been deprecated since version 2.32 and should not be used in newly-written code.

GCond can now be statically allocated, or embedded in structures and initialised with g_cond_init().

Destroys a GCond that has been created with g_cond_new().

Calling g_cond_free() for a GCond on which threads are blocking leads to undefined behaviour.

Parameters

cond

a GCond

 

g_static_mutex_init ()

void
g_static_mutex_init (GStaticMutex *mutex);

g_static_mutex_init has been deprecated since version 2.32 and should not be used in newly-written code.

Use g_mutex_init()

Initializes mutex . Alternatively you can initialize it with G_STATIC_MUTEX_INIT.

Parameters

mutex

a GStaticMutex to be initialized.

 

g_static_mutex_lock ()

void
g_static_mutex_lock (GStaticMutex *mutex);

g_static_mutex_lock has been deprecated since version 2.32 and should not be used in newly-written code.

Use g_mutex_lock()

Works like g_mutex_lock(), but for a GStaticMutex.

Parameters

mutex

a GStaticMutex.

 

g_static_mutex_trylock ()

gboolean
g_static_mutex_trylock (GStaticMutex *mutex);

g_static_mutex_trylock has been deprecated since version 2.32 and should not be used in newly-written code.

Use g_mutex_trylock()

Works like g_mutex_trylock(), but for a GStaticMutex.

Parameters

mutex

a GStaticMutex.

 

Returns

TRUE, if the GStaticMutex could be locked.


g_static_mutex_unlock ()

void
g_static_mutex_unlock (GStaticMutex *mutex);

g_static_mutex_unlock has been deprecated since version 2.32 and should not be used in newly-written code.

Use g_mutex_unlock()

Works like g_mutex_unlock(), but for a GStaticMutex.

Parameters

mutex

a GStaticMutex.

 

g_static_mutex_get_mutex ()

GMutex *
g_static_mutex_get_mutex (GStaticMutex *mutex);

g_static_mutex_get_mutex has been deprecated since version 2.32 and should not be used in newly-written code.

Just use a GMutex

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 .

Parameters

mutex

a GStaticMutex.

 

Returns

the GMutex corresponding to mutex .


g_static_mutex_free ()

void
g_static_mutex_free (GStaticMutex *mutex);

g_static_mutex_free has been deprecated since version 2.32 and should not be used in newly-written code.

Use g_mutex_clear()

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.

Calling g_static_mutex_free() on a locked mutex may result in undefined behaviour.

Parameters

mutex

a GStaticMutex to be freed.

 

Types and Values

G_THREADS_IMPL_POSIX

#define G_THREADS_IMPL_POSIX

G_THREADS_IMPL_POSIX has been deprecated since version 2.32 and should not be used in newly-written code.

POSIX threads are in use on all non-Windows systems. Use G_OS_WIN32 to detect Windows.

This macro is defined if POSIX style threads are used.


G_THREADS_IMPL_WIN32

#define G_THREADS_IMPL_NONE

G_THREADS_IMPL_WIN32 has been deprecated since version 2.32 and should not be used in newly-written code.

Use G_OS_WIN32 to detect Windows.

This macro is defined if Windows style threads are used.


GStaticMutex

typedef struct _GStaticMutex GStaticMutex;

A GStaticMutex works like a GMutex.

Prior to GLib 2.32, GStaticMutex had the significant advantage that it doesn't need to be created at run-time, but can be defined at compile-time. Since 2.32, GMutex can be statically allocated as well, and GStaticMutex has been deprecated.

Here is a version of our give_me_next_number() example using a GStaticMutex:

1
2
3
4
5
6
7
8
9
10
11
12
13
int
give_me_next_number (void)
{
  static int current_number = 0;
  int ret_val;
  static GStaticMutex mutex = G_STATIC_MUTEX_INIT;

  g_static_mutex_lock (&mutex);
  ret_val = current_number = calc_next_number (current_number);
  g_static_mutex_unlock (&mutex);

  return ret_val;
}

Sometimes you would like to dynamically create a mutex. If you don't want to require prior calling to g_thread_init(), because your code should also be usable in non-threaded programs, you are not able to use g_mutex_new() and thus GMutex, as that requires a prior call to g_thread_init(). In theses cases you can also use a GStaticMutex. It must be initialized with g_static_mutex_init() before using it and freed with with g_static_mutex_free() when not needed anymore to free up any allocated resources.

Even though GStaticMutex is not opaque, it should only be used with the following functions, as it is defined differently on different platforms.

All of the g_static_mutex_* functions apart from g_static_mutex_get_mutex() can also be used even if g_thread_init() has not yet been called. Then they do nothing, apart from g_static_mutex_trylock() which does nothing but returning TRUE.

All of the g_static_mutex_* functions are actually macros. Apart from taking their addresses, you can however use them as if they were functions.


G_STATIC_MUTEX_INIT

#define G_STATIC_MUTEX_INIT

A GStaticMutex must be initialized with this macro, before it can be used. This macro can used be to initialize a variable, but it cannot be assigned to a variable. In that case you have to use g_static_mutex_init().

1
GStaticMutex my_mutex = G_STATIC_MUTEX_INIT;


G_STATIC_PRIVATE_INIT

#define G_STATIC_PRIVATE_INIT

Every GStaticPrivate must be initialized with this macro, before it can be used.

1
GStaticPrivate my_private = G_STATIC_PRIVATE_INIT;

See Also

GThread