Thread Support

Thread Support — Support for multi-threaded applications.

Synopsis




gboolean    gnetwork_thread_new             (GThreadFunc func,
                                             gpointer data,
                                             GDestroyNotify notify,
                                             GMainContext *context,
                                             GError **error);
void        gnetwork_thread_set_context     (GMainContext *context);
GMainContext* gnetwork_thread_get_context   (void);
guint       gnetwork_thread_idle_add        (GSourceFunc func,
                                             gpointer data);
guint       gnetwork_thread_idle_add_full   (gint priority,
                                             GSourceFunc func,
                                             gpointer data,
                                             GDestroyNotify notify);
guint       gnetwork_thread_timeout_add     (guint interval,
                                             GSourceFunc func,
                                             gpointer data);
guint       gnetwork_thread_timeout_add_full
                                            (gint priority,
                                             guint interval,
                                             GSourceFunc func,
                                             gpointer data,
                                             GDestroyNotify notify);
guint       gnetwork_thread_io_add_watch    (GIOChannel *channel,
                                             GIOCondition condition,
                                             GIOFunc func,
                                             gpointer data);
guint       gnetwork_thread_io_add_watch_full
                                            (GIOChannel *channel,
                                             gint priority,
                                             GIOCondition condition,
                                             GIOFunc func,
                                             gpointer data,
                                             GDestroyNotify notify);
gboolean    gnetwork_thread_source_remove   (guint id);

Description

These functions provide useful utilities for writing a thread-safe application using the GNetwork library.

Details

gnetwork_thread_new ()

gboolean    gnetwork_thread_new             (GThreadFunc func,
                                             gpointer data,
                                             GDestroyNotify notify,
                                             GMainContext *context,
                                             GError **error);

Convenience function to run func in a non-joinable thread. This function uses a global thread pool to cache up to 2 unused threads, improving the speed of creating a thread in most cases. The GNetwork DNS functions use this to create threaded DNS lookups, so most applications which use this library will benefit from using this function. After func has returned, notify will be called from inside the thread with data as it's argument.

func : the function to use for a thread.
data : the user_data to pass func, or NULL.
notify : a function to call with data as it's pointer when func has finished.
context : the GMainContext for the GMainLoop which will run in this thread, or NULL.
error : a location to contain thread errors, or NULL.
Returns : TRUE if the thread could be created, FALSE if an error occured.

Since 1.0


gnetwork_thread_set_context ()

void        gnetwork_thread_set_context     (GMainContext *context);

When a thread you have created will run it's own GMainLoop, you should associate the new mainloop's context with the thread via this function.

Alternatively, you can avoid using this function if you create your context first, and then create your thread with gnetwork_thread_new(). The setting/unsetting of the context will be handled automatically.

context : the main context to set for the current thread.

Since 1.0


gnetwork_thread_get_context ()

GMainContext* gnetwork_thread_get_context   (void);

This function is used to retrieve a reference to this thread's GMainContext which was set with gnetwork_thread_set_context(). The returned value should be unreferenced with g_main_context_unref() when no longer needed.

The main use of this function is to get the thread's context when manually creating GSource functions. Typically you will not need this function.

Returns : the current thread's associated GMainContext.

Since 1.0


gnetwork_thread_idle_add ()

guint       gnetwork_thread_idle_add        (GSourceFunc func,
                                             gpointer data);

Adds a function to be called whenever there are no higher priority events pending to the current thread's main loop. The function is given the default idle priority, G_PRIORITY_DEFAULT_IDLE. If the function returns FALSE it is automatically removed from the list of event sources and will not be called again.

Note: this function is actually a macro, so apart from taking it's reference, it should behave like a normal function.

func : the function to run.
data : the user data to pass to func.
Returns : the source ID.

Since 1.0


gnetwork_thread_idle_add_full ()

guint       gnetwork_thread_idle_add_full   (gint priority,
                                             GSourceFunc func,
                                             gpointer data,
                                             GDestroyNotify notify);

Adds an idle source which calls func when there are no events with a higher priority than priority to the current thread's main loop. If func returns FALSE, it will automatically be removed from the main loop, and data will be destroyed by notify. See g_idle_add() for more information.

priority : the priority to give within the thread to running func.
func : the function to add.
data : the user data to pass to func.
notify : a function capable of destroying data.
Returns : the source ID.

Since 1.0


gnetwork_thread_timeout_add ()

guint       gnetwork_thread_timeout_add     (guint interval,
                                             GSourceFunc func,
                                             gpointer data);

Adds a timeout source which runs func every interval microseconds at the default priority (G_PRIORITY_DEFAULT) to the current thread's main loop. If func returns FALSE, it will automatically be removed from the main loop. See gnetwork_thread_timeout_add_full() and g_timeout_add() for more information.

Note: this function is actually a macro, so apart from taking it's reference, it should behave like a normal function.

interval : the interval in microseconds between runs of func.
func : the function to run.
data : the user data to pass to func.
Returns : the source ID.

Since 1.0


gnetwork_thread_timeout_add_full ()

guint       gnetwork_thread_timeout_add_full
                                            (gint priority,
                                             guint interval,
                                             GSourceFunc func,
                                             gpointer data,
                                             GDestroyNotify notify);

Adds a timeout source which runs func every interval microseconds with the given priority to the current thread's main loop. If func returns FALSE, it will automatically be removed from the main loop, and data will be destroyed by notify. See g_timeout_add() for more information.

priority : the priority to give within the thread to running func.
interval : the interval in microseconds between runs of func.
func : the function to run.
data : the user data to pass to func.
notify : a function capable of destroying data, or NULL.
Returns : the source ID.

Since 1.0


gnetwork_thread_io_add_watch ()

guint       gnetwork_thread_io_add_watch    (GIOChannel *channel,
                                             GIOCondition condition,
                                             GIOFunc func,
                                             gpointer data);

Adds an event source to the current thread's main loop which calls func when condition is satisfied on channel. If func returns FALSE, the source will be removed.

Note: this function is actually a macro, so apart from taking it's reference, it should behave like a normal function.

channel : a GIOChannel.
condition : the condition to watch for.
func : the function to call when condition is satisfied.
data : the user data to pass to func.
Returns : the event source ID.

Since 1.0


gnetwork_thread_io_add_watch_full ()

guint       gnetwork_thread_io_add_watch_full
                                            (GIOChannel *channel,
                                             gint priority,
                                             GIOCondition condition,
                                             GIOFunc func,
                                             gpointer data,
                                             GDestroyNotify notify);

Adds an event source to the current thread's main loop at priority which calls func when condition is satisfied on channel. If func returns FALSE, the source will be removed, and notify will be called with data as it's argument.

channel : a GIOChannel.
priority : the priority of the GIOChannel source.
condition : the condition to watch for.
func : the function to call when condition is satisfied.
data : the user data to pass to func.
notify : a function to call when the source is removed.
Returns : the event source ID.

Since 1.0


gnetwork_thread_source_remove ()

gboolean    gnetwork_thread_source_remove   (guint id);

Removes the GSource which matches id from the current thread's main loop.

id : the source tag to remove.
Returns : TRUE if id was found and removed, FALSE if not.

Since 1.0