Re: [Evolution-hackers] Camel Manifesto (update)

[Matthew Barnes <mbarnes redhat com>]

I wanted to give a status update on how this is progressing, since some
of you may have noticed me breaking Camel's API with gleeful abandon
since the 2.31 development cycle began.

My initial roadmap is here:
http://mail.gnome.org/archives/evolution-hackers/2009-November/msg00019.html


What's Accomplished
-------------------

- Only <camel/camel.h> may be included from outside of Camel's core.

- The API is slowly being sealed up, with public instance data being
  moved to private structs, along with new accessor functions and in
  some cases GObject properties.  I'm working on this incrementally.

- CamelObject is now a GObject subclass, and Camel's old type system is
  completely gone.

- The CamelArg API has been replaced with GObject properties.
  Persistent properties (whose values are saved to the object's binary
  state file) are implemented by extending GParamFlags with a new flag
  (CAMEL_PARAM_PERSISTENT) which you can specify when registering the
  GObject property.  camel_object_state_read/write() query the object
  class for properties with this flag.

  We currently only use state files to save a handful of booleans,
  so I've dropped support for other types until we actually need more.
  In the distant future I may kill off binary state files completely
  and delegate the job to EShellView's "state" key file.

- CamelObject events have been replaced by GObject signals.


Short Term Goals
----------------

- Replace CamelException with GError.  I already have this mostly done
  on a branch.  It's straight-forward busywork except for one issue:

  Poor error handling often leads to multiple errors piling up on a
  single exception instance.  I consider this a programming error
  regardless of how the exception mechanism handles it.  GError handles
  this by accepting the first error and rejecting subsequent attempts to
  set an error with a run-time warning (unless the GError is explicitly
  cleared).  CamelException just silently overwrites previous errors
  with new errors.

  In the coming days I'll be committing a patch to make CamelException
  behave like GError in this respect.  I'm hoping this will expose some
  of more egregious error handling issues in Camel providers, but the
  truth is we'll probably be hunting these down for some time.  Once
  things are stable under the new CamelException semantics, the GError
  transition should proceed with minimal disruption.

- I would like for all blocking methods in Camel to explicitly take a
  GCancellable or CamelOperation argument, similar to GIO.  (Turning
  CamelOperation into a GCancellable subclass seems like a good fit.)
  This will happen on a branch for two reasons: 1) not exactly sure
  how to get there from here yet, so I'll need to experiment a bit,
  and 2) I may be blocked on the TLS support for GIO since SSL TCP
  streams need a secure file descriptor to support cancellations,
  which GCancellable does not yet offer.


Long-Term Goals
---------------

- All blocking methods in Camel will have corresponding "async" and
  "finish" methods, whose default implementation will spawn a thread,
  run the synchronous method, and pass the result to the user-supplied
  GAsyncReadyCallback in the main thread.  This closely follows the
  asynchronous pattern in GIO.

  This approach avoids the need to rewrite all Camel providers to be
  asynchronous, but they will be free to override the async methods if
  they so choose.  There may be cases where it's more natural to do an
  operation asynchronously than synchronously.

- Once all of this is in place and TLS support has landed in GIO, GIO
  streams will replace CamelStreams.

- In the far distant future I'd like to convert all the MIME filters
  to the new GConverter data conversion interface for GIO streams, and
  maybe offer up a few of them to GIO itself.


The short-term goals are a priority for 3.0, the long-term goals are
just stuff I'm planning for some future Evolution 3.x release.


Matthew Barnes