gio/gtask.h

   1 /* GIO - GLib Input, Output and Streaming Library
   2  *
   3  * Copyright 2011 Red Hat, Inc.
   4  *
   5  * SPDX-License-Identifier: LGPL-2.1-or-later
   6  *
   7  * This library is free software; you can redistribute it and/or
   8  * modify it under the terms of the GNU Lesser General Public
   9  * License as published by the Free Software Foundation; either
  10  * version 2.1 of the License, or (at your option) any later version.
  11  *
  12  * This library is distributed in the hope that it will be useful,
  13  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  15  * Lesser General Public License for more details.
  16  *
  17  * You should have received a copy of the GNU Lesser General
  18  * Public License along with this library; if not, see <http://www.gnu.org/licenses/>.
  19  */
  20
  21 #ifndef __G_TASK_H__
  22 #define __G_TASK_H__
  23
  24 #if !defined (__GIO_GIO_H_INSIDE__) && !defined (GIO_COMPILATION)
  25 #error "Only <gio/gio.h> can be included directly."
  26 #endif
  27
  28 #include <gio/giotypes.h>
  29
  30 G_BEGIN_DECLS
  31
  32 #define G_TYPE_TASK         (g_task_get_type ())
  33 #define G_TASK(o)           (G_TYPE_CHECK_INSTANCE_CAST ((o), G_TYPE_TASK, GTask))
  34 #define G_TASK_CLASS(k)     (G_TYPE_CHECK_CLASS_CAST((k), G_TYPE_TASK, GTaskClass))
  35 #define G_IS_TASK(o)        (G_TYPE_CHECK_INSTANCE_TYPE ((o), G_TYPE_TASK))
  36 #define G_IS_TASK_CLASS(k)  (G_TYPE_CHECK_CLASS_TYPE ((k), G_TYPE_TASK))
  37 #define G_TASK_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), G_TYPE_TASK, GTaskClass))
  38
  39 typedef struct _GTaskClass   GTaskClass;
  40
  41 GIO_AVAILABLE_IN_2_36
  42 GType         g_task_get_type              (void) G_GNUC_CONST;
  43
  44 GIO_AVAILABLE_IN_2_36
  45 GTask        *g_task_new                   (gpointer             source_object,
  46                                             GCancellable        *cancellable,
  47                                             GAsyncReadyCallback  callback,
  48                                             gpointer             callback_data);
  49
  50 GIO_AVAILABLE_IN_2_36
  51 void          g_task_report_error          (gpointer             source_object,
  52                                             GAsyncReadyCallback  callback,
  53                                             gpointer             callback_data,
  54                                             gpointer             source_tag,
  55                                             GError              *error);
  56 GIO_AVAILABLE_IN_2_36
  57 void          g_task_report_new_error      (gpointer             source_object,
  58                                             GAsyncReadyCallback  callback,
  59                                             gpointer             callback_data,
  60                                             gpointer             source_tag,
  61                                             GQuark               domain,
  62                                             gint                 code,
  63                                             const char          *format,
  64                                             ...) G_GNUC_PRINTF(7, 8);
  65
  66 GIO_AVAILABLE_IN_2_36
  67 void          g_task_set_task_data         (GTask               *task,
  68                                             gpointer             task_data,
  69                                             GDestroyNotify       task_data_destroy);
  70 GIO_AVAILABLE_IN_2_36
  71 void          g_task_set_priority          (GTask               *task,
  72                                             gint                 priority);
  73 GIO_AVAILABLE_IN_2_36
  74 void          g_task_set_check_cancellable (GTask               *task,
  75                                             gboolean             check_cancellable);
  76 GIO_AVAILABLE_IN_2_36
  77 void          g_task_set_source_tag        (GTask               *task,
  78                                             gpointer             source_tag);
  79 GIO_AVAILABLE_IN_2_60
  80 void          g_task_set_name              (GTask               *task,
  81                                             const gchar         *name);
  82 GIO_AVAILABLE_IN_2_76
  83 void          g_task_set_static_name       (GTask               *task,
  84                                             const gchar         *name);
  85
  86 /* Macro wrapper to set the task name when setting the source tag. */
  87 #if GLIB_VERSION_MIN_REQUIRED >= GLIB_VERSION_2_76
  88 #define g_task_set_source_tag(task, tag) G_STMT_START { \
  89   GTask *_task = (task); \
  90   (g_task_set_source_tag) (_task, tag); \
  91   if (g_task_get_name (_task) == NULL) \
  92     g_task_set_static_name (_task, G_STRINGIFY (tag)); \
  93 } G_STMT_END
  94 #endif
  95
  96 #if GLIB_VERSION_MIN_REQUIRED >= GLIB_VERSION_2_76
  97 #if defined (__GNUC__) && (__GNUC__ >= 2)
  98 #define g_task_set_name(task, name) G_STMT_START { \
  99   GTask *_task = (task); \
 100   if (__builtin_constant_p (name)) \
 101     g_task_set_static_name (_task, name); \
 102   else \
 103     g_task_set_name (_task, name); \
 104 } G_STMT_END
 105 #endif
 106 #endif
 107
 108 GIO_AVAILABLE_IN_2_36
 109 gpointer      g_task_get_source_object     (GTask               *task);
 110 GIO_AVAILABLE_IN_2_36
 111 gpointer      g_task_get_task_data         (GTask               *task);
 112 GIO_AVAILABLE_IN_2_36
 113 gint          g_task_get_priority          (GTask               *task);
 114 GIO_AVAILABLE_IN_2_36
 115 GMainContext *g_task_get_context           (GTask               *task);
 116 GIO_AVAILABLE_IN_2_36
 117 GCancellable *g_task_get_cancellable       (GTask               *task);
 118 GIO_AVAILABLE_IN_2_36
 119 gboolean      g_task_get_check_cancellable (GTask               *task);
 120 GIO_AVAILABLE_IN_2_36
 121 gpointer      g_task_get_source_tag        (GTask               *task);
 122 GIO_AVAILABLE_IN_2_60
 123 const gchar  *g_task_get_name              (GTask               *task);
 124
 125 GIO_AVAILABLE_IN_2_36
 126 gboolean      g_task_is_valid              (gpointer             result,
 127                                             gpointer             source_object);
 128
 129
 130 typedef void (*GTaskThreadFunc)           (GTask           *task,
 131                                            gpointer         source_object,
 132                                            gpointer         task_data,
 133                                            GCancellable    *cancellable);
 134 GIO_AVAILABLE_IN_2_36
 135 void          g_task_run_in_thread        (GTask           *task,
 136                                            GTaskThreadFunc  task_func);
 137 GIO_AVAILABLE_IN_2_36
 138 void          g_task_run_in_thread_sync   (GTask           *task,
 139                                            GTaskThreadFunc  task_func);
 140 GIO_AVAILABLE_IN_2_36
 141 gboolean      g_task_set_return_on_cancel (GTask           *task,
 142                                            gboolean         return_on_cancel);
 143 GIO_AVAILABLE_IN_2_36
 144 gboolean      g_task_get_return_on_cancel (GTask           *task);
 145
 146 GIO_AVAILABLE_IN_2_36
 147 void          g_task_attach_source        (GTask           *task,
 148                                            GSource         *source,
 149                                            GSourceFunc      callback);
 150
 151
 152 GIO_AVAILABLE_IN_2_36
 153 void          g_task_return_pointer            (GTask           *task,
 154                                                 gpointer         result,
 155                                                 GDestroyNotify   result_destroy);
 156 GIO_AVAILABLE_IN_2_36
 157 void          g_task_return_boolean            (GTask           *task,
 158                                                 gboolean         result);
 159 GIO_AVAILABLE_IN_2_36
 160 void          g_task_return_int                (GTask           *task,
 161                                                 gssize           result);
 162
 163 GIO_AVAILABLE_IN_2_36
 164 void          g_task_return_error              (GTask           *task,
 165                                                 GError          *error);
 166 GIO_AVAILABLE_IN_2_36
 167 void          g_task_return_new_error          (GTask           *task,
 168                                                 GQuark           domain,
 169                                                 gint             code,
 170                                                 const char      *format,
 171                                                 ...) G_GNUC_PRINTF (4, 5);
 172 GIO_AVAILABLE_IN_2_64
 173 void          g_task_return_value              (GTask           *task,
 174                                                 GValue          *result);
 175
 176 GIO_AVAILABLE_IN_2_36
 177 gboolean      g_task_return_error_if_cancelled (GTask           *task);
 178
 179 GIO_AVAILABLE_IN_2_36
 180 gpointer      g_task_propagate_pointer         (GTask           *task,
 181                                                 GError         **error);
 182 GIO_AVAILABLE_IN_2_36
 183 gboolean      g_task_propagate_boolean         (GTask           *task,
 184                                                 GError         **error);
 185 GIO_AVAILABLE_IN_2_36
 186 gssize        g_task_propagate_int             (GTask           *task,
 187                                                 GError         **error);
 188 GIO_AVAILABLE_IN_2_64
 189 gboolean      g_task_propagate_value           (GTask           *task,
 190                                                 GValue          *value,
 191                                                 GError         **error);
 192 GIO_AVAILABLE_IN_2_36
 193 gboolean      g_task_had_error                 (GTask           *task);
 194 GIO_AVAILABLE_IN_2_44
 195 gboolean      g_task_get_completed             (GTask           *task);
 196
 197 /*< private >*/
 198 #ifndef __GTK_DOC_IGNORE__
 199 #ifndef __GI_SCANNER__
 200 /* Debugging API, not part of the public API */
 201 void g_task_print_alive_tasks (void);
 202 #endif /* !__GI_SCANNER__ */
 203 #endif  /* !__GTK_DOC_IGNORE__ */
 204
 205 G_END_DECLS
 206
 207 #endif /* __G_TASK_H__ */