1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
|
// -*- Mode: C++; indent-tabs-mode: nil; c-basic-offset: 2 -*-
/* Copyright (C) 2007 The giomm Development Team
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Library General Public
* License as published by the Free Software Foundation; either
* version 2 of the License, or (at your option) any later version.
*
* This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Library General Public License for more details.
*
* You should have received a copy of the GNU Library General Public
* License along with this library; if not, write to the Free
* Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
*/
//#include <gio/gasyncresult.h> //We are not allowed to include individual headers.
//TODO: Avoid this:
#include <gio/gio.h>
#include <glibmm/interface.h>
#include <glibmm/object.h>
_DEFS(giomm,gio)
_PINCLUDE(glibmm/private/interface_p.h)
namespace Gio
{
class AsyncResult;
/** A function that will be called when an asynchronous operation within GIO has been completed.
* @param result The asynchronous function's results.
*
* For instance,
* @code
* void on_async_ready(Glib::RefPtr<AsyncResult>& result);
* @endcode
*
* @newin2p16
*/
typedef sigc::slot<void, Glib::RefPtr<AsyncResult>& > SlotAsyncReady;
/** Provides a base class for implementing asynchronous function results.
* Asynchronous operations are broken up into two separate operations which are chained together by a SlotAsyncReady.
* To begin an asynchronous operation, provide a SlotAsyncReady to the asynchronous function. This callback will be triggered
* when the operation has completed, and will be passed an AsyncResult instance filled with the details of the operation's success or
* failure, the object the asynchronous function was started for and any error codes returned. The asynchronous callback function is then
* expected to call the corresponding "_finish()" function with the object the function was called for, and the AsyncResult instance,
* and optionally, an error to grab any error conditions that may have occurred.
*
* The purpose of the "_finish()" function is to take the generic result of type AsyncResult and return the specific result that the operation
* in question yields (e.g. a FileEnumerator for an "enumerate children" operation). If the result or error status of the operation is not needed,
* there is no need to call the "_finish()" function and GIO will take care of cleaning up the result and error information after the
* SlotAsyncReady returns. You may also store the AsyncResult and call "_finish()" later.
*
* Example of a typical asynchronous operation flow:
* @code
* void _theoretical_frobnitz_async(const Glib::RefPtr<Theoretical>& t,
* const SlotAsyncReady& slot);
*
* gboolean _theoretical_frobnitz_finish(const Glib::RefPtr<Theoretical>& t,
* const Glib::RefPtr<AsyncResult>& result);
*
* static void
* on_frobnitz_result(Glib::RefPtr<AsyncResult>& result)
* {
*
* Glib::RefPtr<Glib::Object> source_object = result->get_source_object();
* bool success = _theoretical_frobnitz_finish(source_object, res);
*
* if (success)
* std::cout << "Hurray" << std::endl;
* else
* std::cout << "Uh oh!" << std::endl;
*
* ...
* }
*
* int main (int argc, void *argv[])
* {
* ...
*
* _theoretical_frobnitz_async (theoretical_data,
* sigc::ptr_fun(&on_frobnitz_result) );
*
* ...
* }
* @endcode
*
* The async function could also take an optional Glib::Cancellable object, allowing the calling function to cancel the asynchronous operation.
*
* The callback for an asynchronous operation is called only once, and is always called, even in the case of a cancelled operation.
* On cancellation the result is a ERROR_CANCELLED error.
*
* Some ascynchronous operations are implemented using synchronous calls. These are run in a separate GThread, but otherwise they are sent
* to the Main Event Loop and processed in an idle function. So, if you truly need asynchronous operations, make sure to initialize GThread.
*
* @newin2p16
*/
class AsyncResult : public Glib::Interface
{
_CLASS_INTERFACE(AsyncResult, GAsyncResult, G_ASYNC_RESULT, GAsyncResultIface)
public:
_IGNORE(g_async_result_get_user_data)
//Note that this returns a reference, unlike most GTK+ get_*() functions,
//so we don't need to use refreturn.
_WRAP_METHOD(Glib::RefPtr<Glib::Object> get_source_object(),
g_async_result_get_source_object)
_WRAP_METHOD(Glib::RefPtr<const Glib::Object> get_source_object() const,
g_async_result_get_source_object, constversion)
_WRAP_VFUNC(Glib::RefPtr<Glib::Object> get_source_object(),
"get_source_object")
};
} // namespace Gio
|
