![]() |
![]() |
![]() |
libinfinity-0.6 Reference Manual | ![]() |
---|---|---|---|---|
Top | Description |
#include <libinfinity/inf-async-operation.h> InfAsyncOperation; void (*InfAsyncOperationRunFunc) (gpointer *run_data
,GDestroyNotify *run_notify
,gpointer user_data
); void (*InfAsyncOperationDoneFunc) (gpointer run_data
,gpointer user_data
); InfAsyncOperation * inf_async_operation_new (InfIo *io
,InfAsyncOperationRunFunc run_func
,InfAsyncOperationDoneFunc done_func
,gpointer user_data
); gboolean inf_async_operation_start (InfAsyncOperation *op
,GError **error
); void inf_async_operation_free (InfAsyncOperation *op
);
InfAsyncOperation is a simple mechanism to run some code in a separate worker thread and then, once the result is computed, notify the main thread about the result.
typedef struct _InfAsyncOperation InfAsyncOperation;
InfAsyncOperation is an opaque data type and should only be accessed via the public API functions.
void (*InfAsyncOperationRunFunc) (gpointer *run_data
,GDestroyNotify *run_notify
,gpointer user_data
);
This function performs the asynchronous task and is executed in a separate
thread. The pointer written into run_data
is passed back to the main
thread after the function has finished executing.
|
Location where to write the result of the asynchronous operation. |
|
Function to be used to free run_data , or NULL . |
|
Data passed in inf_async_operation_new() . |
void (*InfAsyncOperationDoneFunc) (gpointer run_data
,gpointer user_data
);
This function is called in the main thread once the asynchronous operation has finished.
|
The result of the asynchronous operation. |
|
Data passed in inf_async_operation_new() . |
InfAsyncOperation * inf_async_operation_new (InfIo *io
,InfAsyncOperationRunFunc run_func
,InfAsyncOperationDoneFunc done_func
,gpointer user_data
);
This function creates a new InfAsyncOperation. The function given by
run_func
will be run asynchronously in a worker thread. Once the function
finishes, its result is passed back to the main thread defined by io
, and
done_func
is called with the computed result in the main thread.
To actually start the asynchronous operation, call
inf_async_operation_start()
. This allows to save the returned value into
a structure before starting the operation, avoiding a potential race
condition if the asynchronous function finishes quickly.
The asynchronous operation can be canceled by calling
inf_async_operation_free()
on the returned InfAsyncOperation object.
If the operation is not cancelled and after done_func
has been called,
the operation is freed automatically and must not be freed by the caller.
The caller must also keep a reference to io
while the operation is
running. Before dropping your reference to io
, make sure to free the
asynchronous operation. When the last reference to io
is dropped, the
operation is freed automatically, since it cannot pass back its result to
the main thread anymore.
|
The InfIo object used to pass back the result of the operation. |
|
A function to run asynchronously in a worker thread, computing the result of the operation. |
|
A function to be called in the thread of io once the result
is available. |
|
Additional user data to pass to both functions. |
Returns : |
A new InfAsyncOperation. Free with inf_async_operation_free() to
cancel the operation. |
gboolean inf_async_operation_start (InfAsyncOperation *op
,GError **error
);
Starts the operation given in op
. The operation must have been created
before with inf_async_operation_new()
. If the operation cannot be started,
error
is set and FALSE
is returned. In that case, the operation must not
be used anymore since it will be automatically freed.
|
A InfAsyncOperation. |
|
Location to store error information, if any. |
Returns : |
TRUE on success or FALSE if the operation could not be started. |
void inf_async_operation_free (InfAsyncOperation *op
);
Frees the given asynchronous operation and cancels it if it is currently running. This should only be called to cancel a running operation, or to free an operation that has not been started. In all other cases, the operation is freed automatically.
|
A InfAsyncOperation. |