Telepathy-GLib specific coding style

Those policies have been discussed on bug #39189. Those are not global rules we want to apply on all our projects, but rather a compromise given the history of existing telepathy-glib API. They could change in a distant future if we decide it is important to be threadsafe (maybe after porting to gdbus).

Transfer policy

• tp_foo_get_bar() must return the internal pointer/value. No copy is made.
• tp_foo_dup_bar() must return a new ref or deep-copy.
• tp_foo_borrow_bar() should not be used.
• tp_foo_bar_finish() must return a new ref or deep-copy return value and out args.
• Since finish() returns a copy, tpfoo_dup_bar_async() should be prefered over tp_foo_get_bar_async().

Container policy

telepathy-glib uses either GList or GPtrArray, it is left to developer's choice. The most important to keep in mind is to use the most convenient format given the existing APIs. For example it is preferable to return a set of contacts as a GPtrArray because tp_connection_upgrade_contacts_async() takes a C-array + length.

• GPtrArray must always be used in a way that reffing it is enough to keep the container AND its elements, and unreffing it is enough to 'unown' the container AND its elements. In most case this means that the array must own its elements and have a free_func set, and g_ptr_array_free() must never be used. Returning such GPtrArray, if not retunring the internal pointer, must be annotated with "transfer container" and the function name must be tp_foo_dup_bar().
• GHashTable is similar to GPtrArray case.
• When returning a GList, if not returning the internal pointer, it must be deep-copied, annotated with "transfer full", and function name must be tp_foo_dup_bar().

Unsure?

tp_foo_dup_bar() it is!