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 <jan...@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 <jan...@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 <jan...@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>jan...@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> + +...@exojob: the object which received the signal. +...@arg1: + +<!-- ##### SIGNAL ExoJob::finished ##### --> +<para> + +</para> + +...@exojob: the object which received the signal. + +<!-- ##### SIGNAL ExoJob::info-message ##### --> +<para> + +</para> + +...@exojob: the object which received the signal. +...@arg1: + +<!-- ##### SIGNAL ExoJob::percent ##### --> +<para> + +</para> + +...@exojob: the object which received the signal. +...@arg1: + +<!-- ##### FUNCTION exo_job_launch ##### --> +<para> + +</para> + +...@job: +...@returns: + + +<!-- ##### FUNCTION exo_job_cancel ##### --> +<para> + +</para> + +...@job: + + +<!-- ##### FUNCTION exo_job_is_cancelled ##### --> +<para> + +</para> + +...@job: +...@returns: + + +<!-- ##### FUNCTION exo_job_get_cancellable ##### --> +<para> + +</para> + +...@job: +...@returns: + + +<!-- ##### FUNCTION exo_job_set_error_if_cancelled ##### --> +<para> + +</para> + +...@job: +...@error: +...@returns: + + +<!-- ##### FUNCTION exo_job_emit ##### --> +<para> + +</para> + +...@job: +...@signal_id: +...@signal_detail: +...@varargs: + + +<!-- ##### FUNCTION exo_job_info_message ##### --> +<para> + +</para> + +...@job: +...@format: +...@varargs: + + +<!-- ##### FUNCTION exo_job_percent ##### --> +<para> + +</para> + +...@job: +...@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> + +...@job: +...@param_values: +...@error: +...@returns: + + +<!-- ##### FUNCTION exo_simple_job_launch ##### --> +<para> + +</para> + +...@func: +...@n_param_values: +...@varargs: +...@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: * _______________________________________________ Xfce4-commits mailing list Xfce4-commits@xfce.org http://foo-projects.org/mailman/listinfo/xfce4-commits