[Xfce4-commits] r29927 - in libexo/trunk: . docs/reference docs/reference/tmpl exo
Jannis Pohlmann
jannis at xfce.org
Tue May 5 23:39:22 CEST 2009
Author: jannis
Date: 2009-05-05 21:39:22 +0000 (Tue, 05 May 2009)
New Revision: 29927
Added:
libexo/trunk/docs/reference/tmpl/exo-job.sgml
libexo/trunk/docs/reference/tmpl/exo-simple-job.sgml
Modified:
libexo/trunk/ChangeLog
libexo/trunk/configure.in.in
libexo/trunk/docs/reference/exo-docs.sgml
libexo/trunk/docs/reference/exo-sections.txt
libexo/trunk/exo/exo-job.c
libexo/trunk/exo/exo-simple-job.c
Log:
* configure.in.in: Add hint that we'll need to update library version
information before the next release, due to the added APIs.
* docs/reference/exo-docs.sgml,
docs/reference/tmpl/exo-simple-job.sgml,
docs/reference/tmpl/exo-job.sgml, docs/reference/exo-sections.txt:
Add new section for ExoJob and ExoSimpleJob.
* exo/exo-job.c, exo/exo-simple-job.c: Improve the API documentation
and associate class methods with the signals of ExoJob.
They come from Thunar and can be used to wrap threaded/asynchronous
operations with objects that support signals and subclassing.
Modified: libexo/trunk/ChangeLog
===================================================================
--- libexo/trunk/ChangeLog 2009-05-05 20:07:22 UTC (rev 29926)
+++ libexo/trunk/ChangeLog 2009-05-05 21:39:22 UTC (rev 29927)
@@ -1,9 +1,20 @@
2009-05-05 Jannis Pohlmann <jannis at xfce.org>
+ * configure.in.in: Add hint that we'll need to update library version
+ information before the next release, due to the added APIs.
+ * docs/reference/exo-docs.sgml,
+ docs/reference/tmpl/exo-simple-job.sgml,
+ docs/reference/tmpl/exo-job.sgml, docs/reference/exo-sections.txt:
+ Add new section for ExoJob and ExoSimpleJob.
+ * exo/exo-job.c, exo/exo-simple-job.c: Improve the API documentation
+ and associate class methods with the signals of ExoJob.
+
+2009-05-05 Jannis Pohlmann <jannis at xfce.org>
+
* docs/reference/exo.types, exo/Makefile.am, exo/exo-job.{c,h},
exo/exo-simple-job.{c,h}, exo/exo.h: Add ExoJob and ExoSimpleJob.
- They come from Thunar and can be used to wrap threaded/asynchronous
- operations with objects that support signals and subclassing.
+ They come from Thunar and can be used to wrap threaded/asynchronous
+ operations with objects that support signals and subclassing.
2009-04-13 Jannis Pohlmann <jannis at xfce.org>
Modified: libexo/trunk/configure.in.in
===================================================================
--- libexo/trunk/configure.in.in 2009-05-05 20:07:22 UTC (rev 29926)
+++ libexo/trunk/configure.in.in 2009-05-05 21:39:22 UTC (rev 29927)
@@ -9,7 +9,7 @@
dnl ***************************
dnl *** Version information ***
dnl ***************************
-m4_define([libexo_verinfo], [5:0:5])
+m4_define([libexo_verinfo], [5:0:5]) dnl Needs to be set to [6:0:6] before the next release!
m4_define([libexo_version_major], [0])
m4_define([libexo_version_minor], [3])
m4_define([libexo_version_micro], [101])
Modified: libexo/trunk/docs/reference/exo-docs.sgml
===================================================================
--- libexo/trunk/docs/reference/exo-docs.sgml 2009-05-05 20:07:22 UTC (rev 29926)
+++ libexo/trunk/docs/reference/exo-docs.sgml 2009-05-05 21:39:22 UTC (rev 29927)
@@ -12,6 +12,8 @@
<!ENTITY exo-wrap-table SYSTEM "xml/exo-wrap-table.xml">
<!ENTITY exo-cell-renderer-ellipsized-text SYSTEM "xml/exo-cell-renderer-ellipsized-text.xml">
<!ENTITY exo-cell-renderer-icon SYSTEM "xml/exo-cell-renderer-icon.xml">
+<!ENTITY exo-job SYSTEM "xml/exo-job.xml">
+<!ENTITY exo-simple-job SYSTEM "xml/exo-simple-job.xml">
<!ENTITY exo-gdk-pixbuf-extensions SYSTEM "xml/exo-gdk-pixbuf-extensions.xml">
<!ENTITY exo-gobject-extensions SYSTEM "xml/exo-gobject-extensions.xml">
<!ENTITY exo-gtk-extensions SYSTEM "xml/exo-gtk-extensions.xml">
@@ -50,6 +52,11 @@
<holder>os-cillation e.K.</holder>
</copyright>
+ <copyright>
+ <year>2009</year>
+ <holder>Xfce Development Team</holder>
+ </copyright>
+
<legalnotice id="legalnotice">
<para>
Permission is granted to copy, distribute and/or modify this document
@@ -72,6 +79,13 @@
<jobtitle>Software developer</jobtitle>
</affiliation>
</author>
+ <author>
+ <firstname>Jannis</firstname>
+ <surname>Pohlmann</surname>
+ <affiliation>
+ <address><email>jannis at xfce.org</email></address>
+ </affiliation>
+ </author>
</authorgroup>
</bookinfo>
@@ -254,6 +268,22 @@
&exo-cell-renderer-icon;
</part>
+ <part id="exo-jobs">
+ <title>Framework for threaded/asynchronous jobs</title>
+
+ <para>
+ <link linkend="ExoJob">ExoJob</link> provides a simple way to deal with threaded/asynchronous operations (called jobs here).
+ It can be used to wrap any kind of blocking function calls like file operations or web service communication. It can be
+ subclassed to add additional signals for progress information or password requests.
+ <link linkend="ExoSimpleJob">ExoSimpleJob</link> is useful in situations where you don't need additional signals. It takes
+ a <link linkend="ExoSimpleJobFunc">ExoSimpleJobFunc</link> callback and creates a job so one doesn't have to subclass
+ <link linkend="ExoJob">ExoJob</link> just to execute a single function asynchronously.
+ </para>
+
+ &exo-job;
+ &exo-simple-job;
+ </part>
+
<part id="exo-extensions">
<title>Extensions to existing frameworks</title>
Modified: libexo/trunk/docs/reference/exo-sections.txt
===================================================================
--- libexo/trunk/docs/reference/exo-sections.txt 2009-05-05 20:07:22 UTC (rev 29926)
+++ libexo/trunk/docs/reference/exo-sections.txt 2009-05-05 21:39:22 UTC (rev 29927)
@@ -327,6 +327,53 @@
<SECTION>
+<FILE>exo-job</FILE>
+<TITLE>ExoJob</TITLE>
+ExoJob
+exo_job_launch
+exo_job_cancel
+exo_job_is_cancelled
+exo_job_get_cancellable
+exo_job_set_error_if_cancelled
+exo_job_emit
+exo_job_info_message
+exo_job_percent
+<SUBSECTION Standard>
+ExoJobPrivate
+ExoJobClass
+EXO_TYPE_JOB
+EXO_JOB
+EXO_JOB_CLASS
+EXO_IS_JOB
+EXO_IS_JOB_CLASS
+EXO_JOB_GET_CLASS
+<SUBSECTION Private>
+exo_job_get_type
+</SECTION>
+
+
+
+<SECTION>
+<FILE>exo-simple-job</FILE>
+<TITLE>ExoSimpleJob</TITLE>
+ExoSimpleJob
+ExoSimpleJobFunc
+exo_simple_job_launch
+<SUBSECTION Standard>
+ExoSimpleJobClass
+EXO_TYPE_SIMPLE_JOB
+EXO_SIMPLE_JOB
+EXO_SIMPLE_JOB_CLASS
+EXO_IS_SIMPLE_JOB
+EXO_IS_SIMPLE_JOB_CLASS
+EXO_SIMPLE_JOB_GET_CLASS
+<SUBSECTION Private>
+exo_simple_job_get_type
+</SECTION>
+
+
+
+<SECTION>
<FILE>exo-gdk-pixbuf-extensions</FILE>
<TITLE>Extensions to gdk-pixbuf</TITLE>
exo_gdk_pixbuf_colorize
Added: libexo/trunk/docs/reference/tmpl/exo-job.sgml
===================================================================
--- libexo/trunk/docs/reference/tmpl/exo-job.sgml (rev 0)
+++ libexo/trunk/docs/reference/tmpl/exo-job.sgml 2009-05-05 21:39:22 UTC (rev 29927)
@@ -0,0 +1,140 @@
+<!-- ##### SECTION Title ##### -->
+ExoJob
+
+<!-- ##### SECTION Short_Description ##### -->
+Base class for threaded/asynchronous jobs
+
+<!-- ##### SECTION Long_Description ##### -->
+<para>
+<link linkend="ExoJob">ExoJob</link> is an abstract base class intended to wrap threaded/asynchronous
+operations (called jobs here). It was written because the ways of dealing with threads provided by
+GLib were too low-level and not exactly object-oriented.
+
+It can be used to wrap any kind of long-running or possibly-blocking operation, like file operations
+or communication with web services. The benefit of using <link linkend="ExoJob">ExoJob</link> is that
+you get an object associated with an operation. After creating the job you can connect to signals like
+<link linkend="ExoJob::error">"error"</link> or
+<link linkend="ExoJob::percent">"percent"</link>. This design integrates very well in the
+usual object-oriented design of applications based on GLib.
+</para>
+
+<!-- ##### SECTION See_Also ##### -->
+<para>
+<link linkend="ExoSimpleJob">ExoSimpleJob</link>
+</para>
+
+<!-- ##### SECTION Stability_Level ##### -->
+
+
+<!-- ##### STRUCT ExoJob ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### SIGNAL ExoJob::error ##### -->
+<para>
+
+</para>
+
+ at exojob: the object which received the signal.
+ at arg1:
+
+<!-- ##### SIGNAL ExoJob::finished ##### -->
+<para>
+
+</para>
+
+ at exojob: the object which received the signal.
+
+<!-- ##### SIGNAL ExoJob::info-message ##### -->
+<para>
+
+</para>
+
+ at exojob: the object which received the signal.
+ at arg1:
+
+<!-- ##### SIGNAL ExoJob::percent ##### -->
+<para>
+
+</para>
+
+ at exojob: the object which received the signal.
+ at arg1:
+
+<!-- ##### FUNCTION exo_job_launch ##### -->
+<para>
+
+</para>
+
+ at job:
+ at Returns:
+
+
+<!-- ##### FUNCTION exo_job_cancel ##### -->
+<para>
+
+</para>
+
+ at job:
+
+
+<!-- ##### FUNCTION exo_job_is_cancelled ##### -->
+<para>
+
+</para>
+
+ at job:
+ at Returns:
+
+
+<!-- ##### FUNCTION exo_job_get_cancellable ##### -->
+<para>
+
+</para>
+
+ at job:
+ at Returns:
+
+
+<!-- ##### FUNCTION exo_job_set_error_if_cancelled ##### -->
+<para>
+
+</para>
+
+ at job:
+ at error:
+ at Returns:
+
+
+<!-- ##### FUNCTION exo_job_emit ##### -->
+<para>
+
+</para>
+
+ at job:
+ at signal_id:
+ at signal_detail:
+ at Varargs:
+
+
+<!-- ##### FUNCTION exo_job_info_message ##### -->
+<para>
+
+</para>
+
+ at job:
+ at format:
+ at Varargs:
+
+
+<!-- ##### FUNCTION exo_job_percent ##### -->
+<para>
+
+</para>
+
+ at job:
+ at percent:
+
+
Added: libexo/trunk/docs/reference/tmpl/exo-simple-job.sgml
===================================================================
--- libexo/trunk/docs/reference/tmpl/exo-simple-job.sgml (rev 0)
+++ libexo/trunk/docs/reference/tmpl/exo-simple-job.sgml 2009-05-05 21:39:22 UTC (rev 29927)
@@ -0,0 +1,47 @@
+<!-- ##### SECTION Title ##### -->
+ExoSimpleJob
+
+<!-- ##### SECTION Short_Description ##### -->
+
+
+<!-- ##### SECTION Long_Description ##### -->
+<para>
+
+</para>
+
+<!-- ##### SECTION See_Also ##### -->
+<para>
+
+</para>
+
+<!-- ##### SECTION Stability_Level ##### -->
+
+
+<!-- ##### STRUCT ExoSimpleJob ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### USER_FUNCTION ExoSimpleJobFunc ##### -->
+<para>
+
+</para>
+
+ at job:
+ at param_values:
+ at error:
+ at Returns:
+
+
+<!-- ##### FUNCTION exo_simple_job_launch ##### -->
+<para>
+
+</para>
+
+ at func:
+ at n_param_values:
+ at Varargs:
+ at Returns:
+
+
Modified: libexo/trunk/exo/exo-job.c
===================================================================
--- libexo/trunk/exo/exo-job.c 2009-05-05 20:07:22 UTC (rev 29926)
+++ libexo/trunk/exo/exo-job.c 2009-05-05 21:39:22 UTC (rev 29927)
@@ -145,15 +145,16 @@
* ExoJob::finished:
* @job : an #ExoJob.
*
- * This signal will be automatically emitted once the
- * @job finishes its execution, no matter whether @job
- * completed successfully or was cancelled by the
- * user.
+ * This signal will be automatically emitted once the @job finishes
+ * its execution, no matter whether @job completed successfully or
+ * was cancelled by the user.
**/
job_signals[FINISHED] =
g_signal_new (I_("finished"),
G_TYPE_FROM_CLASS (klass),
- G_SIGNAL_NO_HOOKS, 0, NULL, NULL,
+ G_SIGNAL_NO_HOOKS,
+ G_STRUCT_OFFSET (ExoJobClass, finished),
+ NULL, NULL,
g_cclosure_marshal_VOID__VOID,
G_TYPE_NONE, 0);
@@ -162,18 +163,18 @@
* @job : an #ExoJob.
* @message : information to be displayed about @job.
*
- * This signal is emitted to display information about the
- * @job. Examples of messages are "Preparing..." or
- * "Cleaning up...".
+ * This signal is emitted to display information about the * @job.
+ * Examples of messages are "Preparing..." or "Cleaning up...".
*
- * The @message is garanteed to contain valid UTF-8, so
- * it can be displayed by #GtkWidget<!---->s out of the
- * box.
+ * The @message is garanteed to contain valid UTF-8, so it can be
+ * displayed by #GtkWidget<!---->s out of the box.
**/
job_signals[INFO_MESSAGE] =
g_signal_new (I_("info-message"),
G_TYPE_FROM_CLASS (klass),
- G_SIGNAL_NO_HOOKS, 0, NULL, NULL,
+ G_SIGNAL_NO_HOOKS,
+ G_STRUCT_OFFSET (ExoJobClass, info_message),
+ NULL, NULL,
g_cclosure_marshal_VOID__STRING,
G_TYPE_NONE, 1, G_TYPE_STRING);
@@ -183,13 +184,15 @@
* @percent : the percentage of completeness.
*
* This signal is emitted to present the state of the overall
- * progress. The @percent value is garantied to be in the
- * range 0.0 to 100.0.
+ * progress. The @percent value is garantied to be in the range 0.0
+ * to 100.0.
**/
job_signals[PERCENT] =
g_signal_new (I_("percent"),
G_TYPE_FROM_CLASS (klass),
- G_SIGNAL_NO_HOOKS, 0, NULL, NULL,
+ G_SIGNAL_NO_HOOKS,
+ G_STRUCT_OFFSET (ExoJobClass, percent),
+ NULL, NULL,
g_cclosure_marshal_VOID__DOUBLE,
G_TYPE_NONE, 1, G_TYPE_DOUBLE);
}
@@ -220,6 +223,18 @@
+/**
+ * exo_job_finish:
+ * @job : an #ExoJob.
+ * @result : the #GSimpleAsyncResult of the job.
+ * @error : return location for errors.
+ *
+ * Finishes the execution of an operation by propagating errors
+ * from the @result into @error.
+ *
+ * Return value: %TRUE if there was no error during the operation,
+ * %FALSE otherwise.
+ **/
static gboolean
exo_job_finish (ExoJob *job,
GSimpleAsyncResult *result,
@@ -234,6 +249,15 @@
+/**
+ * exo_job_async_ready:
+ * @object : an #ExoJob.
+ * @result : the #GAsyncResult of the job.
+ *
+ * This function is called by the #GIOScheduler at the end of the
+ * operation. It checks if there were errors during the operation
+ * and emits "error" and "finished" signals.
+ **/
static void
exo_job_async_ready (GObject *object,
GAsyncResult *result)
@@ -260,6 +284,19 @@
+/**
+ * exo_job_scheduler_job_func:
+ * @scheduler_job : the #GIOSchedulerJob running the operation.
+ * @cancellable : the #GCancellable associated with the job.
+ * @user_data : a #GSimpleAsyncResult.
+ *
+ * This function is called by the #GIOScheduler to execute the
+ * operation associated with the job. It basically calls the
+ * ExoJobClass#execute function.
+ *
+ * Return value: %FALSE, to stop the thread at the end of the
+ * operation.
+ **/
static gboolean
exo_job_scheduler_job_func (GIOSchedulerJob *scheduler_job,
GCancellable *cancellable,
@@ -292,6 +329,16 @@
+/**
+ * exo_job_emit_valist_in_mainloop:
+ * @user_data : an #ExoJobSignalData.
+ *
+ * Called from the main loop of the application to emit the signal
+ * specified by the @user_data.
+ *
+ * Return value: %FALSE, to keep the function from being called
+ * multiple times in a row.
+ **/
static gboolean
exo_job_emit_valist_in_mainloop (gpointer user_data)
{
@@ -304,6 +351,20 @@
}
+/**
+ * exo_job_emit_valist:
+ * @job : an #ExoJob.
+ * @signal_id : the signal id.
+ * @signal_detail : the signal detail.
+ * @var_args : a list of parameters to be passed to the signal,
+ * followed by a location for the return value. If the
+ * return type of the signal is G_TYPE_NONE, the return
+ * value location can be omitted.
+ *
+ * Send a the signal with the given @signal_id and @signal_detail to the
+ * main loop of the application and waits for the listeners to handle
+ * it.
+ **/
static void
exo_job_emit_valist (ExoJob *job,
guint signal_id,
@@ -330,6 +391,17 @@
+/**
+ * exo_job_error:
+ * @job : an #ExoJob.
+ * @error : a #GError.
+ *
+ * Emits the "error" signal and passes the @error to it so that the
+ * application can handle it (e.g. by displaying an error dialog).
+ *
+ * This function should never be called from outside the application's
+ * main loop.
+ **/
static void
exo_job_error (ExoJob *job,
GError *error)
@@ -342,6 +414,16 @@
+/**
+ * exo_job_finished:
+ * @job : an #ExoJob.
+ *
+ * Emits the "finished" signal to notify listeners of the end of the
+ * operation.
+ *
+ * This function should never be called from outside the application's
+ * main loop.
+ **/
static void
exo_job_finished (ExoJob *job)
{
@@ -355,12 +437,14 @@
* exo_job_launch:
* @job : an #ExoJob.
*
- * This functions schedules @job to be run as soon as possible, in a
- * separate thread.
+ * This functions schedules the @job to be run as soon as possible, in
+ * a separate thread. The caller can then connect to the signals of the
+ * returned #ExoJob in order to be notified on errors, progress updates
+ * and the end of the operation.
*
- * Return value: a pointer to @job.
+ * Return value: the @job itself.
**/
-ExoJob*
+ExoJob *
exo_job_launch (ExoJob *job)
{
GSimpleAsyncResult *result;
@@ -424,6 +508,15 @@
+/**
+ * exo_job_get_cancellable:
+ * @job : an #ExoJob.
+ *
+ * Returns the #GCancellable that can be used to cancel the @job.
+ *
+ * Return value: the #GCancellable associated with the @job. It
+ * is owned by the @job and must not be released.
+ **/
GCancellable *
exo_job_get_cancellable (const ExoJob *job)
{
@@ -433,6 +526,22 @@
+/**
+ * exo_job_set_error_if_cancelled:
+ * @job : an #ExoJob.
+ * @error : error to be set if the @job was cancelled.
+ *
+ * Sets the @error if the @job was cancelled. This is a convenience
+ * function that is equivalent to
+ * <informalexample><programlisting>
+ * GCancellable *cancellable;
+ * cancellable = exo_job_get_cancllable (job);
+ * g_cancellable_set_error_if_cancelled (cancellable, error);
+ * </programlisting></informalexample>
+ *
+ * Return value: %TRUE if the job was cancelled and @error is now set,
+ * %FALSE otherwise.
+ **/
gboolean
exo_job_set_error_if_cancelled (ExoJob *job,
GError **error)
@@ -443,6 +552,19 @@
+/**
+ * exo_job_emit:
+ * @job : an #ExoJob.
+ * @signal_id : the signal id.
+ * @signal_detail : the signal detail.
+ * ... : a list of parameters to be passed to the signal,
+ * followed by a location for the return value. If the
+ * return type of the signal is G_TYPE_NONE, the return
+ * value location can be omitted.
+ *
+ * Sends the signal with @signal_id and @signal_id to the application's
+ * main loop and waits for listeners to handle it.
+ **/
void
exo_job_emit (ExoJob *job,
guint signal_id,
@@ -460,6 +582,15 @@
+/**
+ * exo_job_info_message:
+ * @job : an #ExoJob.
+ * @format : a format string.
+ * ... : parameters for the format string.
+ *
+ * Generates and emits an "info-message" signal and sends it to the
+ * application's main loop.
+ **/
void
exo_job_info_message (ExoJob *job,
const gchar *format,
@@ -482,6 +613,14 @@
+/**
+ * exo_job_percent:
+ * @job : an #ExoJob.
+ * @percent : percentage of completeness of the operation.
+ *
+ * Emits a "percent" signal and sends it to the application's main
+ * loop. Also makes sure that @percent is between 0.0 and 100.0.
+ **/
void
exo_job_percent (ExoJob *job,
gdouble percent)
Modified: libexo/trunk/exo/exo-simple-job.c
===================================================================
--- libexo/trunk/exo/exo-simple-job.c 2009-05-05 20:07:22 UTC (rev 29926)
+++ libexo/trunk/exo/exo-simple-job.c 2009-05-05 21:39:22 UTC (rev 29927)
@@ -163,8 +163,8 @@
* @... : a list of #GType and parameter pairs (exactly
* @n_param_values pairs) that are passed to @func.
*
- * Allocates a new #ExoSimpleJob, which executes the specified
- * @func with the specified parameters.
+ * Allocates a new #ExoJob which executes the specified @func with
+ * the specified parameters.
*
* An example could be:
*
More information about the Xfce4-commits
mailing list