1 /* GIO - GLib Input, Output and Streaming Library 2 * 3 * Copyright (C) 2006-2007 Red Hat, Inc. 4 * 5 * This library is free software; you can redistribute it and/or 6 * modify it under the terms of the GNU Lesser General Public 7 * License as published by the Free Software Foundation; either 8 * version 2 of the License, or (at your option) any later version. 9 * 10 * This library is distributed in the hope that it will be useful, 11 * but WITHOUT ANY WARRANTY; without even the implied warranty of 12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 13 * Lesser General Public License for more details. 14 * 15 * You should have received a copy of the GNU Lesser General 16 * Public License along with this library; if not, write to the 17 * Free Software Foundation, Inc., 59 Temple Place, Suite 330, 18 * Boston, MA 02111-1307, USA. 19 * 20 * Author: Alexander Larsson <alexl (at) redhat.com> 21 */ 22 23 #include "config.h" 24 #include "gasyncresult.h" 25 #include "glibintl.h" 26 27 #include "gioalias.h" 28 29 /** 30 * SECTION:gasyncresult 31 * @short_description: Asynchronous Function Results 32 * @include: gio/gio.h 33 * @see_also: #GSimpleAsyncResult 34 * 35 * Provides a base class for implementing asynchronous function results. 36 * 37 * Asynchronous operations are broken up into two separate operations 38 * which are chained together by a #GAsyncReadyCallback. To begin 39 * an asynchronous operation, provide a #GAsyncReadyCallback to the 40 * asynchronous function. This callback will be triggered when the 41 * operation has completed, and will be passed a #GAsyncResult instance 42 * filled with the details of the operation's success or failure, the 43 * object the asynchronous function was started for and any error codes 44 * returned. The asynchronous callback function is then expected to call 45 * the corresponding "_finish()" function with the object the function 46 * was called for, and the #GAsyncResult instance, and optionally, 47 * an @error to grab any error conditions that may have occurred. 48 * 49 * The purpose of the "_finish()" function is to take the generic 50 * result of type #GAsyncResult and return the specific result 51 * that the operation in question yields (e.g. a #GFileEnumerator for 52 * a "enumerate children" operation). If the result or error status 53 * of the operation is not needed, there is no need to call the 54 * "_finish()" function, GIO will take care of cleaning up the 55 * result and error information after the #GAsyncReadyCallback 56 * returns. It is also allowed to take a reference to the #GAsyncResult and 57 * call "_finish()" later. 58 * 59 * Example of a typical asynchronous operation flow: 60 * |[ 61 * void _theoretical_frobnitz_async (Theoretical *t, 62 * GCancellable *c, 63 * GAsyncReadyCallback *cb, 64 * gpointer u); 65 * 66 * gboolean _theoretical_frobnitz_finish (Theoretical *t, 67 * GAsyncResult *res, 68 * GError **e); 69 * 70 * static void 71 * frobnitz_result_func (GObject *source_object, 72 * GAsyncResult *res, 73 * gpointer user_data) 74 * { 75 * gboolean success = FALSE; 76 * 77 * success = _theoretical_frobnitz_finish (source_object, res, NULL); 78 * 79 * if (success) 80 * g_printf ("Hurray!\n"); 81 * else 82 * g_printf ("Uh oh!\n"); 83 * 84 * /<!-- -->* ... *<!-- -->/ 85 * 86 * } 87 * 88 * int main (int argc, void *argv[]) 89 * { 90 * /<!-- -->* ... *<!-- -->/ 91 * 92 * _theoretical_frobnitz_async (theoretical_data, 93 * NULL, 94 * frobnitz_result_func, 95 * NULL); 96 * 97 * /<!-- -->* ... *<!-- -->/ 98 * } 99 * ]| 100 * 101 * The callback for an asynchronous operation is called only once, and is 102 * always called, even in the case of a cancelled operation. On cancellation 103 * the result is a %G_IO_ERROR_CANCELLED error. 104 * 105 * Some ascynchronous operations are implemented using synchronous calls. These 106 * are run in a separate thread, if #GThread has been initialized, but otherwise they 107 * are sent to the Main Event Loop and processed in an idle function. So, if you 108 * truly need asynchronous operations, make sure to initialize #GThread. 109 **/ 110 111 static void g_async_result_base_init (gpointer g_class); 112 static void g_async_result_class_init (gpointer g_class, 113 gpointer class_data); 114 115 GType 116 g_async_result_get_type (void) 117 { 118 static volatile gsize g_define_type_id__volatile = 0; 119 120 if (g_once_init_enter (&g_define_type_id__volatile)) 121 { 122 const GTypeInfo async_result_info = 123 { 124 sizeof (GAsyncResultIface), /* class_size */ 125 g_async_result_base_init, /* base_init */ 126 NULL, /* base_finalize */ 127 g_async_result_class_init, 128 NULL, /* class_finalize */ 129 NULL, /* class_data */ 130 0, 131 0, /* n_preallocs */ 132 NULL 133 }; 134 GType g_define_type_id = 135 g_type_register_static (G_TYPE_INTERFACE, I_("GAsyncResult"), 136 &async_result_info, 0); 137 138 g_type_interface_add_prerequisite (g_define_type_id, G_TYPE_OBJECT); 139 140 g_once_init_leave (&g_define_type_id__volatile, g_define_type_id); 141 } 142 143 return g_define_type_id__volatile; 144 } 145 146 static void 147 g_async_result_class_init (gpointer g_class, 148 gpointer class_data) 149 { 150 } 151 152 static void 153 g_async_result_base_init (gpointer g_class) 154 { 155 } 156 157 /** 158 * g_async_result_get_user_data: 159 * @res: a #GAsyncResult. 160 * 161 * Gets the user data from a #GAsyncResult. 162 * 163 * Returns: the user data for @res. 164 **/ 165 gpointer 166 g_async_result_get_user_data (GAsyncResult *res) 167 { 168 GAsyncResultIface *iface; 169 170 g_return_val_if_fail (G_IS_ASYNC_RESULT (res), NULL); 171 172 iface = G_ASYNC_RESULT_GET_IFACE (res); 173 174 return (* iface->get_user_data) (res); 175 } 176 177 /** 178 * g_async_result_get_source_object: 179 * @res: a #GAsyncResult. 180 * 181 * Gets the source object from a #GAsyncResult. 182 * 183 * Returns: the source object for the @res. 184 **/ 185 GObject * 186 g_async_result_get_source_object (GAsyncResult *res) 187 { 188 GAsyncResultIface *iface; 189 190 g_return_val_if_fail (G_IS_ASYNC_RESULT (res), NULL); 191 192 iface = G_ASYNC_RESULT_GET_IFACE (res); 193 194 return (* iface->get_source_object) (res); 195 } 196 197 #define __G_ASYNC_RESULT_C__ 198 #include "gioaliasdef.c" 199