Gda.ThreadWrapper¶

Subclasses:: None

Methods¶

Inherited:: GObject.Object (37)
Structs:: GObject.ObjectClass (5)

class	`error_quark` ()
class	`new` ()
	`cancel` (id)
	`connect_raw` (instance, sig_name, private_thread, private_job, callback, *data)
	`disconnect` (id)
	`execute` (func, arg)
	`execute_void` (func, arg)
	`fetch_result` (may_lock, exp_id)
	`get_io_channel` ()
	`get_waiting_size` ()
	`iterate` (may_block)
	`steal_signal` (id)
	`unset_io_channel` ()

Virtual Methods¶

Inherited:: GObject.Object (7)

Properties¶

None

Signals¶

Inherited:: GObject.Object (1)

Fields¶

Inherited:: GObject.Object (1)

Name	Type	Access	Description
object	`GObject.Object`	r

Class Details¶

class Gda.ThreadWrapper(**kwargs)¶

Bases:: GObject.Object
Abstract:: No
Structure:: Gda.ThreadWrapperClass

classmethod error_quark()¶

Return type:: int

classmethod new()¶

Returns:: a new Gda.ThreadWrapper object, or None if threads are not supported/enabled
Return type:: Gda.ThreadWrapper

Creates a new Gda.ThreadWrapper object

New in version 4.2.

cancel(id)¶

Parameters:: id (int) – the ID of a job as returned by Gda.ThreadWrapper.execute() or Gda.ThreadWrapper.execute_void()
Returns:: True if the job has been cancelled, or False in any other case.
Return type:: bool

Cancels a job not yet executed. This may fail for the following reasons:

the job id could not be found, either because it has already been treated or because it does not exist or because it was created in another thread
the job id is currently being treated by the worker thread

New in version 4.2.

connect_raw(instance, sig_name, private_thread, private_job, callback, *data)¶

Parameters:

instance (object or None) – the instance to connect to
sig_name (str) – a string of the form “signal-name::detail”
private_thread (bool) – set to True if callback is to be invoked only if the signal has been emitted while in self's private sub thread (ie. used when self is executing some functions specified by Gda.ThreadWrapper.execute() or Gda.ThreadWrapper.execute_void()), and to False if the callback is to be invoked whenever the signal is emitted, independently of the thread in which the signal is emitted.
private_job (bool) – set to True if callback is to be invoked only if the signal has been emitted when a job created for the calling thread is being executed, and to False if callback has to be called whenever the sig_name signal is emitted by instance. Note that this argument is not taken into account if private_thread is set to False.
callback (Gda.ThreadWrapperCallback) – a Gda.ThreadWrapperCallback function
data (object or None) – data to pass to callback's calls

Returns:

the handler ID

Return type:

int

Connects a callback function to a signal for a particular object. The difference with g_signal_connect() and similar functions are:

the callback argument is not a GObject.Callback function, so the callback signature is not dependent 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.ThreadWrapper.iterate() to get the notification
if private_job and private_thread control in which case the signal is propagated.

Also note that signal handling is done asynchronously: when emitted in the worker thread, it will be “queued” to be processed in the user thread when it has the chance (when Gda.ThreadWrapper.iterate() is called directly or indirectly). The side effect is that the callback function is usually called long after the object emitting the signal has finished emitting it.

To disconnect a signal handler, don’t use any of the g_signal_handler_*() functions but the Gda.ThreadWrapper.disconnect() method.

New in version 4.2.

disconnect(id)¶

Parameters:: id (int) – a handler ID, as returned by Gda.ThreadWrapper.connect_raw()

Disconnects the emission of a signal, does the opposite of Gda.ThreadWrapper.connect_raw().

As soon as this method returns, the callback function set when Gda.ThreadWrapper.connect_raw() was called will not be called anymore (even if the object has emitted the signal in the worker thread and this signal has not been handled in the user thread).

New in version 4.2.

execute(func, arg)¶

Parameters:

func (Gda.ThreadWrapperFunc) – the function to execute, not None
arg (object or None) – argument to pass to func, or None

Raises:

GLib.Error

Returns:

the job ID, or 0 if an error occurred

Return type:

int

Make self execute the func function with the arg argument (along with a GLib.Error which is not error) in the sub thread managed by self. To execute a function which does not return anything, use Gda.ThreadWrapper.execute_void().

This method returns immediately, and the caller then needs to use Gda.ThreadWrapper.fetch_result() to check if the execution has finished and get the result.

Once func's execution is finished, if arg is not None, the arg_destroy_func destruction function is called on arg. This call occurs in the thread calling Gda.ThreadWrapper.fetch_result().

If an error occurred in this function, then the arg_destroy_func function is not called to free arg.

New in version 4.2.

execute_void(func, arg)¶

Parameters:

func (Gda.ThreadWrapperVoidFunc) – the function to execute, not None
arg (object or None) – argument to pass to func

Raises:

GLib.Error

Returns:

the job ID, or 0 if an error occurred

Return type:

int

Make self execute the func function with the arg argument (along with a GLib.Error which is not error) in the sub thread managed by self. To execute a function which returns some pointer, use Gda.ThreadWrapper.execute().

This method returns immediately. Calling Gda.ThreadWrapper.fetch_result() is not necessary as func does not return any result. However, it may be necessary to call Gda.ThreadWrapper.iterate() to give self a chance to execute the arg_destroy_func function if not None (note that Gda.ThreadWrapper.iterate() is called by Gda.ThreadWrapper.fetch_result() itself).

Once func's execution is finished, if arg is not None, the arg_destroy_func destruction function is called on arg. This call occurs in the thread calling Gda.ThreadWrapper.fetch_result().

If an error occurred in this function, then the arg_destroy_func function is not called to free arg.

New in version 4.2.

fetch_result(may_lock, exp_id)¶

Parameters:

may_lock (bool) – True if this funct must lock the caller untill a result is available
exp_id (int) – ID of the job for which a result is expected

Raises:

GLib.Error

Returns:

the pointer returned by the execution, or None if no result is available

Return type:

object or None

Use this method to check if the execution of a function is finished. The function’s execution must have been requested using Gda.ThreadWrapper.execute().

New in version 4.2.

get_io_channel()¶

Returns:: a new GLib.IOChannel, or None if it could not be created
Return type:: GLib.IOChannel

Allow self to notify when an execution job is finished, by making its exec ID readable through a new GLib.IOChannel. This function is useful when the notification needs to be included into a main loop. This also notifies that signals (emitted by objects in self's internal thread) are available.

The returned GLib.IOChannel will have something to read everytime an execution job is finished for an execution job submitted from the calling thread. The user whould read Gda.ThreadNotification structures from the channel and analyse its contents to call Gda.ThreadWrapper.iterate() or Gda.ThreadWrapper.fetch_result().

Note1: the new communication channel will only be operational for jobs submitted after this function returns, and for signals which have been connected after this function returns. A safe practice is to call this function before the self object has been used.

Note2: this function will return the same GLib.IOChannel everytime it’s called from the same thread.

Note3: if the usage of the returned GLib.IOChannel reveals an error, then GLib.IOChannel.shutdown() and GLib.IOChannel.unref() should be called on the GLib.IOChannel to let self know it should not use that object anymore.

New in version 4.2.9.

get_waiting_size()¶

Returns:: the number of jobs not yet executed
Return type:: int

Use this method to query the number of functions which have been queued to be executed but which have not yet been executed.

New in version 4.2.

iterate(may_block)¶

Parameters:: may_block (bool) – whether the call may block

This method gives self a chance to check if some functions to be executed have finished for the calling thread. In this case it handles the execution result and makes it ready to be processed using Gda.ThreadWrapper.fetch_result().

This method also allows self to handle signals which may have been emitted by objects while in the worker thread, and call the callback function specified when Gda.ThreadWrapper.connect_raw() was used.

If may_block is True, then it will block untill there is one finished execution (functions returning void and signals are ignored regarding this argument).

New in version 4.2.

steal_signal(id)¶

Parameters:: id (int) – a signal ID

Requests that the signal which ID is id (which has been obtained using Gda.ThreadWrapper.connect_raw()) be treated by the calling thread instead of by the thread in which Gda.ThreadWrapper.connect_raw() was called.

New in version 4.2.

unset_io_channel()¶: Does the opposite of Gda.ThreadWrapper.get_io_channel()

New in version 4.2.9.