Top | ![]() |
![]() |
![]() |
![]() |
gpointer | (*FmJobCallMainThreadFunc) () |
gboolean | fm_job_is_cancelled () |
gboolean | fm_job_is_running () |
gboolean | fm_job_run_async () |
gboolean | fm_job_run_sync () |
gboolean | fm_job_run_sync_with_mainloop () |
void | fm_job_cancel () |
gpointer | fm_job_call_main_thread () |
void | fm_job_init_cancellable () |
GCancellable * | fm_job_get_cancellable () |
void | fm_job_set_cancellable () |
void | fm_job_finish () |
FmJobErrorAction | fm_job_emit_error () |
gint | fm_job_ask () |
gint | fm_job_askv () |
gint | fm_job_ask_valist () |
gboolean | fm_job_pause () |
void | fm_job_resume () |
GObject ╰── FmJob ├── FmDeepCountJob ├── FmDirListJob ├── FmFileInfoJob ╰── FmFileOpsJob
include
: libfm/fm.h
The FmJob can be used to create asynchronous jobs performing some
time-consuming tasks in another worker thread.
To run a FmJob in another thread you simply call
fm_job_run_async()
, and then the task will be done in another
worker thread. Later, when the job is finished, “finished” signal is
emitted. When the job is still running, it's possible to cancel it
from main thread by calling fm_job_cancel()
. Then, “cancelled” signal
will be emitted before emitting “finished” signal. You can also run
the job in blocking fashion instead of running it asynchronously by
calling fm_job_run_sync()
.
gboolean
fm_job_is_cancelled (FmJob *job
);
Checks if the job is already cancelled.
Since: 0.1.9
gboolean
fm_job_is_running (FmJob *job
);
Checks if the job is still running.
Since: 0.1.9
gboolean
fm_job_run_async (FmJob *job
);
Starts the job
asyncronously creating new thread. If job starts
successfully then the “finished” signal will be emitted when
job
is either succeeded or was cancelled. If job
could not be
started then “cancelled” signal is emitted before return from
this function.
Since: 0.1.0
gboolean
fm_job_run_sync (FmJob *job
);
Runs the job
in current thread in a blocking fashion. The job will
emit either “cancelled” signal if job was cancelled
or “finished” signal if it finished successfully.
Since: 0.1.0
gboolean
fm_job_run_sync_with_mainloop (FmJob *job
);
Runs the job
in current thread in a blocking fashion and an additional
mainloop being created to prevent blocking of user interface. If job
started successfully then “finished” signal is emitted when job
is either succeeded or was cancelled.
Note: using this API from within GTK main loop will lead to deadlock
therefore if it is a GTK application then caller should unlock GDK
threads before calling this API and lock them back after return from
it. This statement is valid for any GTK application that uses locks.
Since: 0.1.1
gpointer fm_job_call_main_thread (FmJob *job
,FmJobCallMainThreadFunc func
,gpointer user_data
);
Stops calling thread, waits main thread for idle, passes user_data
to callback func
in main thread, gathers result of callback, and
returns it to caller.
This APIs is private to FmJob and should only be used in the implementation of classes derived from FmJob.
This function should be called from working thread only.
job |
the job that calls main thread |
|
func |
callback to run from main thread |
|
user_data |
user data for the callback |
Since: 0.1.0
void
fm_job_init_cancellable (FmJob *job
);
Used by derived classes to implement FmJobClass:
using gio inside.
This API tries to initialize a GCancellable object for use with gio and
should only be called once in the constructor of derived classes which
require the use of GCancellable.run()
This APIs is private to FmJob and should only be used in the implementation of classes derived from FmJob.
Since: 0.1.0
GCancellable *
fm_job_get_cancellable (FmJob *job
);
Get an existing GCancellable object from job
for use with gio in
another job by calling fm_job_set_cancellable()
.
This can be used when you wish to share a cancellable object
among different jobs.
This APIs is private to FmJob and should only be used in the implementation of classes derived from FmJob.
Since: 0.1.9
void fm_job_set_cancellable (FmJob *job
,GCancellable *cancellable
);
Lets the job to use an existing cancellable
object.
This can be used when you wish to share a cancellable object
among different jobs.
This should only be called before the job
is launched.
This APIs is private to FmJob and should only be used in the implementation of classes derived from FmJob.
Since: 0.1.0
void
fm_job_finish (FmJob *job
);
Schedules the finishing of job. Once this function is called the
job
becomes invalid for the caller and should be not used anymore.
This APIs is private to FmJob and should only be used in the implementation of classes derived from FmJob.
This function should be called from working thread only.
Since: 0.1.0
FmJobErrorAction fm_job_emit_error (FmJob *job
,GError *err
,FmJobErrorSeverity severity
);
Emits an “error” signal in the main thread to notify it when an
error occurs.
The return value of this function is the return value returned by
the connected signal handlers.
If severity
is FM_JOB_ERROR_CRITICAL, the returned value is ignored and
fm_job_cancel()
is called to abort the job. Otherwise, the signal
handler of this error can return FM_JOB_RETRY to ask for retrying the
failed operation, return FM_JOB_CONTINUE to ignore the error and
continue the remaining job, or return FM_JOB_ABORT to abort the job.
If FM_JOB_ABORT is returned by the signal handler, fm_job_cancel()
will be called in fm_job_emit_error()
.
This APIs is private to FmJob and should only be used in the implementation of classes derived from FmJob.
This function should be called from working thread only.
Since: 0.1.0
gint fm_job_ask (FmJob *job
,const char *question
,...
);
Asks the user for some interactions. The user will have a list of available options and should make a choice.
This APIs is private to FmJob and should only be used in the implementation of classes derived from FmJob.
This function should be called from working thread only.
job |
the job that calls main thread |
|
question |
the text to ask the user |
|
... |
list of choices to give the user |
Since: 0.1.0
gint fm_job_askv (FmJob *job
,const char *question
,gchar * const *options
);
Asks the user for some interactions. The user will have a list of available options and should make a choice.
This APIs is private to FmJob and should only be used in the implementation of classes derived from FmJob.
This function should be called from working thread only.
job |
the job that calls main thread |
|
question |
the text to ask the user |
|
options |
list of choices to give the user |
Since: 0.1.0
gint fm_job_ask_valist (FmJob *job
,const char *question
,va_list options
);
Asks the user for some interactions. The user will have a list of available options and should make a choice.
This APIs is private to FmJob and should only be used in the implementation of classes derived from FmJob.
This function should be called from working thread only.
job |
the job that calls main thread |
|
question |
the text to ask the user |
|
options |
list of choices to give the user |
Since: 0.1.0
gboolean
fm_job_pause (FmJob *job
);
Locks execution of job until next call to fm_job_resume()
. This call
may be used from thread different from the thread where the job runs
in. This call may be done again (but have no extra effect) from the
same thread. Any other usage may lead to deadlock.
Since: 1.2.0
void
fm_job_resume (FmJob *job
);
Unlocks execution of job
that was made by previous call to
fm_job_pause()
. This call may be used only from the same thread
where previous fm_job_pause()
was made. Any other usage may lead to
deadlock.
Since: 1.2.0
The action that should be performed after error happened. Usually chosen by user.
struct FmJobClass { GObjectClass parent_class; /* the class closures for signals */ void (*finished)(FmJob* job); guint (*error)(FmJob* job, GError* err, guint severity); /* guint above are: FmJobErrorAction and FmJobErrorSeverity */ void (*cancelled)(FmJob* job); gint (*ask)(FmJob* job, const gchar* question, gchar* const *options); /* routines used by methods */ gboolean (*run_async)(FmJob* job); /* for fm_job_run_async() */ gboolean (*run)(FmJob* job); /* for any fm_job_run_*() */ void (*cancel)(FmJob* job); /* for fm_job_cancel() */ };
the class closure for the “finished” signal. |
||
the class closure for the “error” signal. |
||
the class closure for the “cancelled” signal. |
||
the class closure for the “ask” signal. |
||
the |
||
the |
||
the |
“ask”
signalint user_function (FmJob *job, gpointer question, gpointer options, gpointer user_data)
The “ask” signal is emitted when the job asks for some
user interactions. The user then will have a list of available
options
. If there is more than one handler connected to the
signal then only one of them will receive it.
job |
a job that emitted the signal |
|
question |
(const gchar *) a question to ask user |
|
options |
(gchar* const *) list of choices to ask user |
|
user_data |
user data set when the signal handler was connected. |
Flags: Run Last
Since: 0.1.0
“cancelled”
signalvoid user_function (FmJob *job, gpointer user_data)
The “cancelled” signal is emitted when the job is cancelled or aborted due to critical errors.
job |
a job that emitted the signal |
|
user_data |
user data set when the signal handler was connected. |
Flags: Run First
Since: 0.1.0
“error”
signalguint user_function (FmJob *job, GError *error, guint severity, gpointer user_data)
The “error” signal is emitted when errors happen. A case if more than one handler is connected to this signal is ambiguous.
job |
a job that emitted the signal |
|
error |
an error descriptor |
|
severity |
FmJobErrorSeverity of the error |
|
user_data |
user data set when the signal handler was connected. |
Flags: Run Last
Since: 0.1.0
“finished”
signalvoid user_function (FmJob *job, gpointer user_data)
The “finished” signal is emitted after the job is finished.
The signal is never emitted if the fm_job_run_XXX function
returned FALSE
, in that case the “cancelled” signal will be
emitted instead.
job |
a job that emitted the signal |
|
user_data |
user data set when the signal handler was connected. |
Flags: Run First
Since: 0.1.0