![]() |
![]() |
![]() |
GNOME Data Access 4 manual | ![]() |
---|---|---|---|---|
#include <libgda/thread-wrapper/gda-thread-wrapper.h> GdaThreadWrapper; GdaThreadWrapper* gda_thread_wrapper_new (void); gpointer (*GdaThreadWrapperFunc) (gpointer arg, GError **error); guint gda_thread_wrapper_execute (GdaThreadWrapper *wrapper, GdaThreadWrapperFunc func, gpointer arg, GDestroyNotify arg_destroy_func, GError **error); void (*GdaThreadWrapperVoidFunc) (gpointer arg, GError **error); guint gda_thread_wrapper_execute_void (GdaThreadWrapper *wrapper, GdaThreadWrapperVoidFunc func, gpointer arg, GDestroyNotify arg_destroy_func, GError **error); void gda_thread_wrapper_iterate (GdaThreadWrapper *wrapper, gboolean may_block); gpointer gda_thread_wrapper_fetch_result (GdaThreadWrapper *wrapper, gboolean may_lock, guint exp_id, GError **error); gint gda_thread_wrapper_get_waiting_size (GdaThreadWrapper *wrapper); void (*GdaThreadWrapperCallback) (GdaThreadWrapper *wrapper, gpointer instance, const gchar *signame, gint n_param_values, const GValue *param_values, gpointer gda_reserved, gpointer data); gulong gda_thread_wrapper_connect_raw (GdaThreadWrapper *wrapper, gpointer instance, const gchar *sig_name, GdaThreadWrapperCallback callback, gpointer data); void gda_thread_wrapper_disconnect (GdaThreadWrapper *wrapper, gulong id);
The purpose of the GdaThreadWrapper object is to execute functions in an isolated sub thread. As the GdaThreadWrapper is thread safe, one is able to isolate some code's execution is a private thread, and make a non thread safe code thread safe.
The downside of this is that the actual execution of the code will be slower as it requires threads to be synchronized.
Each thread using a GdaThreadWrapper object can use it as if it was the only user: the GdaThreadWrapper will simply dispatch all the execution requests to its private sub thread and report the execution's status only to the thread which made the request.
GdaThreadWrapper* gda_thread_wrapper_new (void);
Creates a new GdaThreadWrapper object
Returns : |
a new GdaThreadWrapper object, or NULL if threads are not supported/enabled
|
Since 4.2
gpointer (*GdaThreadWrapperFunc) (gpointer arg, GError **error);
Specifies the type of function to be passed to gda_thread_wrapper_execute()
.
|
pointer to the data (which is the arg argument passed to gda_thread_wrapper_execute_void() )
|
|
a place to store errors |
Returns : |
a pointer to some data which will be returned by gda_thread_wrapper_fetch_result()
|
guint gda_thread_wrapper_execute (GdaThreadWrapper *wrapper, GdaThreadWrapperFunc func, gpointer arg, GDestroyNotify arg_destroy_func, GError **error);
Make wrapper
execute the func
function with the arg
argument (along with a GError which is not error
)
in the sub thread managed by wrapper
. To execute a function which does not return anything,
use gda_thread_wrapper_execute_void()
.
This method returns immediately, and the caller then needs to use gda_thread_wrapper_fetch_result()
to
check if the execution has finished and get the result.
Once func
's execution is finished, if it is not NULL
, the arg_destroy_func
destruction function is called
on arg
. This occurs in the thread calling gda_thread_wrapper_fetch_result()
.
|
a GdaThreadWrapper object |
|
the function to execute |
|
argument to pass to func
|
|
function to be called when the execution has finished, to destroy arg
|
|
a place to store errors, for errors occurring in this method, not errors occurring while func
is executed, or NULL
|
Returns : |
the job ID, or 0 if an error occurred |
Since 4.2
void (*GdaThreadWrapperVoidFunc) (gpointer arg, GError **error);
Specifies the type of function to be passed to gda_thread_wrapper_execute_void()
.
|
a pointer to the data (which is the arg argument passed to gda_thread_wrapper_execute_void() )
|
|
a place to store errors |
guint gda_thread_wrapper_execute_void (GdaThreadWrapper *wrapper, GdaThreadWrapperVoidFunc func, gpointer arg, GDestroyNotify arg_destroy_func, GError **error);
Make wrapper
execute the func
function with the arg
argument (along with a GError which is not error
)
in the sub thread managed by wrapper
. To execute a function which returns some pointer,
use gda_thread_wrapper_execute()
.
This method returns immediately. Calling gda_thread_wrapper_fetch_result()
is not necessary as func
does not return any result. However, it may be necessary to call gda_thread_wrapper_iterate()
to give wrapper
a
chance to execute the arg_destroy_func
function if not NULL
(note that gda_thread_wrapper_iterate()
is
called by gda_thread_wrapper_fetch_result()
itself).
Once func
's execution is finished, if it is not NULL
, the arg_destroy_func
destruction function is called
on arg
. This occurs in the thread calling gda_thread_wrapper_fetch_result()
.
|
a GdaThreadWrapper object |
|
the function to execute |
|
argument to pass to func
|
|
function to be called when the execution has finished, to destroy arg
|
|
a place to store errors, for errors occurring in this method, not errors occurring while func
is executed, or NULL
|
Returns : |
the job ID, or 0 if an error occurred |
Since 4.2
void gda_thread_wrapper_iterate (GdaThreadWrapper *wrapper, gboolean may_block);
This method gives wrapper
a chance to check if some functions to be executed have finished
in the calling thread. It handles one function's execution result, and
if may_block
is TRUE
, then it will block untill there is one (functions returning void are
ignored).
|
a GdaThreadWrapper object |
|
whether the call may block |
Since 4.2
gpointer gda_thread_wrapper_fetch_result (GdaThreadWrapper *wrapper, gboolean may_lock, guint exp_id, GError **error);
Use this method to check if the execution of a function is finished. The function's execution must have
been requested using gda_thread_wrapper_execute()
.
|
a GdaThreadWrapper object |
|
TRUE if this funct must lock the caller untill a result is available |
|
ID of the job for which a result is expected |
|
a place to store errors, for errors which may have occurred during the execution, or NULL
|
Returns : |
the pointer returned by the execution, or NULL if no result is available
|
Since 4.2
gint gda_thread_wrapper_get_waiting_size (GdaThreadWrapper *wrapper);
Use this method to query the number of functions which have been queued to be executed but which have not yet been executed.
|
a GdaThreadWrapper object |
Returns : |
the number of jobs not yet executed |
Since 4.2
void (*GdaThreadWrapperCallback) (GdaThreadWrapper *wrapper, gpointer instance, const gchar *signame, gint n_param_values, const GValue *param_values, gpointer gda_reserved, gpointer data);
Specifies the type of function to be passed to gda_thread_wrapper_connect_raw()
.
|
the GdaThreadWrapper |
|
a pointer to the instance which emitted the signal |
|
the name of the signal being emitted |
|
number of GValue in param_values
|
|
array of n_param_values GValue
|
|
reserved |
|
a pointer to the data (which is the data argument passed to gda_thread_wrapper_connect_raw() )
|
gulong gda_thread_wrapper_connect_raw (GdaThreadWrapper *wrapper, gpointer instance, const gchar *sig_name, GdaThreadWrapperCallback callback, gpointer data);
Connects a callbeck function to a signal for a particular object. The difference with g_signal_connect()
and
similar functions are:
the callback
argument is not a GCallback function, so the callback signature is not
dependant on the signal itself
the signal handler must not have to return any value
the callback
function will be called asynchronously, the caller may need to use
gda_thread_wrapper_iterate()
to get the notification
the callback
function will be called only if the signal has been emitted by instance
while being used in wrapper
's private sub thread (ie. used when wrapper
is executing some functions
specified by
gda_thread_wrapper_execute()
or gda_thread_wrapper_execute_void()
have been used)
To disconnect a signal handler, don't use any of the g_signal_handler_*() functions but the
gda_thread_wrapper_disconnect()
method.
|
a GdaThreadWrapper object |
|
the instance to connect to |
|
a string of the form "signal-name::detail" |
|
a GdaThreadWrapperCallback function |
|
data to pass to callback 's calls
|
Returns : |
the handler ID |
Since 4.2
void gda_thread_wrapper_disconnect (GdaThreadWrapper *wrapper, gulong id);
Disconnects the emission of a signal, does the opposite of gda_thread_wrapper_connect_raw()
|
a GdaThreadWrapper object |
|
a handler ID, as returned by gda_thread_wrapper_connect_raw()
|
Since 4.2