[Evolution-hackers] Submitting background jobs in Camel

[Matthew Barnes <mbarnes redhat com>]

After playing around with CamelSession earlier this week, the whole
CamelSessionThreadMsg API finally annoyed me enough to replace it with
something more modern.

The new API is a lot cleaner, I think, and uses the same mechanisms that
the asynchronous functions use.  Low-priority background jobs can now be
initiated from any thread by calling camel_session_submit_job():

  void camel_session_submit_job (CamelSession *session,
                                 CamelSessionCallback callback,
                                 gpointer user_data,
                                 GDestroyNotify notify);

Regardless of which thread this is called from, the following things
happen next:

  1) A new CamelSession signal -- "job-started" -- is emitted from the
     main thread.  (Technically from whatever thread the CamelSession
     was created on, which should be running a main loop.)  This is
     mainly for the benefit of Camel clients like Evolution that want
     to track these jobs.

       void (*job_started) (CamelSession *session,
                            GCancellable *cancellable);

  2) The CamelSessionCallback is invoked on a different thread where
     it's safe to call synchronous functions.  The callback signature
     is nicer than before:

       void (*CamelSessionCallback) (CamelSession *session,
                                     GCancellable *cancellable,
                                     gpointer user_data,
                                     GError **error);

     The GCancellable is actually a CamelOperation, so callbacks can
     push and pop status messages and report progress like normal.  And
     the GError pointer is always non-NULL, so it's safe to dereference
     if needed to check if a GError has been set.

  3) After the CamelSessionCallback returns, another new CamelSession
     signal -- "job-finished" -- is emitted from the same thread that
     emitted "job-started".

       void (*job_finished) (CamelSession *session,
                             GCancellable *cancellable,
                             const GError *error);

  4) Finally the GDestroyNotify is invoked (if one was given) and passed
     the 'user_data' argument so resources can be freed.

Code that was using CamelSessionThreadMsg previously looks significantly
cleaner now, and error handling is improved.  Evolution wraps these jobs
into EActivity objects and treats them as any other activity.