## InfAsyncOperation

InfAsyncOperation — Perform long-running operations in a separate thread

## Stability Level

Unstable, unless otherwise indicated

## Functions

void | (*InfAsyncOperationRunFunc) ()
void | (*InfAsyncOperationDoneFunc) ()
InfAsyncOperation * | inf_async_operation_new ()
gboolean | inf_async_operation_start ()
void | inf_async_operation_free ()

## Types and Values

| InfAsyncOperation

## 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

op | A InfAsyncOperation. |

## Types and Values

### InfAsyncOperation

    typedef struct _InfAsyncOperation InfAsyncOperation;

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