## AgsTask

AgsTask — thread-safe task

## Stability Level

Stable, unless otherwise indicated

## Functions

#define | AGS_TASK_GET_OBJ_MUTEX()
gboolean | ags_task_test_flags ()
void | ags_task_set_flags ()
void | ags_task_unset_flags ()
void | ags_task_launch ()
void | ags_task_failure ()
AgsTask * | ags_task_new ()

## Properties

AgsTaskLauncher * | task-launcher | Read / Write

## Signals

void | failure | Run Last
void | launch | Run Last

## Types and Values

#define | AGS_TYPE_TASK_FLAGS
enum | AgsTaskFlags

## Object Hierarchy

        GObject
        ╰── AgsTask

## Includes

    #include <ags/thread/ags_task.h>

## Description

AgsTask object acts an interceptor in a thread safe context. It's AgsTask::`launch()` function is normally called by AgsTaskLauncher.

The AgsTaskLauncher within thread tree provides thread-safety within entire tree context. You obtain the task launcher of the thread tree by calling AgsConcurrencyProvider::`get_task_launcher()`

There are some task launcher with threads, too. In order to inject from one thread to another.

## Functions

### AGS_TASK_GET_OBJ_MUTEX()

    #define AGS_TASK_GET_OBJ_MUTEX(obj) (&(((AgsTask *) obj)->obj_mutex))

### ags_task_test_flags ()

    gboolean
    ags_task_test_flags (AgsTask *task,
                         AgsTaskFlags flags);

Test `flags` to be set on `task` .

#### Parameters

task | the AgsTask |
flags | the flags |

#### Returns

`TRUE` if flags are set, else `FALSE`

Since: 3.0.0

### ags_task_set_flags ()

    void
    ags_task_set_flags (AgsTask *task,
                        AgsTaskFlags flags);

Enable a feature of AgsTask.

#### Parameters

task | the AgsTask |
flags | see enum AgsTaskFlags |

Since: 3.0.0

### ags_task_unset_flags ()

    void
    ags_task_unset_flags (AgsTask *task,
                          AgsTaskFlags flags);

Disable a feature of AgsTask.

#### Parameters

task | the AgsTask |
flags | see enum AgsTaskFlags |

Since: 3.0.0

### ags_task_launch ()

    void
    ags_task_launch (AgsTask *task);

Intercept task.

#### Parameters

task | an AgsTask |

Since: 3.0.0

### ags_task_failure ()

    void
    ags_task_failure (AgsTask *task,
                      GError *error);

Signals failure of task.

#### Parameters

task | an AgsTask |
error | is `NULL` on success |

Since: 3.0.0

### ags_task_new ()

    AgsTask *
    ags_task_new ();

Create a new AgsTask.

#### Returns

the new AgsTask

Since: 3.0.0

## Types and Values

### AGS_TYPE_TASK_FLAGS

    #define AGS_TYPE_TASK_FLAGS                (ags_task_flags_get_type())

### enum AgsTaskFlags

Enum values to control the behavior or indicate internal state of AgsTask by enable/disable as flags.

#### Members

AGS_TASK_LOCKED | the task is locked |
AGS_TASK_CYCLIC | call task repeatedly |

## Property Details

### The `“task-launcher”` property

      “task-launcher”            AgsTaskLauncher *

The assigned AgsTaskLauncher

Owner: AgsTask

Flags: Read / Write

Since: 3.0.0

## Signal Details

### The `“failure”` signal

    void
    user_function (AgsTask *task,
                   gpointer error,
                   gpointer user_data)

The ::failure signal is emited if ::launch fails

#### Parameters

task | the AgsTask failed to do its work. |
error | the GError |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

Since: 3.0.0

### The `“launch”` signal

    void
    user_function (AgsTask *task,
                   gpointer user_data)

The ::launch signal is emited in a thread safe context

#### Parameters

task | the AgsTask to launch |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

Since: 3.0.0