/* GIO - GLib Input, Output and Streaming Library
 *
 * Copyright 2011 Red Hat, Inc.
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser 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
 * Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General
 * Public License along with this library; if not, write to the
 * Free Software Foundation, Inc., 59 Temple Place, Suite 330,
 * Boston, MA 02111-1307, USA.
 */

#include "config.h"

#include "gtask.h"

/**
 * SECTION:gtask
 * @short_description: Cancellable synchronous or asynchronous tasks
 * @include: gio/gio.h
 * @see_also: #GAsyncResult
 *
 * FIXME
 */

/**
 * g_task_new:
 * @source_object: (allow-none): a #GObject, or %NULL.
 * @task_data: (allow-none): task-specific data
 * @task_data_destroy: (allow-none): #GDestroyNotify for @task_data
 * @io_priority: the io priority of the request.
 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
 * @callback: (scope async): a #GAsyncReadyCallback.
 * @callback_data: (closure): user data passed to @callback.
 *
 * Creates a #GTask.
 *
 * Returns: a #GTask.
 */
GTask *
g_task_new (gpointer              source_object,
	    gpointer              task_data,
	    GDestroyNotify        task_data_destroy,
	    gint                  io_priority,
	    GCancellable         *cancellable,
	    GAsyncReadyCallback   callback,
	    gpointer              callback_data)
{
}


/**
 * g_task_new_sync:
 * @source_object: (allow-none): a #GObject, or %NULL.
 * @task_data: (allow-none): task-specific data
 * @task_data_destroy: (allow-none): #GDestroyNotify for @task_data
 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
 *
 * Creates a #GTask to be run synchronously.
 *
 * Returns: a #GTask.
 */
GTask *
g_task_new_sync (gpointer              source_object,
		 gpointer              task_data,
		 GDestroyNotify        task_data_destroy,
		 GCancellable         *cancellable)
{
  return g_task_new (source_object, task_data, task_data_destroy,
		     G_PRIORITY_DEFAULT, cancellable, NULL, NULL);
}


/**
 * g_task_get_source_object: (skip)
 * @task: a #GTask
 *
 * Gets the source object from @task. Like
 * g_async_result_get_source_object(), but does not ref the object.
 *
 * Returns: (transfer none): @task's source object, or %NULL
 */
gpointer
g_task_get_source_object (GTask *task)
{
}

/**
 * g_task_get_task_data:
 * @task: a #GTask
 *
 * Gets @task's <literal>task_data</literal>.
 *
 * Returns: @task's <literal>task_data</literal>.
 */
gpointer
g_task_get_task_data (GTask *task)
{
}

/**
 * g_task_get_io_priority:
 * @task: a #GTask
 *
 * Gets @task's I/O priority
 *
 * Returns: @task's I/O priority
 */
gint
g_task_get_io_priority (GTask *task)
{
}

/**
 * g_task_get_cancellable:
 * @task: a #GTask
 *
 * Gets @task's #GCancellable
 *
 * Returns: @task's #GCancellable
 */
GCancellable *
g_task_get_cancellable (GTask *task)
{
}

/**
 * g_task_get_context:
 * @task: a #GTask
 *
 * Gets @task's #GMainContext
 *
 * Returns: @task's #GMainContext
 */
GMainContext *
g_task_get_context (GTask *task)
{
}


/**
 * GTaskThreadFunc:
 * @task: the #GTask
 * @task_data: @task's task data
 * @cancellable: @task's #GCancellable, or %NULL
 * @error: return location for a #GError
 *
 * The prototype for a task function to be run cancellably in a thread.
 *
 * If the @cancellable is triggered, then the #GTaskThreadFunc's
 * caller will return immediately, without waiting for the task
 * function to complete. However, the task function will continue
 * running in its thread in the background. The function should
 * therefore not modify any externally-visible state, and any data it
 * uses must remain valid until @task_data's #GDestroyNotify is
 * called.
 *
 * The #GTaskThreadFunc can check @cancellable itself occasionally,
 * and return early if it discovers that it has been cancelled, but it
 * does not need to do this.
 *
 * If @error is set when the function returns, then that value will be
 * set on the task, overriding any return value set via
 * g_task_set_result_gpointer(), etc.
 */

/**
 * g_task_run_sync_in_thread:
 * @task: a #GTask
 * @task_func: a #GTaskThreadFunc
 *
 * Runs @task_func in another thread and waits for it to return or be
 * cancelled. If @task is cancelled then g_task_run_sync_in_thread()
 * will return immediately, with a %G_IO_ERROR_CANCELLED error set.
 */
void
g_task_run_sync_in_thread (GTask                *task,
			   GTaskThreadFunc       task_func)
{
}

/**
 * g_task_run_async_in_thread:
 * @task: a #GTask
 * @task_func: a #GTaskThreadFunc
 *
 * Runs @task_func in another thread and calls @task's
 * #GAsyncReadyCallback when it returns or is cancelled. If @task is
 * cancelled then its callback will be queued immediately, with a
 * %G_IO_ERROR_CANCELLED error set.
 *
 * FIXME: the immediately-cancel behavior is what you want for the
 * GThreadedResolver case, but probably not for the
 * g_simple_async_result_run_in_thread() case. Probably there should
 * be a "gboolean handle_cancellation" flag or something, saying
 * whether or not GTask should automatically handle cancellation.
 */
void
g_task_run_async_in_thread  (GTask                *task,
			     GTaskThreadFunc       task_func)
{
}


/**
 * g_task_set_result_gpointer:
 * @task: a #GTask
 * @result: a pointer result from an task function
 * @result_destroy: a #GDestroyNotify function.
 *
 * Sets @task's result to @result.
 */
void
g_task_set_result_gpointer (GTask          *task,
			    gpointer        result,
			    GDestroyNotify  result_destroy)
{
}

/**
 * g_task_get_result_gpointer:
 * @task: a #GTask
 * @error: return location for a #GError
 *
 * Gets the result of @task as a pointer. If the task resulted in an
 * error, then @error will be set and %NULL will be returned.
 *
 * The returned value is owned by @task. See also
 * g_task_propagate_result_gpointer().
 *
 * Returns: (transfer none): the task result, or %NULL on error
 */
gpointer
g_task_get_result_gpointer (GTask   *task,
			    GError **error)
{
}

/**
 * g_task_propagate_result_gpointer:
 * @task: a #GTask
 * @error: return location for a #GError
 *
 * Gets the result of @task as a pointer. If the task resulted in an
 * error, then @error will be set and %NULL will be returned.
 *
 * The returned value is owned by the caller. See also
 * g_task_get_result_gpointer().
 *
 * FIXME: is "propagate" the right word here? I had
 * "g_task_take_result_gpointer()" first, but "take" is consistently
 * used to mean the opposite direction in glib (qv
 * g_task_take_result_gerror()), so that's wrong.
 *
 * Returns: (transfer full): the task result, or %NULL on error
 */
gpointer
g_task_propagate_result_gpointer (GTask   *task,
				  GError **error)
{
}

/**
 * g_task_set_result_gssize:
 * @task: a #GTask.
 * @result: a #gssize.
 *
 * Sets @task's result to @result.
 */
void
g_task_set_result_gssize (GTask  *task,
			  gssize  result)
{
}

/**
 * g_task_get_result_gssize:
 * @task: a #GTask.
 *
 * Gets the result of @task as a #gssize. If the task resulted in an
 * error, then @error will be set and -1 will be returned.
 *
 * Returns: the task result, or -1 on error
 */
gssize
g_task_get_result_gssize (GTask *task)
{
}

/**
 * g_task_set_result_gboolean:
 * @task: a #GTask.
 * @result: a #gboolean.
 *
 * Sets @task's result to @result.
 */
void
g_task_set_result_gboolean (GTask    *task,
			    gboolean  result)
{
}

/**
 * g_task_get_result_gboolean:
 * @task: a #GTask.
 *
 * Gets the result of @task as a #gboolean. If the task resulted in an
 * error, then @error will be set and %FALSE will be returned.
 *
 * Returns: the task result, or %FALSE on error
 */
gboolean
g_task_get_result_gboolean (GTask *task)
{
}

/**
 * g_task_set_result_gerror:
 * @task: a #GTask.
 * @gerror: #GError.
 *
 * Sets the result of @task to @gerror. See also
 * g_task_take_result_error().
 */
void
g_task_set_result_gerror (GTask        *task,
			  const GError *gerror)
{
}

/**
 * g_task_take_result_gerror:
 * @task: a #GTask
 * @gerror: a #GError
 *
 * Sets the result of @task to @gerror, and takes over the caller's
 * ownership of @gerror. See also g_task_set_result_gerror().
 */
void
g_task_take_result_gerror (GTask  *task,
			   GError *gerror)
{
}

/**
 * g_task_propagate_error:
 * @task: a #GTask
 * @dest: return location for a #GError
 *
 * Propagates an error from within @task to @dest.
 *
 * Returns: %TRUE if the error was propagated to @dest. %FALSE otherwise.
 **/
gboolean
g_task_propagate_error (GTask   *task,
			GError **dest)
{
}


/**
 * g_task_complete:
 * @task: a #GTask.
 *
 * Completes an asynchronous I/O job. If called from the #GMainContext
 * in which @task was started, at some point after the task was
 * originally created, then this will invoke @task's
 * #GAsyncReadyCallback directly. Otherwise, it will queue the callback
 * to run in the next iteration of @task's #GMainContext.
 *
 * Calling this function takes a reference to @task for as long as
 * is needed to complete the call.
 */
void
g_task_complete (GTask *task)
{
}
