mirror of
https://github.com/Ardour/ardour.git
synced 2025-12-19 21:26:26 +01:00
a73d15e989
git-svn-id: svn://localhost/ardour2/branches/3.0@5306 d708f5d6-7413-0410-9779-e7cbd77b26cf
122 lines
4.9 KiB
Text
122 lines
4.9 KiB
Text
// -*- 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 <glibmm/interface.h>
|
|
#include <glibmm/object.h>
|
|
|
|
_DEFS(giomm,gio)
|
|
_PINCLUDE(glibmm/private/interface_p.h)
|
|
|
|
#ifndef DOXYGEN_SHOULD_SKIP_THIS
|
|
typedef struct _GAsyncResultIface GAsyncResultIface;
|
|
#endif /* DOXYGEN_SHOULD_SKIP_THIS */
|
|
|
|
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.
|
|
*
|
|
* 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
|
|
|