InfAsyncOperation

InfAsyncOperation — Perform long-running operations in a separate thread

Stability Level

Unstable, unless otherwise indicated

Functions

Types and Values

Includes

#include <libinfinity/inf-async-operation.h>

Description

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.

Functions

InfAsyncOperationRunFunc ()

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.

Parameters

run_data

Location where to write the result of the asynchronous operation.

 

run_notify

Function to be used to free run_data , or NULL.

 

user_data

Data passed in inf_async_operation_new().

 

InfAsyncOperationDoneFunc ()

void
(*InfAsyncOperationDoneFunc) (gpointer run_data,
                              gpointer user_data);

This function is called in the main thread once the asynchronous operation has finished.

Parameters

run_data

The result of the asynchronous operation.

 

user_data

Data passed in inf_async_operation_new().

 

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.

Parameters

io

The InfIo object used to pass back the result of the operation.

 

run_func

A function to run asynchronously in a worker thread, computing the result of the operation.

[scope async]

done_func

A function to be called in the thread of io once the result is available.

[scope async]

user_data

Additional user data to pass to both functions.

 

Returns

A new InfAsyncOperation. Free with inf_async_operation_free() to cancel the operation.

[transfer full]


inf_async_operation_start ()

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.

Parameters

op

A InfAsyncOperation.

[transfer full]

error

Location to store error information, if any.

 

Returns

TRUE on success or FALSE if the operation could not be started.


inf_async_operation_free ()

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.

Parameters

Types and Values

InfAsyncOperation

typedef struct _InfAsyncOperation InfAsyncOperation;

InfAsyncOperation is an opaque data type and should only be accessed via the public API functions.