Debian Codegraph @

src/job/fm-job.h

raw
1 /*
2 * fm-job.h
3 *
4 * Copyright 2009 PCMan <[email protected]>
5 * Copyright 2012-2013 Andriy Grytsenko (LStranger) <[email protected]>
6 *
7 * This file is a part of the Libfm library.
8 *
9 * This library is free software; you can redistribute it and/or
10 * modify it under the terms of the GNU Lesser General Public
11 * License as published by the Free Software Foundation; either
12 * version 2.1 of the License, or (at your option) any later version.
13 *
14 * This library is distributed in the hope that it will be useful,
15 * but WITHOUT ANY WARRANTY; without even the implied warranty of
16 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
17 * Lesser General Public License for more details.
18 *
19 * You should have received a copy of the GNU Lesser General Public
20 * License along with this library; if not, write to the Free Software
21 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
22 */
23
24
25 #ifndef __FM_JOB_H__
26 #define __FM_JOB_H__
27
28 #include <glib-object.h>
29 #include <gio/gio.h>
30 #include <stdarg.h>
31
32 #include "fm-seal.h"
33
34 /* If we're not using GNU C, elide __attribute__ */
35 #ifndef __GNUC__
36 # define __attribute__(x)
37 #endif
38
39 G_BEGIN_DECLS
40
41 #define FM_TYPE_JOB (fm_job_get_type())
42 #define FM_JOB(obj) (G_TYPE_CHECK_INSTANCE_CAST((obj),\
43 FM_TYPE_JOB, FmJob))
44 #define FM_JOB_CLASS(klass) (G_TYPE_CHECK_CLASS_CAST((klass),\
45 FM_TYPE_JOB, FmJobClass))
46 #define FM_IS_JOB(obj) (G_TYPE_CHECK_INSTANCE_TYPE((obj),\
47 FM_TYPE_JOB))
48 #define FM_IS_JOB_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE((klass),\
49 FM_TYPE_JOB))
50
51 typedef struct _FmJob FmJob;
52 typedef struct _FmJobClass FmJobClass;
53
54 typedef gpointer (*FmJobCallMainThreadFunc)(FmJob* job, gpointer user_data);
55
56 /**
57 * FmJobErrorSeverity
58 * @FM_JOB_ERROR_WARNING: not an error, just a warning
59 * @FM_JOB_ERROR_MILD: no big deal, can be ignored most of the time
60 * @FM_JOB_ERROR_MODERATE: moderate errors
61 * @FM_JOB_ERROR_SEVERE: severe errors, whether to abort operation depends on error handlers
62 * @FM_JOB_ERROR_CRITICAL: critical errors, the operation is aborted
63 */
64 typedef enum {
65 FM_JOB_ERROR_WARNING,
66 FM_JOB_ERROR_MILD,
67 FM_JOB_ERROR_MODERATE,
68 FM_JOB_ERROR_SEVERE,
69 FM_JOB_ERROR_CRITICAL
70 } FmJobErrorSeverity;
71
72 /**
73 * FmJobErrorAction
74 * @FM_JOB_CONTINUE: ignore the error and continue remaining work
75 * @FM_JOB_RETRY: retry the previously failed operation. (not every kind of job support this)
76 * @FM_JOB_ABORT: abort the whole job
77 *
78 * The action that should be performed after error happened.
79 * Usually chosen by user.
80 */
81 typedef enum {
82 FM_JOB_CONTINUE,
83 FM_JOB_RETRY,
84 FM_JOB_ABORT
85 } FmJobErrorAction;
86
87 struct _FmJob
88 {
89 /*< private >*/
90 GObject parent;
91 /* booleans but need unlocked access */
92 sig_atomic_t FM_SEAL(cancel);
93 sig_atomic_t FM_SEAL(running);
94
95 /* optional, should be created if the job uses gio */
96 GCancellable* FM_SEAL(cancellable);
97 /* used for suspending the job */
98 gboolean FM_SEAL(suspended);
99 #if GLIB_CHECK_VERSION(2, 32, 0)
100 GRecMutex FM_SEAL(stop);
101 #else
102 GStaticRecMutex FM_SEAL(stop);
103 #endif
104
105 gpointer _reserved1;
106 gpointer _reserved2;
107 };
108
109 /**
110 * FmJobClass:
111 * @parent_class: the parent class
112 * @finished: the class closure for the #FmJob::finished signal.
113 * @error: the class closure for the #FmJob::error signal.
114 * @cancelled: the class closure for the #FmJob::cancelled signal.
115 * @ask: the class closure for the #FmJob::ask signal.
116 * @run_async: the @run_async function called to create a thread for the
117 * job execution. Returns %TRUE if thread was created successfully.
118 * The most probably should be not overridden by any derived class.
119 * @run: the @run function is called to perform actual job actions. Returns
120 * value that will be returned from call fm_job_run_sync(). Should be
121 * set by any class derived from #FmJob.
122 * @cancel: the @cancel function is called when the job is cancelled.
123 * It can perform some class-specific operations then.
124 */
125 struct _FmJobClass
126 {
127 GObjectClass parent_class;
128
129 /*< public >*/
130 /* the class closures for signals */
131 void (*finished)(FmJob* job);
132 guint (*error)(FmJob* job, GError* err, guint severity);
133 /* guint above are: FmJobErrorAction and FmJobErrorSeverity */
134 void (*cancelled)(FmJob* job);
135 gint (*ask)(FmJob* job, const gchar* question, gchar* const *options);
136
137 /* routines used by methods */
138 gboolean (*run_async)(FmJob* job); /* for fm_job_run_async() */
139 gboolean (*run)(FmJob* job); /* for any fm_job_run_*() */
140 void (*cancel)(FmJob* job); /* for fm_job_cancel() */
141
142 /*< private >*/
143 gpointer _reserved1;
144 };
145
146
147 /* Base type of all file I/O jobs.
148 * not directly called by applications. */
149
150 GType fm_job_get_type (void);
151
152 /* return TRUE if the job is already cancelled */
153 gboolean fm_job_is_cancelled(FmJob* job);
154
155 /* return TRUE if the job is still running */
156 gboolean fm_job_is_running(FmJob* job);
157
158
159 /* Run a job asynchronously in another working thread, and
160 * emit 'finished' signal in the main thread after its termination.
161 * The default implementation of FmJob::run_async() create a working
162 * thread in thread pool, and calls FmJob::run() in it.
163 */
164 gboolean fm_job_run_async(FmJob* job) __attribute__((warn_unused_result));
165
166 /* Run a job in current thread in a blocking fashion.
167 * A job running synchronously with this function should be unrefed
168 * later with g_object_unref when no longer needed. */
169 gboolean fm_job_run_sync(FmJob* job);
170
171 /* Run a job in current thread in a blocking fashion and an additional
172 * mainloop being created to prevent blocking of user interface.
173 * A job running synchronously with this function should be unrefed
174 * later with g_object_unref when no longer needed. */
175 gboolean fm_job_run_sync_with_mainloop(FmJob* job);
176
177 /* Cancel the running job. can be called from any thread. */
178 void fm_job_cancel(FmJob* job);
179
180 /* Following APIs are private to FmJob and should only be used in the
181 * implementation of classes derived from FmJob.
182 * Besides, they should be called from working thread only if another
183 * isn't stated. */
184 gpointer fm_job_call_main_thread(FmJob* job, FmJobCallMainThreadFunc func,
185 gpointer user_data);
186
187 /* Used by derived classes to implement FmJob::run() using gio inside.
188 * This API tried to initialize a GCancellable object for use with gio and
189 * should only be called once in the constructor of derived classes which
190 * require the use of GCancellable. */
191 void fm_job_init_cancellable(FmJob* job);
192
193 /* Used to implement FmJob::run() using gio inside.
194 * This API tried to initialize a GCancellable object for use with gio.
195 * Prior to calling this API, fm_job_init_cancellable() should be
196 * called first to initiate GCancellable object. Otherwise NULL is returned. */
197 GCancellable* fm_job_get_cancellable(FmJob* job);
198
199 /* Let the job use an existing cancellable object.
200 * This can be used when you wish to share a cancellable object
201 * among different jobs.
202 * This should only be called before the job is launched. */
203 void fm_job_set_cancellable(FmJob* job, GCancellable* cancellable);
204
205 /* only call this at the end of working thread if you're going to
206 * override FmJob::run_async() and use your own multi-threading mechnism. */
207 void fm_job_finish(FmJob* job);
208
209 /* fm_job_emit_finished() and fm_job_emit_cancelled() can be called only
210 * from main loop thread, You should never use it since FmJob API do it. */
211 /* void fm_job_emit_finished(FmJob* job); */
212
213 /* void fm_job_emit_cancelled(FmJob* job); */
214
215 /* Emit an 'error' signal to notify the main thread when an error occurs.
216 * The return value of this function is the return value returned by
217 * the connected signal handlers.
218 * If severity is FM_JOB_ERROR_CRITICAL, the returned value is ignored and
219 * fm_job_cancel() is called to abort the job. Otherwise, the signal
220 * handler of this error can return FM_JOB_RETRY to ask for retrying the
221 * failed operation, return FM_JOB_CONTINUE to ignore the error and
222 * continue the remaining job, or return FM_JOB_ABORT to abort the job.
223 * If FM_JOB_ABORT is returned by the signal handler, fm_job_cancel
224 * will be called in fm_job_emit_error().
225 */
226 FmJobErrorAction fm_job_emit_error(FmJob* job, GError* err, FmJobErrorSeverity severity);
227
228 gint fm_job_ask(FmJob* job, const char* question, ...);
229 gint fm_job_askv(FmJob* job, const char* question, gchar* const *options);
230 gint fm_job_ask_valist(FmJob* job, const char* question, va_list options);
231
232 gboolean fm_job_pause(FmJob *job);
233 void fm_job_resume(FmJob *job);
234
235 G_END_DECLS
236
237 #endif /* __FM-JOB_H__ */