Package ch.bailu.gtk.gio

Klasse SimpleAsyncResult

java.lang.Object
ch.bailu.gtk.type.Type
ch.bailu.gtk.type.Pointer
ch.bailu.gtk.gobject.Object
ch.bailu.gtk.type.PropertyHolder
ch.bailu.gtk.gio.SimpleAsyncResult
Alle implementierten Schnittstellen:
PointerInterface
public class SimpleAsyncResult extends PropertyHolder
As of GLib 2.46, `GSimpleAsyncResult` is deprecated in favor of
[class@Gio.Task], which provides a simpler API.

`GSimpleAsyncResult` implements [iface@Gio.AsyncResult].

`GSimpleAsyncResult` handles [type@Gio.AsyncReadyCallback]s, error
reporting, operation cancellation and the final state of an operation,
completely transparent to the application. Results can be returned
as a pointer e.g. for functions that return data that is collected
asynchronously, a boolean value for checking the success or failure
of an operation, or a `gssize` for operations which return the number
of bytes modified by the operation; all of the simple return cases
are covered.

Most of the time, an application will not need to know of the details
of this API; it is handled transparently, and any necessary operations
are handled by [iface@Gio.AsyncResult]’s interface. However, if implementing
a new GIO module, for writing language bindings, or for complex
applications that need better control of how asynchronous operations
are completed, it is important to understand this functionality.

`GSimpleAsyncResult`s are tagged with the calling function to ensure
that asynchronous functions and their finishing functions are used
together correctly.

To create a new `GSimpleAsyncResult`, call [ctor@Gio.SimpleAsyncResult.new].
If the result needs to be created for a `GError`, use
[ctor@Gio.SimpleAsyncResult.new_from_error] or
[ctor@Gio.SimpleAsyncResult.new_take_error]. If a `GError` is not available
(e.g. the asynchronous operation doesn’t take a `GError` argument),
but the result still needs to be created for an error condition, use
[ctor@Gio.SimpleAsyncResult.new_error] (or
[method@Gio.SimpleAsyncResult.set_error_va] if your application or binding
requires passing a variable argument list directly), and the error can then
be propagated through the use of
[method@Gio.SimpleAsyncResult.propagate_error].

An asynchronous operation can be made to ignore a cancellation event by
calling [method@Gio.SimpleAsyncResult.set_handle_cancellation] with a
`GSimpleAsyncResult` for the operation and `FALSE`. This is useful for
operations that are dangerous to cancel, such as close (which would
cause a leak if cancelled before being run).

`GSimpleAsyncResult` can integrate into GLib’s event loop,
[type@GLib.MainLoop], or it can use [type@GLib.Thread]s.
[method@Gio.SimpleAsyncResult.complete] will finish an I/O task directly
from the point where it is called.
[method@Gio.SimpleAsyncResult.complete_in_idle] will finish it from an idle
handler in the thread-default main context (see
[method@GLib.MainContext.push_thread_default]) where the `GSimpleAsyncResult`
was created. [method@Gio.SimpleAsyncResult.run_in_thread] will run the job in
a separate thread and then use
[method@Gio.SimpleAsyncResult.complete_in_idle] to deliver the result.

To set the results of an asynchronous function,
[method@Gio.SimpleAsyncResult.set_op_res_gpointer],
[method@Gio.SimpleAsyncResult.set_op_res_gboolean], and
[method@Gio.SimpleAsyncResult.set_op_res_gssize]
are provided, setting the operation's result to a `gpointer`, `gboolean`, or
`gssize`, respectively.

Likewise, to get the result of an asynchronous function,
[method@Gio.SimpleAsyncResult.get_op_res_gpointer],
[method@Gio.SimpleAsyncResult.get_op_res_gboolean], and
[method@Gio.SimpleAsyncResult.get_op_res_gssize] are
provided, getting the operation’s result as a `gpointer`, `gboolean`, and
`gssize`, respectively.

For the details of the requirements implementations must respect, see
[iface@Gio.AsyncResult]. A typical implementation of an asynchronous
operation using `GSimpleAsyncResult` looks something like this:

```c
static void
baked_cb (Cake *cake,
gpointer user_data)
{
// In this example, this callback is not given a reference to the cake,
// so the GSimpleAsyncResult has to take a reference to it.
GSimpleAsyncResult *result = user_data;

if (cake == NULL)
g_simple_async_result_set_error (result,
BAKER_ERRORS,
BAKER_ERROR_NO_FLOUR,
"Go to the supermarket");
else
g_simple_async_result_set_op_res_gpointer (result,
g_object_ref (cake),
g_object_unref);


// In this example, we assume that baked_cb is called as a callback from
// the mainloop, so it's safe to complete the operation synchronously here.
// If, however, _baker_prepare_cake () might call its callback without
// first returning to the mainloop — inadvisable, but some APIs do so —
// we would need to use g_simple_async_result_complete_in_idle().
g_simple_async_result_complete (result);
g_object_unref (result);
}

void
baker_bake_cake_async (Baker *self,
guint radius,
GAsyncReadyCallback callback,
gpointer user_data)
{
GSimpleAsyncResult *simple;
Cake *cake;

if (radius < 3)
{
g_simple_async_report_error_in_idle (G_OBJECT (self),
callback,
user_data,
BAKER_ERRORS,
BAKER_ERROR_TOO_SMALL,
"%ucm radius cakes are silly",
radius);
return;
}

simple = g_simple_async_result_new (G_OBJECT (self),
callback,
user_data,
baker_bake_cake_async);
cake = _baker_get_cached_cake (self, radius);

if (cake != NULL)
{
g_simple_async_result_set_op_res_gpointer (simple,
g_object_ref (cake),
g_object_unref);
g_simple_async_result_complete_in_idle (simple);
g_object_unref (simple);
// Drop the reference returned by _baker_get_cached_cake();
// the GSimpleAsyncResult has taken its own reference.
g_object_unref (cake);
return;
}

_baker_prepare_cake (self, radius, baked_cb, simple);
}

Cake *
baker_bake_cake_finish (Baker *self,
GAsyncResult *result,
GError **error)
{
GSimpleAsyncResult *simple;
Cake *cake;

g_return_val_if_fail (g_simple_async_result_is_valid (result,
G_OBJECT (self),
baker_bake_cake_async),
NULL);

simple = (GSimpleAsyncResult *) result;

if (g_simple_async_result_propagate_error (simple, error))
return NULL;

cake = CAKE (g_simple_async_result_get_op_res_gpointer (simple));
return g_object_ref (cake);
}
```

https://docs.gtk.org/gio/class.SimpleAsyncResult.html

  • Konstruktordetails

    • SimpleAsyncResult

      public SimpleAsyncResult(PointerContainer pointer)

    • SimpleAsyncResult

      @Deprecated public SimpleAsyncResult(@Nullable Object source_object, SimpleAsyncResult.OnAsyncReadyCallback callback, @Nullable Pointer user_data, @Nullable Pointer source_tag)
      Veraltet.
      Creates a #GSimpleAsyncResult.

      The common convention is to create the #GSimpleAsyncResult in the
      function that starts the asynchronous operation and use that same
      function as the @source_tag.

      If your operation supports cancellation with #GCancellable (which it
      probably should) then you should provide the user's cancellable to
      g_simple_async_result_set_check_cancellable() immediately after
      this function returns.
      Parameter:
      source_object - a #GObject, or %NULL.
      callback - a #GAsyncReadyCallback.
      user_data - user data passed to @callback.
      source_tag - the asynchronous function.

  • Methodendetails

    • getClassHandler

      public static ClassHandler getClassHandler()

    • newErrorSimpleAsyncResult

      @Deprecated public static SimpleAsyncResult newErrorSimpleAsyncResult(@Nullable Object source_object, SimpleAsyncResult.OnAsyncReadyCallback callback, @Nullable Pointer user_data, int domain, int code, @Nonnull Str format, Object... _ellipsis)
      Veraltet.
      Creates a new #GSimpleAsyncResult with a set error.
      Parameter:
      source_object - a #GObject, or %NULL.
      callback - a #GAsyncReadyCallback.
      user_data - user data passed to @callback.
      domain - a #GQuark.
      code - an error code.
      format - a string with format characters.
      _ellipsis - a list of values to insert into @format.
      Gibt zurück:
      a #GSimpleAsyncResult.

    • newErrorSimpleAsyncResult

      @Deprecated public static SimpleAsyncResult newErrorSimpleAsyncResult(@Nullable Object source_object, SimpleAsyncResult.OnAsyncReadyCallback callback, @Nullable Pointer user_data, int domain, int code, String format, Object... _ellipsis)
      Veraltet.
      Creates a new #GSimpleAsyncResult with a set error.
      Parameter:
      source_object - a #GObject, or %NULL.
      callback - a #GAsyncReadyCallback.
      user_data - user data passed to @callback.
      domain - a #GQuark.
      code - an error code.
      format - a string with format characters.
      _ellipsis - a list of values to insert into @format.
      Gibt zurück:
      a #GSimpleAsyncResult.

    • newFromErrorSimpleAsyncResult

      @Deprecated public static SimpleAsyncResult newFromErrorSimpleAsyncResult(@Nullable Object source_object, SimpleAsyncResult.OnAsyncReadyCallback callback, @Nullable Pointer user_data, @Nonnull Error error)
      Veraltet.
      Creates a #GSimpleAsyncResult from an error condition.
      Parameter:
      source_object - a #GObject, or %NULL.
      callback - a #GAsyncReadyCallback.
      user_data - user data passed to @callback.
      error - a #GError
      Gibt zurück:
      a #GSimpleAsyncResult.

    • newTakeErrorSimpleAsyncResult

      @Deprecated public static SimpleAsyncResult newTakeErrorSimpleAsyncResult(@Nullable Object source_object, SimpleAsyncResult.OnAsyncReadyCallback callback, @Nullable Pointer user_data, @Nonnull Error error)
      Veraltet.
      Creates a #GSimpleAsyncResult from an error condition, and takes over the
      caller's ownership of @error, so the caller does not need to free it anymore.
      Parameter:
      source_object - a #GObject, or %NULL
      callback - a #GAsyncReadyCallback.
      user_data - user data passed to @callback.
      error - a #GError
      Gibt zurück:
      a #GSimpleAsyncResult

    • complete

      @Deprecated public void complete()
      Veraltet.
      Completes an asynchronous I/O job immediately. Must be called in
      the thread where the asynchronous result was to be delivered, as it
      invokes the callback directly. If you are in a different thread use
      g_simple_async_result_complete_in_idle().

      Calling this function takes a reference to @simple for as long as
      is needed to complete the call.

    • completeInIdle

      @Deprecated public void completeInIdle()
      Veraltet.
      Completes an asynchronous function in an idle handler in the
      thread-default main context (see [method@GLib.MainContext.push_thread_default])
      of the thread that @simple was initially created in
      (and re-pushes that context around the invocation of the callback).

      Calling this function takes a reference to @simple for as long as
      is needed to complete the call.

    • getOpResGboolean

      @Deprecated public boolean getOpResGboolean()
      Veraltet.
      Gets the operation result boolean from within the asynchronous result.
      Gibt zurück:
      %TRUE if the operation's result was %TRUE, %FALSE if the operation's result was %FALSE.

    • getOpResGpointer

      @Deprecated public Pointer getOpResGpointer()
      Veraltet.
      Gets a pointer result as returned by the asynchronous function.
      Gibt zurück:
      a pointer from the result.

    • getOpResGssize

      @Deprecated public long getOpResGssize()
      Veraltet.
      Gets a gssize from the asynchronous result.
      Gibt zurück:
      a gssize returned from the asynchronous function.

    • getSourceTag

      @Deprecated public Pointer getSourceTag()
      Veraltet.
      Gets the source tag for the #GSimpleAsyncResult.
      Gibt zurück:
      a #gpointer to the source object for the #GSimpleAsyncResult.

    • propagateError

      @Deprecated public boolean propagateError() throws AllocationError
      Veraltet.
      Propagates an error from within the simple asynchronous result to
      a given destination.

      If the #GCancellable given to a prior call to
      g_simple_async_result_set_check_cancellable() is cancelled then this
      function will return %TRUE with @dest set appropriately.
      Gibt zurück:
      %TRUE if the error was propagated to @dest. %FALSE otherwise.
      Löst aus:
      AllocationError

    • runInThread

      @Deprecated public void runInThread(SimpleAsyncResult.OnSimpleAsyncThreadFunc func, int io_priority, @Nullable Cancellable cancellable)
      Veraltet.
      Runs the asynchronous job in a separate thread and then calls
      g_simple_async_result_complete_in_idle() on @simple to return
      the result to the appropriate main loop.

      Calling this function takes a reference to @simple for as long as
      is needed to run the job and report its completion.
      Parameter:
      func - a #GSimpleAsyncThreadFunc.
      io_priority - the io priority of the request.
      cancellable - optional #GCancellable object, %NULL to ignore.

    • setCheckCancellable

      @Deprecated public void setCheckCancellable(@Nullable Cancellable check_cancellable)
      Veraltet.
      Sets a #GCancellable to check before dispatching results.

      This function has one very specific purpose: the provided cancellable
      is checked at the time of g_simple_async_result_propagate_error() If
      it is cancelled, these functions will return an "Operation was
      cancelled" error (%G_IO_ERROR_CANCELLED).

      Implementors of cancellable asynchronous functions should use this in
      order to provide a guarantee to their callers that cancelling an
      async operation will reliably result in an error being returned for
      that operation (even if a positive result for the operation has
      already been sent as an idle to the main context to be dispatched).

      The checking described above is done regardless of any call to the
      unrelated g_simple_async_result_set_handle_cancellation() function.
      Parameter:
      check_cancellable - a #GCancellable to check, or %NULL to unset

    • setError

      @Deprecated public void setError(int domain, int code, @Nonnull Str format, Object... _ellipsis)
      Veraltet.
      Sets an error within the asynchronous result without a #GError.
      Parameter:
      domain - a #GQuark (usually %G_IO_ERROR).
      code - an error code.
      format - a formatted error reporting string.
      _ellipsis - a list of variables to fill in @format.

    • setError

      @Deprecated public void setError(int domain, int code, String format, Object... _ellipsis)
      Veraltet.
      Sets an error within the asynchronous result without a #GError.
      Parameter:
      domain - a #GQuark (usually %G_IO_ERROR).
      code - an error code.
      format - a formatted error reporting string.
      _ellipsis - a list of variables to fill in @format.

    • setFromError

      @Deprecated public void setFromError(@Nonnull Error error)
      Veraltet.
      Sets the result from a #GError.
      Parameter:
      error - #GError.

    • setHandleCancellation

      @Deprecated public void setHandleCancellation(boolean handle_cancellation)
      Veraltet.
      Sets whether to handle cancellation within the asynchronous operation.

      This function has nothing to do with
      g_simple_async_result_set_check_cancellable(). It only refers to the
      #GCancellable passed to g_simple_async_result_run_in_thread().
      Parameter:
      handle_cancellation - a #gboolean.

    • setOpResGboolean

      @Deprecated public void setOpResGboolean(boolean op_res)
      Veraltet.
      Sets the operation result to a boolean within the asynchronous result.
      Parameter:
      op_res - a #gboolean.

    • setOpResGpointer

      @Deprecated public void setOpResGpointer(@Nullable Pointer op_res, SimpleAsyncResult.OnDestroyNotify destroy_op_res)
      Veraltet.
      Sets the operation result within the asynchronous result to a pointer.
      Parameter:
      op_res - a pointer result from an asynchronous function.
      destroy_op_res - a #GDestroyNotify function.

    • setOpResGssize

      @Deprecated public void setOpResGssize(long op_res)
      Veraltet.
      Sets the operation result within the asynchronous result to
      the given @op_res.
      Parameter:
      op_res - a #gssize.

    • takeError

      @Deprecated public void takeError(@Nonnull Error error)
      Veraltet.
      Sets the result from @error, and takes over the caller's ownership
      of @error, so the caller does not need to free it any more.
      Parameter:
      error - a #GError

    • isValid

      @Deprecated public static boolean isValid(@Nonnull AsyncResult result, @Nullable Object source, @Nullable Pointer source_tag)
      Veraltet.
      Ensures that the data passed to the _finish function of an async
      operation is consistent. Three checks are performed.

      First, @result is checked to ensure that it is really a
      #GSimpleAsyncResult. Second, @source is checked to ensure that it
      matches the source object of @result. Third, @source_tag is
      checked to ensure that it is equal to the @source_tag argument given
      to g_simple_async_result_new() (which, by convention, is a pointer
      to the _async function corresponding to the _finish function from
      which this function is called). (Alternatively, if either
      @source_tag or @result's source tag is %NULL, then the source tag
      check is skipped.)
      Parameter:
      result - the #GAsyncResult passed to the _finish function.
      source - the #GObject passed to the _finish function.
      source_tag - the asynchronous function.
      Gibt zurück:
      #TRUE if all checks passed or #FALSE if any failed.

    • asAsyncResult

      public AsyncResult asAsyncResult()
      Implements interface AsyncResult. Call this to get access to interface functions.
      Gibt zurück:
      AsyncResult

    • getTypeID

      public static long getTypeID()

    • getParentTypeID

      public static long getParentTypeID()

    • getTypeSize

      public static TypeSystem.TypeSize getTypeSize()

    • getParentTypeSize

      public static TypeSystem.TypeSize getParentTypeSize()

    • getInstanceSize

      public static int getInstanceSize()