Unreferencing. The sick tny_folder_iface_uncache has been removed and replaced by an autodetect mechanism

[Philip Van Hoof <spam pvanhoof be>]

Hackers!

The upcoming commit will remove the need for the developer to use
tny_folder_iface_uncache. This is indeed cause of the new API's making
it possible for me (the framework developer) to detect when there's no
more headers being managed (or, visible) in the application.

I did this by (very simply, like all solutions) keeping some sort of
reference count in the folder instance and pinging that instance each
time a header is destroyed.

Something like: 

o. Folder creates a header and increases its header-reference-count
o. Header gets destroyed and decreases the header-reference-count of the folder
o. Header pings the folder
o. Folder checks its header-reference-count, if it's 0 then it uncaches itself

Back when headers where owned by the folder, this wasn't as easy because
the same header instances where reused by all users of the headers. So
headers needed an extra reference count per user and other yadi yada
that made this impossible. Since the new tny_folder_get_headers API the
reference ownership reparents to the TnyListIface. The developer
destroys this instance which will trigger the unreferencing of all the
header instances. 

If now all the logic is right, the folder will eventually get its
header-reference-count on zero. If not, well ... bad luck for your
memory because that means that the memory for all Camel header
information is never destroyed. This indeed means that reference
counting of the headers, messages and components using headers must be
checked carefully: You loose the memory of ALL headers if you leak the
reference count of one header.

But then again. If you would otherwise (without this fix) uncache the
folder to early, things will burn and crash big time somewhere in Camel.
This is not possible anymore.

You can still unreference the TnyFolder instance to often. That will
still burn and crash somewhere in both tinymail and Camel. But that's
just a programming error. 

The tny_folder_iface_uncache was invited to do this often and sounds
harmless. It wasn't harmless.

Case:

Open a folder
Open a message
Close the folder
Close the message


In the "Close the folder" step the developer might have uncached the
folder. The message still uses the header. If the coder would use this
header instance (maybe to craft a reply-to message), the things would
have burned and crashed.


The upcoming commit fixes this. The camelfolder will not be destroyed
until the message is closed (because that unreferences the header too).



-- 
Philip Van Hoof, software developer at x-tend 
home: me at pvanhoof dot be 
gnome: pvanhoof at gnome dot org 
work: vanhoof at x-tend dot be 
http://www.pvanhoof.be - http://www.x-tend.be