Re: [Evolution-hackers] Some minor Camel API breaks

[Matthew Barnes <mbarnes redhat com>]

On Mon, 2012-08-13 at 19:00 +0100, Philip Withnall wrote:
> This is all great work! Just a point to note: Telepathy uses the
> convention of calling refcounting getters ‘_dup_’ (e.g.
> “camel_session_dup_service()”) rather than ‘_ref_’. This seems better
> (imo) because ‘ref’ could get confused with a reference-count-increasing
> function which _doesn’t_ return the reference. If it’s not too late,
> perhaps Camel could be changed to use this ‘_dup_’ convention instead?

I actually like 'ref' better and am already using it throughout the new
ESource APIs in Evolution-Data-Server.

The lack of consistency across libraries is a little annoying, but I
find this convention easiest to remember:

* foo_get_bar()

  You don't own the returned "bar" and can safely nest the function call
  without leaking resources.

  These functions may not be thread-safe, however.

* foo_dup_bar()

  You own an allocated copy of "bar" and will generally call something
  like bar_free() to release it.

  These functions should always be thread-safe.

* foo_ref_bar()

  You own a new reference on "bar" and will generally call something
  like bar_unref() to release it.

  These functions should always be thread-safe.

* foo_ref()

  This is a self-referencing function.  You own a new reference on "foo"
  and will generally call something like foo_unref() to release it.  In
  all cases I can think of, the function also acts as a pass-through by
  returning the input value.

  These functions are usually thread-safe by way of atomic integer ops.

I think the last two nicely sidestep the confusion over "ref".

Matt